Skip to content
This repository was archived by the owner on Nov 5, 2026. It is now read-only.
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -427,3 +427,8 @@ FodyWeavers.xsd
*.msix
*.msm
*.msp

# Sample setup output (ms app init / add data-source); it belongs in your own app repository
samples/*/ms.config.json
samples/*/generated/
samples/*/.ms/
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ See the [Quickstart - CLI](https://go.microsoft.com/fwlink/?LinkId=2368962) to s
## Repository structure

- [`templates/`](templates/) — first-party project templates (currently [`vite8`](templates/vite8), a React + TypeScript + Vite 8 starter).
- [`samples/`](samples/) — complete sample apps you can set up in your own environment. Each sample's README and setup skill walk through copying it into its own folder, `ms app init` (which creates the app's platform-managed repository) and adding its connectors; app data is stored in the browser by default, and the bundled `add-data-source` skill moves it to SharePoint, Dataverse or your own API.
- [`plugins/`](plugins/) — the [`microsoft-managed-apps`](plugins/microsoft-managed-apps) plugin: skills, agents, and hooks for building apps hosted on Copilot Managed Runtime with AI coding agents (works with Claude Code and GitHub Copilot).
- [`.claude-plugin/`](.claude-plugin/) — marketplace manifest (`marketplace.json`) that registers the plugin so agents can install it via `/plugin marketplace add`.

Expand Down
185 changes: 185 additions & 0 deletions samples/CodeFlow/.claude/skills/add-data-source/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,185 @@
---
name: add-data-source
description: Moves this app's data from browser-local storage to a shared backend (SharePoint lists, Dataverse tables, a REST API, or any other store) by adding a storage provider. Use when the user wants app data shared between people or devices, kept outside the browser, or stored in a specific system.
---

# Add a data source

Every read and write of app-owned data in this template goes through one storage interface
(`src/storage/core/types.ts`). By default the `local` provider keeps data in the browser
(`localStorage`). This skill adds another provider and switches the app to it **without
changing UI or domain code**.

## Ground rules

- **Never edit `src/storage/core/`.** It is shared, tested code. Build on it.
- **Never change UI, hooks or domain modules** to make a backend work. If the interface seems
insufficient, stop and explain the gap to the user.
- Generated connector code is imported **only** from `src/connectors/` (an ESLint rule enforces
this). The provider in `src/storage/providers/` depends on that thin wrapper, not on
`generated/` directly, so it can be tested with fakes.
- A provider is finished when `runProviderContract()` passes against it (step 6).
- Authorization belongs to the backend. Configure list/table permissions; never rely on hiding
UI (step 7).

## Step 1: Understand what is stored

1. Read `src/storage/collections.ts`. Every collection is a zod schema plus a name.
2. Run `npm run storage:describe`. It prints each collection as JSON Schema; you will create one
list/table per collection.
3. Note which data uses `provider.kv(...)` (preferences, drafts, UI state). These usually stay
**device-local**, which is the default described in step 5.
4. Ask the user which collections should move (usually all of them) and who should be able to
read and write each one.

## Step 2: Choose the backend

| Backend | Good for | Needs | Reference |
|---|---|---|---|
| **SharePoint lists** | Teams that already use SharePoint; simple setup | A SharePoint site where the user can create lists | `references/sharepoint.md` |
| **Dataverse tables** | Relational/business data; role-based security; large volumes | A Power Platform environment with Dataverse, and the matching licenses | `references/dataverse.md` |
| **Your own API** | Existing systems or databases | A connector (or custom connector) that exposes CRUD operations | `references/custom-api.md` |

If the user has no preference, recommend SharePoint lists for small teams and Dataverse for
anything with roles, auditing or large data.

## Step 3: Provision the backing store

Use the **document-in-a-row** layout for every collection. It maps any record shape onto any
tabular store and keeps the provider generic:

| Column | Type | Purpose |
|---|---|---|
| `RecordKey` | Single line of text, **indexed, unique, required** | Record id (`BackendRow.key`) |
| `Data` | Multiple lines of **plain** text (no rich text, no length cap below ~1 MB) | The record body as JSON |
| *(built-in)* ETag / row version | backend-managed | `BackendRow.etag` |
| *(built-in)* Created / Modified | backend-managed | `createdAt` / `updatedAt` |

Name each list/table after the collection, optionally with an app prefix, e.g. `LearningHub_sessions`.
You *may* add extra "promoted" columns for fields you want to search in the backend UI, but the
app reads only `RecordKey` and `Data`.

Create the lists/tables yourself only if the user asks and has permission. Otherwise give them
the exact list of names and columns.

## Step 4: Add the connector

Always use the CLI (pinned in `package.json`) so codegen and `ms.config.json` stay consistent. Run
`npx ms app add data-source --help` to see every flag.

```bash
# SharePoint: one command per list
npx ms app add data-source --connector shared_sharepointonline --as table --dataset "<site URL>" --table "<list name>"

# Dataverse: one command per table (no connection id needed)
npx ms app add data-source --connector dataverse --as table --table "<table logical name>"

# Any other connector
npx ms connector list --search "<keyword>"
npx ms app add data-source --connector <api-id> --as action
```

Then find the generated operations. **Do not read whole generated files**; they are large:

```bash
# list method names of a generated service
rg "async \w+\(" generated/services/<Name>Service.ts
# then read one method and its model
rg "async <MethodName>" -A 25 generated/services/<Name>Service.ts
```

## Step 5: Implement the provider

The core already provides `createTableBackedProvider()`. You implement **one `TableBackend` per
collection**, which is five methods. Everything else (validation, queries, paging, conflicts,
export/import) is handled for you.

1. **Connector wrapper**: `src/connectors/<backend>Tables.ts`. This is the only file that imports
`generated/`. Expose plain functions such as `listRows(table, cursor)`, `getRow`,
`createRow`, `updateRow(table, key, data, etag)` and `deleteRow`, and translate connector
results into `BackendRow` (`{ key, data, etag, createdAt, updatedAt }`).
2. **Provider**: `src/storage/providers/<backend>.ts`.

```ts
// Adjust names (config fields, table prefix) to match this app's src/config.ts.
import { createLocalProvider, createTableBackedProvider, type TableBackend } from '../core';
import * as rows from '../../connectors/sharepointTables';
import { config } from '../../config';

function backendFor(collectionName: string): TableBackend {
const table = `${config.storageTablePrefix}${collectionName}`;
return {
list: (cursor) => rows.listRows(table, cursor),
get: (key) => rows.getRow(table, key),
create: (key, data) => rows.createRow(table, key, data), // ConflictError if key exists
update: (key, data, etag) => rows.updateRow(table, key, data, etag), // ConflictError on etag mismatch, NotFoundError if missing
delete: (key, etag) => rows.deleteRow(table, key, etag), // idempotent; ConflictError on etag mismatch
};
}

export function createSharePointProvider() {
const local = createLocalProvider({ prefix: config.storagePrefix });
return createTableBackedProvider({
id: 'sharepoint',
shared: true,
tableFor: backendFor,
kv: (namespace) => local.kv(namespace), // keep preferences on the device
});
}
```

3. **Register it** in `src/storage/index.ts` by adding `sharepoint: createSharePointProvider` to
the provider registry. Then set `VITE_STORAGE_PROVIDER=sharepoint` (plus any new variables,
such as the table prefix) in `.env.local`. Document the new variables in `.env.example` and in `src/config.ts`.
4. Remote stores do not push changes. Call `provider.refresh()` on window focus, and optionally
on a timer, so other users' edits appear.

### Mapping rules every backend must follow

- `etag` must change on **every** write, and the backend must reject stale etags with a
"precondition failed" error (HTTP 412). Map that error to `ConflictError` from `../core`.
- `create` with an existing key must throw `ConflictError`. Enforce uniqueness on `RecordKey`,
or check first.
- A missing record on `update` throws `NotFoundError`. `delete` of a missing record succeeds.
- `list` must page with the backend's continuation token. Never assume one page holds everything.
- Store `Data` exactly as given. Never reformat the JSON.

## Step 6: Prove it with the contract suite

Create `src/storage/providers/<backend>.test.ts`:

```ts
import { runProviderContract } from '../core/contract';
// Fake the connector wrapper (src/connectors/<backend>Tables.ts) with an in-memory map that
// reproduces the backend's real behaviour: etags, 412s, paging. See createInMemoryTableBackend
// in core/providers/tableBacked.ts for the reference behaviour.
runProviderContract('sharepoint', () => createSharePointProviderWithFakeRows());
```

Run `npm test`, `npm run lint` and `npm run typecheck`. All must pass. Then run the app against the
real backend and try each feature, ideally in two browsers with different accounts to see
sharing and conflicts.

## Step 7: Security and privacy

- Grant list/table permissions to exactly the people who should read or write each collection.
The app's UI is not a security boundary.
- Review what becomes visible once data is shared. Collections that were per-browser (drafts,
personal notes) may now be readable by others; keep those in `kv` (device-local), or use a
per-user table with item-level permissions.
- Keep connector permissions least-privilege. Add only the tables the app uses.

## Step 8: Move existing data

Users can move what they already have: in the app's Settings, choose **Export data** while still
on the `local` provider, switch to the new provider, then **Import data**. Import validates every
record and skips anything invalid.

## Done checklist

- [ ] One list/table per moved collection, with `RecordKey` (unique) and `Data` columns
- [ ] Connector added with the CLI; the updated `generated/`, `.ms/` and `ms.config.json` are committed to the app's repository.
- [ ] `src/connectors/<backend>Tables.ts` plus `src/storage/providers/<backend>.ts`, registered in `src/storage/index.ts`
- [ ] The contract suite passes for the new provider, and `npm test`, `npm run lint` and `npm run typecheck` are green
- [ ] Permissions configured in the backend
- [ ] `.env.example`, `src/config.ts` and the README's "Storage" section updated
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Your own API as a backend

Use this when data must live in an existing system (an internal service, a SQL database behind an
API, a SaaS product).

## Requirements for the API

Expose, per collection (or with the collection as a path segment):

| Operation | Example | Must |
|---|---|---|
| List | `GET /collections/{name}/rows?cursor=…` | Return `{ rows: BackendRow[], nextCursor? }` and page results |
| Get | `GET /collections/{name}/rows/{key}` | Return 404 when missing |
| Create | `POST /collections/{name}/rows` with `{ key, data }` | Return 409 when the key exists |
| Update | `PUT /collections/{name}/rows/{key}` with `If-Match: <etag>` | Return 412 on a stale etag and 404 when missing |
| Delete | `DELETE /collections/{name}/rows/{key}` with optional `If-Match` | Succeed when already gone; return 412 on a stale etag |

Rows carry `key`, `data` (an opaque JSON string, stored verbatim), `etag` (changes on every
write), `createdAt` and `updatedAt`. The API must authenticate the caller and enforce
authorization itself.

## Reach it through a connector

Wrap the API in a **custom connector** (OpenAPI definition plus authentication) in your Power
Platform environment. Then add it like any other connector:

```bash
npx ms connector list --search "<your connector name>"
npx ms app add data-source --connector <api-id> --as action
```

Calling arbitrary URLs with `fetch` from the app is discouraged: it bypasses connector
authentication, data-loss-prevention policies and auditing.

## Map responses

In `src/connectors/<api>Tables.ts`, translate:

- 404 on get → `undefined`
- 409 on create → `ConflictError`
- 412 on update/delete → `ConflictError`
- 404 on update → `NotFoundError`

Then build the provider with `createTableBackedProvider()` exactly as in `SKILL.md` step 5, and
run the contract suite against a fake of the wrapper.
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Dataverse tables backend

## Provision

For each collection, create a table (for example display name `LearningHub Session`, logical
name `<publisherprefix>_learninghubsession`):

| Column | Dataverse type | Settings |
|---|---|---|
| `RecordKey` | Text (single line), max length 200 | Business required, plus an **alternate key** on this column |
| `Data` | Multiline text (plain) | Max length 1,048,576 |

The primary name column can hold a readable label (for example the record's title) for
browsing in Dataverse. Ownership: choose **User or team** if you need per-user security, or
**Organization** for data everyone shares.

Security: create or extend a **security role** with Create/Read/Write/Delete privileges on each
table at the right depth (User, Business Unit or Organization), and assign it to the app's users.

## Add the connector

```bash
npx ms app add data-source --connector dataverse --as table --table "<publisherprefix>_learninghubsession"
```

No connection id is needed; the CLI binds to the active environment's Dataverse. Repeat per
table, then inspect the generated services with `rg "async \w+\(" generated/services`.

## Mapping to `BackendRow`

| BackendRow | Dataverse row |
|---|---|
| `key` | `RecordKey` column (the alternate key) |
| `data` | `Data` column |
| `etag` | `@odata.etag` |
| `createdAt` / `updatedAt` | `createdon` / `modifiedon` |

- **Lookups by key**: retrieve by alternate key, or filter `RecordKey eq '<key>'`. Keep the row's
primary GUID in the wrapper for updates and deletes.
- **Paging**: follow `@odata.nextLink`, or the paging cookie the generated list operation exposes.
- **Conflicts**: Dataverse supports optimistic concurrency. Send `If-Match: <etag>` on update
and delete, and map HTTP 412 to `ConflictError`. A duplicate alternate key on create fails, so
map that to `ConflictError` too.
- **Timestamps** are UTC ISO strings, so pass them through unchanged.

## Notes

- Use a **solution** to hold the tables and security role, so the setup can be exported to other environments.
- Dataverse capacity is metered. JSON in `Data` is compact, but avoid storing large blobs; use file columns or SharePoint for documents.
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# SharePoint lists backend

## Provision

For each collection, create a list (for example `LearningHub_sessions`):

| Column | SharePoint type | Settings |
|---|---|---|
| `RecordKey` | Single line of text | Required, **Enforce unique values: Yes** (this also indexes it) |
| `Data` | Multiple lines of text | **Plain text** (not rich/enhanced), "Append changes" **off** |

Rename or hide the built-in `Title` column if you like; the app does not use it. You can set
`Title` to a human-readable value (e.g. the record's name) in `createRow` to make the list browsable.

Permissions: break inheritance on each list only if it needs different access than the site.
Grant **Contribute** to people who write and **Read** to people who only read.

## Add the connector

```bash
npx ms app add data-source --connector shared_sharepointonline --as table --dataset "https://<tenant>.sharepoint.com/sites/<site>" --table "LearningHub_sessions"
```

Repeat for each list. Then inspect the generated services:

```bash
rg "async \w+\(" generated/services
```

Typical operations are "get items" (with `$filter`, `$top` and a continuation/skip token),
"get item", "create item", "update item" and "delete item". Exact names depend on the CLI version,
so use what the grep shows.

## Mapping to `BackendRow`

| BackendRow | SharePoint item |
|---|---|
| `key` | `RecordKey` |
| `data` | `Data` |
| `etag` | `@odata.etag` (or `ETag`) from the item |
| `createdAt` / `updatedAt` | `Created` / `Modified` |

- **Lookups by key**: SharePoint item ids are numeric and differ from `RecordKey`. Find items with
a filter such as `$filter=RecordKey eq '<key>'` (escape single quotes by doubling them). Cache
`RecordKey → item id` inside the wrapper if you want fewer calls.
- **Paging**: follow the continuation value the "get items" operation returns (`@odata.nextLink`
or a skip token). Return it as `nextCursor`.
- **Conflicts**: if the update/delete operation accepts an `If-Match` header or etag parameter, pass
the etag and map HTTP 412 to `ConflictError`. If it does not, re-read the item, compare `etag`,
then write. Document in the README that a small race window remains.
- **Create uniqueness**: with "Enforce unique values" on, a duplicate `RecordKey` fails. Map that
failure to `ConflictError`.
- **Size**: keep each record well under a few hundred KB. Large attachments belong in a document
library, with only a link stored in the record.

## Throttling

SharePoint throttles bursts. Keep `list` page sizes moderate (100–500). If the connector reports
HTTP 429, wait for `Retry-After` and retry.
Loading
Loading