From 1199eff6c3e0730fa96e854eda6304db091393d7 Mon Sep 17 00:00:00 2001 From: Lago Date: Tue, 14 Apr 2026 18:46:32 +0000 Subject: [PATCH] Add README with tutorial and connector documentation --- README.md | 212 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..fcdd76a9 --- /dev/null +++ b/README.md @@ -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 -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)