Add README with tutorial and connector documentation
This commit is contained in:
212
README.md
Normal file
212
README.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# Power Apps Code Apps — Part 2: Connectors, Dataverse & Outlook
|
||||
|
||||
> Build a full Outlook-like email client in a code app, wired to real Power Platform connectors.
|
||||
|
||||
This is the second article in the series. Make sure you have completed [Part 1](https://www.thatsagoodquestion.info/power-apps-code-apps) before continuing.
|
||||
|
||||
## What you will build
|
||||
|
||||
A complete email client (Bandeja de entrada, Enviados, Borradores, Papelera) with:
|
||||
- Folder navigation
|
||||
- Email list with unread indicators
|
||||
- Email detail view with reply/forward
|
||||
- Compose modal
|
||||
- Real-time search
|
||||
|
||||
All powered by the Outlook connector — the same connector used by millions of Microsoft 365 users.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Power Apps environment with a licensed user
|
||||
- `pac` CLI installed (`dotnet tool install -g Microsoft.PowerApps.CLI`)
|
||||
- Node.js 18+ and npm
|
||||
- A Microsoft 365 account (for the Outlook connector)
|
||||
- Connections already created in [make.powerapps.com](https://make.powerapps.com)
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Your Code App │
|
||||
│ React UI → Service Layer → Connector Client │
|
||||
│ ↓ │
|
||||
│ ┌─────────────────────────────+ │
|
||||
│ │ Power Platform Connectors │ │
|
||||
│ │ ─────────────────────────── │ │
|
||||
│ │ Outlook │ Dataverse │ … │ │
|
||||
│ └─────────────────────────────+ │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Step 1 — Add a data source (connector)
|
||||
|
||||
The `pac code add-data-source` command wires a connector to your app and auto-generates typed TypeScript model and service files.
|
||||
|
||||
### Get your connection metadata
|
||||
|
||||
**Option A — PAC CLI (recommended)**
|
||||
|
||||
```bash
|
||||
pac connection list
|
||||
```
|
||||
|
||||
You'll see a table:
|
||||
|
||||
| Connection Name | Connection ID | API Name |
|
||||
|---|---|---|
|
||||
| shared_office365 | `aaaaaaaa-0000-...` | `shared_office365` |
|
||||
| shared_outlook | `bbbbbbbb-1111-...` | `shared_outlook` |
|
||||
|
||||
**Option B — Power Apps URL**
|
||||
|
||||
1. Go to [make.powerapps.com](https://make.powerapps.com) → **Data** → **Connections**
|
||||
2. Click your connection
|
||||
3. The URL contains both the **API name** and **Connection ID**:
|
||||
|
||||
```
|
||||
https://make.powerapps.com/connections/aaaaaaa-0000-.../details
|
||||
└──────────────┘ └──────────────┘
|
||||
api name connection id
|
||||
```
|
||||
|
||||
### Add the data source
|
||||
|
||||
```bash
|
||||
pac code add-data-source -a shared_outlook -c aaaaaaaa-0000-1111-bbbb-cccccccccccc
|
||||
```
|
||||
|
||||
After running, you'll find two new files:
|
||||
|
||||
```
|
||||
src/
|
||||
connectors/
|
||||
shared_outlook/
|
||||
OutlookModel.ts ← typed request/response types
|
||||
OutlookService.ts ← service with all connector actions
|
||||
```
|
||||
|
||||
The generated service wraps every action from the connector as a typed TypeScript method. No need to manually craft HTTP calls or worry about auth headers.
|
||||
|
||||
### Dataverse connector
|
||||
|
||||
```bash
|
||||
pac code add-data-source -a shared_commondataservice -c <connection-id> -t accounts -d default
|
||||
```
|
||||
|
||||
This generates `DataverseModel.ts` and `DataverseService.ts` with full type safety for Dataverse tables.
|
||||
|
||||
## Step 2 — Use the connector in your app
|
||||
|
||||
Here's the theoretical model for how code apps interact with connectors:
|
||||
|
||||
```typescript
|
||||
// The Power Platform client library exposes a typed service.
|
||||
// The service is injected or instantiated with your connection reference.
|
||||
import { OutlookService } from '../connectors/shared_outlook';
|
||||
|
||||
const outlook = new OutlookService();
|
||||
|
||||
// All methods return typed Promises — no manual fetch needed
|
||||
const messages = await outlook.getMessages('inbox');
|
||||
const profile = await outlook.getProfile();
|
||||
|
||||
// Actions are also typed
|
||||
await outlook.sendMessage({
|
||||
to: 'colleague@company.com',
|
||||
subject: 'Sprint planning',
|
||||
body: 'Hi, let\'s sync tomorrow...',
|
||||
});
|
||||
```
|
||||
|
||||
### Connection reference pattern
|
||||
|
||||
Rather than binding directly to a user-specific connection, code apps use a **connection reference** — a solution component that points to a connection. This allows:
|
||||
|
||||
- **Environment promotion**: connections change per environment (dev/staging/prod) without code changes
|
||||
- **Managed identity support**: use system-assigned identities instead of user credentials
|
||||
- **Centralised governance**: IT can audit which apps use which connectors
|
||||
|
||||
## Step 3 — Explore the example
|
||||
|
||||
The `src/` directory in this repo contains a complete, working example:
|
||||
|
||||
```
|
||||
src/
|
||||
App.tsx ← main UI (folders, email list, detail, compose)
|
||||
index.css ← dark theme styles
|
||||
main.tsx ← React entry point
|
||||
types/
|
||||
index.ts ← shared TypeScript types
|
||||
services/
|
||||
OutlookService.ts ← mock connector (for demo without real creds)
|
||||
```
|
||||
|
||||
The mock `OutlookService` mirrors the interface of a real generated connector. Swap it for the real generated service and the app works against your actual Outlook data.
|
||||
|
||||
## Step 4 — Run locally
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Opens at `http://localhost:5173`. The app hot-reloads as you edit.
|
||||
|
||||
## Step 5 — Deploy to Power Platform
|
||||
|
||||
```bash
|
||||
pac code deploy
|
||||
```
|
||||
|
||||
This packages the app and registers it in your Power Apps environment. After deploying, add the code app to a solution and publish.
|
||||
|
||||
## How connectors work in code apps (theory)
|
||||
|
||||
Code apps access connectors through the **Power Platform client library**. The client library:
|
||||
|
||||
1. **Discovers available connectors** from the runtime environment
|
||||
2. **Manages authentication** via the user's Microsoft 365 session (single sign-on)
|
||||
3. **Exposes typed service interfaces** generated at add-time
|
||||
4. **Handles pagination, throttling, and error responses** transparently
|
||||
|
||||
This means you call `outlookService.getMessages()` just like any other async function — no base URLs, no API keys, no manual token refresh.
|
||||
|
||||
### Supported connectors
|
||||
|
||||
Code apps support **1,400+ connectors** including:
|
||||
|
||||
| Category | Connectors |
|
||||
|---|---|
|
||||
| Microsoft 365 | Outlook, Teams, SharePoint, OneDrive, Planner |
|
||||
| Dataverse | Common Data Service (Dataverse) |
|
||||
| Data | SQL Server, Dataverse, OData |
|
||||
| SaaS | Salesforce, SAP, ServiceNow, Slack |
|
||||
| Custom | Any standard REST connector |
|
||||
|
||||
### Unsupported connectors
|
||||
|
||||
As of the initial release:
|
||||
|
||||
- Excel Online (Business)
|
||||
- Excel Online (OneDrive)
|
||||
|
||||
## Key differences from canvas apps
|
||||
|
||||
| Aspect | Canvas Apps | Code Apps |
|
||||
|---|---|---|
|
||||
| UI Framework | Power Fx formula bar | React/Vue/Svelte (your choice) |
|
||||
| Connector Access | Built-in connector picker | PAC CLI + typed client library |
|
||||
| Data Model | Implicit, delegation-based | Explicit TypeScript types |
|
||||
| Deployment | Packaged by Power Platform | `pac code deploy` + solution |
|
||||
| CI/CD | Limited | Full git-native workflow |
|
||||
|
||||
## References
|
||||
|
||||
- [How to: Connect your code app to data](https://learn.microsoft.com/en-us/power-apps/developer/code-apps/how-to/connect-to-data) — Microsoft Learn
|
||||
- [Power Apps code apps overview](https://learn.microsoft.com/en-us/power-apps/developer/code-apps/overview) — Microsoft Learn
|
||||
- [Code apps architecture](https://learn.microsoft.com/en-us/power-apps/developer/code-apps/architecture) — Microsoft Learn
|
||||
- [Use CLI to discover, create, and wire connectors](https://learn.microsoft.com/en-us/power-platform/release-plan/2026wave1/power-apps/use-cli-discover-create-wire-connectors-code-apps) — Microsoft Learn
|
||||
- [pac connection list](https://learn.microsoft.com/en-us/power-platform/developer/cli/reference/connection#pac-connection-list) — PAC CLI reference
|
||||
- [pac code add-data-source](https://learn.microsoft.com/en-us/power-platform/developer/cli/reference/code#pac-code-add-data-source) — PAC CLI reference
|
||||
- [Connector classification (DLP)](https://learn.microsoft.com/en-us/power-platform/admin/dlp-connector-classification) — Microsoft Learn
|
||||
- [Part 1 — Power Apps code apps: tutorial, best practices, and production patterns](https://www.thatsagoodquestion.info/power-apps-code-apps)
|
||||
Reference in New Issue
Block a user