Beyond the chat, and running the app

Microsoft Learn asks for Node.js LTS 24.11.0 or later, Git 2.27.0 or later and Git Credential Manager; the plugin README says Node 22 is enough. Use the stricter baseline. Any editor works. D

node --version
git --version
git credential-manager --version
npm i -g @microsoft/managed-apps-cli
ms --version
ms auth login --account you@contoso.com
ms auth status

The package is being renamed. Learn still shows @microsoft/managed-apps-cli; the new repository advertises @microsoft/cmr-cli. Install one, record its version in the repository's README, and don't mix old and new names in one project. DC

Copy link

• New app from the command line: ms app create inventory --display-name "Inventory" creates it in your personal developer environment, provisioning one on first use. Add --environment-id <guid> to target another environment; that choice is made at creation. D
• An existing web project: use ms app init --display-name "Inventory" --repo native in its folder rather than create, which expects an empty destination. D
• An app someone built in Cowork, Code or Copilot Studio: the owner grants you edit access (ms app share colleague@contoso.com --access edit), then you run ms app list --permission edit and ms app clone --app <app-id> ./inventory-local. The CLI finds the repository from the app record and sets up Git authentication. Give clone an explicit folder; two Learn pages disagree about the default. D

The CLI starter is a lean React and TypeScript project on Vite. Apps created from the chats start from a richer template with Tailwind, Radix-based components and the device controls described in Part 4, so don't assume one matches the other. DO

Copy link

ms app dev starts your framework's dev server and a local configuration server (port 8080, app on localhost:3000) and prints a local play URL once both respond. Open that URL in the browser profile that is already signed in to your tenant; raw localhost does not reproduce the managed host. Hot reload works, and Ctrl+C stops the loop. D

ms app dev
ms app dev --local-app-url http://localhost:5173 --port 8081
ms app dev --config-only --local-app-url http://localhost:5173

Local does not mean mocked. Data calls still go through the host to live connections with your consent and permissions, so a local test can change real records. Point development at test lists or tables. DI

Copy link

Discover first, then bind. The current flag is --connector; older examples use --api-id. In non-interactive mode a tabular connector needs --as table or --as action. D

ms connector list --search sharepoint --include-blocked
ms connector list-actions --connector shared_sharepointonline
ms app add data-source --connector shared_sharepointonline --as table --connection-id <id> --dataset "https://contoso.sharepoint.com/sites/Operations" --table "Requests"
ms app add data-source --connector shared_commondataserviceforapps --as table --dataverse-environment-id <guid> --table account
ms app add data-source --connector shared_a365copilotchatmcp --as action
ms app refresh data-source
ms app show

• Excel Online (Business) binds as a table through an interactive picker; let the picker discover the workbook's dataset id instead of pasting a SharePoint file URL. D
• Binding a SQL stored procedure is not supported; bind tables or views. D
• Binding Work IQ generates typed services, not a finished conversation. Your code still opens a session, reuses its id, calls tools and re-initializes when the session expires. D
• After a schema change in the source, run ms app refresh data-source, rebuild and retest; after a credential expires, add the data source again with a new connection. D

Copy link

git add .
git commit -m "Release inventory validation"
git push
SHA=$(git rev-parse HEAD)
ms app build --commit "$SHA"
ms app build-status --commit "$SHA" --show-log
ms app play --mode preview --commit "$SHA"
ms app deploy --commit "$SHA"
ms app play --mode live
ms app deploy --commit <previous-good-sha>

• Push before you ask for a build: the platform builds what is in the repository, never your uncommitted files. D
• Preview shows the latest build of main unless you pin a commit; live is a snapshot that never updates itself. Always pass the SHA you tested, because Learn pages disagree on whether an omitted commit means HEAD or the latest main. D
• Rolling back is redeploying an older SHA. It restores code, not data: records the newer version wrote stay written. DI
• For an app created with --repo none, ms app deploy builds and uploads from your machine, and --artifact ./release.zip uploads a prebuilt bundle. External artifacts are off by default and need admin approval. D
• The only documented app setting is the host header: ms app set-setting --show-header false. There is no documented place for secrets or environment variables, so don't look for one. D
• Every command takes --json, --non-interactive and --no-color for scripting. --cloud accepts public, usgov, usgovhigh, usgovdod and china, which are routing values, not proof the service runs in each cloud. CLI telemetry is on by default and excludes your code and data; ms telemetry disable turns it off. D

Copy link

Microsoft's walkthrough uses the standalone GitHub Copilot CLI (run it in VS Code's terminal if you like) with a plugin marketplace. Start a fresh agent session after installing. D

copilot
/plugin marketplace add microsoft/Copilot-Managed-Runtime
/plugin install copilot-managed-runtime@Copilot-Managed-Runtime

Claude Code takes the same two marketplace commands. Learn's quickstart still shows the archived identity (microsoft/Managed-Apps and microsoft-managed-apps@Managed-Apps), which is a separate install rather than an upgrade. Codex can load the portable package for evaluation only, and no tested Cursor recipe was published as of this edition. D

The plugin wraps the CLI with 22 skills and does not ship an MCP server of its own. Its conventions are worth copying even in Code: plan significant changes, require a green build, sync source before releasing, and ask before deploying, sharing or deleting. It keeps project memory in a memory-bank.md file at the repository root. D

Copy link

Switching modes later means creating a new app, so choose on day zero. For a GitHub-bound app, ms app create inventory --repo https://github.com/contoso/inventory links it and ms git auth refresh renews the Entra-to-GitHub mapping. D

Copy link

Microsoft's documented pipeline needs an app created with --repo none, a committed ms.config.json, external artifacts allowed by your admin, and an Entra service principal with a client secret stored in Actions secrets. D

• In environments with Dataverse, the application user needs the System Administrator and System Customizer roles; in environments without Dataverse it needs EnvironmentAdmin. Use the Enterprise Applications object id: the App Registrations id fails with "400 Principal not found." This is the published setup, not a least-privilege design. D
• The action input app-id is the service principal's client id, not the app's id, which comes from ms.config.json. D
• The new repository's actions are referenced at @main and old release tags were not carried over; Learn still shows microsoft/Managed-Apps/...@v1. Pin a reviewed commit SHA before you depend on it. DI

- uses: microsoft/Copilot-Managed-Runtime/github-actions/install-ms-cli@main
- uses: microsoft/Copilot-Managed-Runtime/github-actions/ms-app-pack@main
  with:
    working-directory: apps/inventory
    app-id: ${{ secrets.PP_SP_CLIENT_ID }}
    client-secret: ${{ secrets.PP_SP_CLIENT_SECRET }}
    tenant-id: ${{ secrets.PP_SP_TENANT_ID }}
- uses: microsoft/Copilot-Managed-Runtime/github-actions/ms-app-deploy@main

There is no Microsoft-published Azure Pipelines recipe and no federated-credential variant yet; anything else is your own design and your own risk. D

Copy link

New apps land in the maker's personal developer environment, which is a Managed Environment governed by routing rules, not a dev stage in a pipeline. There is no ms app move. Microsoft documents moving a Cowork app to a shared or production environment: you need its id and maker rights there, you must share it again afterwards, and Dataverse tables do not move with it. D

For real dev, test and production separation, run separate apps with separate data bindings, promote a reviewed SHA or artifact between them, and keep a release manifest of app ids, environments, bindings and versions. Within one app, preview is a release candidate and live is a snapshot; neither is an isolated data store. Feature switches hide work but are not security: enforce restricted writes in the data source. I

Decide this in the setup → Step 7: Access and licensing

Copy link

• The SDK has no root import. Use its subpaths: /app (getContext, setConfig), /auth (getUser), /data (getClient) and /telemetry. D
• getUser() returns the signed-in person's fullName, objectId and tenantId, supplied by the host; the app never handles a token. Email address, theme, host navigation and storage APIs are not documented for managed apps. D
• Don't edit ms.config.json or generated/ by hand; the tools own them. Everything else is ordinary code. D
• The default content security policy sets worker-src 'none' and manifest-src 'none', so offline use and installable app behavior are off the table; responsive layout is up to you. D
• For telemetry, add Application Insights' web SDK, register a logger through setConfig, and ask your admin to add the exact ingestion origin to connect-src. Telemetry starts only after the app loads, so failed launches show up only in the admin center's monitoring. D

Copy link

• App Builder agent apps stop opening on 30 November 2026. From 4 November, one-click Migrate app moves screens, navigation and logic into Apps in Copilot Studio only. Moving to Cowork, or anywhere else, is a manual rebuild from the downloaded source. Nothing migrates into Copilot Code. Sharing links don't carry over; data stays where it is. Keep the original until the new app is verified. D
• vibe.powerapps.com apps move one-click to Apps in Copilot Studio by the same date. Publish draft tables first, because unpublished tables don't migrate; manual rebuilds can't yet reach Dataverse tables in the default environment, and Studio ZIP uploads are limited to 10 MB. D
• Power Apps code apps have no official converter. Community ports keep the React components, swap the Power Apps SDK and plugin for the managed-apps ones, register with ms app init, regenerate connectors and redeploy. C

Copy link

Name an owner and a backup owner in README.md, give the backup edit access, and review both every quarter. No co-owner model or ownership transfer is documented for managed apps, and the inventory's Owner column can differ from the person who built the app. DI Deleting is permanent, and the two delete routes treat the repository differently (see the callout in section 15.6). DO

Copy link

• Schedule a weekly check in Cowork: open the app, compare a few totals with the source, read the feedback list and report the differences. I
• Connections age out. Ask Code to check connection status (connected, stale, expired) before every release and after password or policy changes. O
• Use the admin center's monitoring for open success and latency, and Application Insights for deeper telemetry, which needs a content security policy entry. D
• Add a "Send feedback" control that writes to a SharePoint list, and triage it weekly. I

Copy link

The bill is driven by chatty apps: at pay-as-you-go pricing of about one cent per credit, a call costs roughly a tenth of a cent, plus a per-launch charge whose rate is not published, so cache reads, avoid polling and load data on demand. DI

Copy link

• Publish release notes, keep a "What's new" page in the app, and update Help whenever behavior changes. O
• Keep a dated known-issues backlog with an owner for each item. O
• Tell users before planned pauses; when an admin blocks an app, people simply can't open it.

Copy link

Block before you delete, archive the repository, record the sunset date and tell the users. DI If you still have apps built with the older App Builder agent, act now. App Builder and vibe.powerapps.com retire on 30 November 2026. From 4 November, one-click Migrate app moves screens, navigation and logic into Apps in Copilot Studio only. Moving to Cowork, or anywhere else, is a manual rebuild from the downloaded source. D

Copy link

The admin center's monitoring shows whether apps open and how fast. History is kept 28 days, with up to five alert rules per tenant, and only admins see it. D It can't tell you which screen people abandon, which call is slow or whether a new feature helped. Application Insights can, and the builder can see it too.

You get these signals: D

• Two built-in metrics from the platform. The app SDK passes them to your logger: a session load summary (did the app open, and how long until it was usable) and network request summaries (URL, method, duration, status, size).
• Browser telemetry from the web SDK: page views, fetch and XHR dependency calls with timings, unhandled exceptions, and any custom events you send.
• Usage tools: Users, Sessions and Events views, Funnels (up to six steps), User Flows, Cohorts, and workbook templates for retention and user impact.
• Logs, workbooks and alerts over all of it, written in Kusto Query Language (KQL).

Telemetry starts only after the app loads. A blocked or failed launch never reaches Application Insights. It shows up only in the admin center's monitoring, so keep watching both. D

Copy link

Settle first: one Azure region for data residency, one resource per app, and who may see the results.

Copy link

1. Create the resource. In the Azure portal, create a workspace-based Application Insights resource in your chosen region, then copy its connection string from Overview. The string carries a regional ingestion endpoint, which keeps ingestion in that geography. D
2. Keep the string out of the blueprint and the skill. Microsoft says the connection string "isn't considered a security token or key". It is still visible in every user's browser. D Managed apps have no documented place for secrets or environment variables (section 22.5). D So keep it in one row of a SharePoint "App settings" list that the app reads at startup, with an on/off column. That keeps the string out of the repository. The owner can also switch telemetry off without a release. I The blueprint records only the host, in integrations.externalHosts (for example <region>.in.applicationinsights.azure.com), never the string itself.
3. Add the SDK with Code. Use the prompt below. Code bundles the npm package @microsoft/applicationinsights-web. Don't use the CDN loader script: the default script-src blocks third-party CDNs, and bundling means only the ingestion origin needs an exception. DI
4. Find the origin. Publish the build with telemetry switched on for yourself only. Open the app, press F12, filter the console to Errors and look for "Refused to connect". Copy that origin exactly. D
5. Ask for the exception. Send the request below. Ask for connect-src only, for that one origin, never a wildcard. D
6. Test with a colleague. After the change propagates (several minutes), reload. Check that the console shows no violations and that events appear in Logs within a few minutes. Then switch telemetry on for one colleague and confirm their session shows up without their name in it. DI

Fetch tracking stays on and covers the app's own calls. Turning off XHR tracking avoids duplicate entries. Adjust it if your build relies on XHR. I

The exception request uses the standard recipe:

On report-only mode: Microsoft recommends enforcing a change in a development or test environment first, then running report-only in production before enforcing it there. D Report-only applies to the whole policy, not to one origin. So for a single telemetry origin, the narrowest route is usually adding it in a test environment group first, then in production. Let your admin choose. I

Copy link

Decide the events before you write code, and keep the list in src/telemetry/events.ts. I

Use bands rather than raw values where a value could identify someone: "1–5 items", not "3 items for account 4412". I

Copy link

As of 7 November 2026: D

• IP addresses. By default, Application Insights uses the IP address for a city-level location lookup, then stores 0.0.0.0 in place of the address. Leave IP masking on.
• User ids. Users are counted with anonymous ids in browser cookies, so a person on two browsers counts twice. Don't call setAuthenticatedUserContext with a real id. If you must link sessions, use a salted one-way hash of the object id, and record that decision with your privacy lead. DI
• Sampling. The web SDK sends 100 percent of events by default. Lower samplingPercentage if volume grows. Sampling makes funnels and the retention workbooks less accurate.
• Retention. Application Insights tables keep data for 90 days at no charge. You can extend that per table at extra cost.
• Residency. Data stays in the region of the resource and its workspace.
• Cost. Ingestion is billed per GB through the workspace, at a rate that varies by region. The Azure pricing page shows the first 5 GB a month per billing account free on the pay-as-you-go Analytics Logs tier. Check the calculator for your region, and ask the Azure owner to set a daily cap.

For sizing, 200 users with three sessions a day and 40 events per session, at about 1 KB per event, comes to about 0.7 GB a month. That fits inside the free allowance if nothing else in the billing account uses it. I Telemetry posts go straight to Azure, not through the app's connectors. We expect them not to count as runtime API calls, but Microsoft doesn't document this. I

Copy link

Open the resource, then Monitoring > Logs. Platform metrics land in customEvents. D Platform metric names have appeared in more than one form in Microsoft's samples, so start with the first query. DI

// 1. Which event names is this app sending?
customEvents
| where timestamp > ago(7d)
| summarize count() by name
| order by count_ desc

// 2. App open time, 75th percentile by day (successful opens only)
customEvents
| where name == "sessionLoadSummary"
| extend ok = tobool(customDimensions.successfulAppLaunch),
         tti = todouble(customMeasurements.timeToAppInteractive)
| where ok == true
| summarize p75_ms = percentile(tti, 75) by bin(timestamp, 1d)
| render timechart

// 3. Slowest calls by route, 75th percentile
customEvents
| where timestamp > ago(7d) and name == "networkRequest"
| extend url = tostring(split(tostring(customDimensions.url), "?")[0]),
         duration = todouble(customMeasurements.duration)
| summarize calls = count(), p75_ms = percentile(duration, 75) by url
| top 10 by p75_ms

// 4. Screens by visits and distinct browsers
pageViews
| where timestamp > ago(28d)
| summarize views = count(), browsers = dcount(user_Id) by name
| order by views desc

// 5. Top errors this week
exceptions
| where timestamp > ago(7d)
| summarize count = count(), sessions = dcount(session_Id) by problemId, screen = tostring(customDimensions.screen)
| top 10 by sessions

// 6. Did the switched-on feature help? Completion rate by switch state
let exposed = customEvents
| where timestamp > ago(14d) and name == "feature_exposed"
| project session_Id, flag = tostring(customDimensions.flag), state = tostring(customDimensions.state);
let done = customEvents
| where timestamp > ago(14d) and name == "request_submitted"
| distinct session_Id
| extend completed = 1;
exposed
| join kind=leftouter done on session_Id
| summarize sessions = dcount(session_Id), completed = dcountif(session_Id, completed == 1) by flag, state
| extend rate_pct = round(100.0 * completed / sessions, 1)

// 7. The weekly summary the flow writes (one row per metric)
let since = ago(7d);
union
 (customEvents | where timestamp > since and name == "sessionLoadSummary"
  | summarize value = percentile(todouble(customMeasurements.timeToAppInteractive), 75) | extend metric = "Open time p75 (ms)"),
 (exceptions | where timestamp > since | summarize value = todouble(count()) | extend metric = "Errors"),
 (pageViews | where timestamp > since | summarize value = todouble(dcount(session_Id)) | extend metric = "Sessions")
| project metric, value

Pin queries 2, 3 and 5 to a workbook. Add a log search alert on query 5, for example when errors in an hour pass a threshold you set from the first two weeks of data. DI Use Funnels for a fixed path, such as open, filter, submit, and User Flows to explore. D

Copy link

Telemetry pays off only when it changes the next release. Every step after the first uses tools a managed app already has. I

1. A weekly flow reads Application Insights. A scheduled Power Automate flow owned by the service account runs query 7 with the Azure Monitor Logs action "Run query and list results". It then writes one row per metric into a SharePoint "Telemetry" list: week, metric, value, last week's value, status (ok, watch, act) and query name. The connector supports a service principal, and it allows 100 calls per connection every 60 seconds, so use one query, not one per metric. DI
2. The app shows an Insights screen. An admin route reads the Telemetry list through the SharePoint connector, which is on the default allow-list (section 9.4). It shows this week against last week, with a status chip per metric. Restrict the list itself to the owners group. Hiding the route is not security. DI
3. Cowork reviews it weekly. A Cowork scheduled prompt (you can keep up to 25 scheduled prompts) runs a few hours after the flow. It reads the Telemetry list and the feedback list, then proposes items. DI
4. Findings become backlog items. Accepted items go into an "Improvements" list: title, evidence (metric and week), expected effect, effort, status, feature switch, owner and release. They also get a line in RELEASE-LOG.md. I
5. Code ships the change dark and measures it. The next Code session picks up the top accepted item. Code ships it behind a switch, logs feature_exposed, and after two weeks query 6 decides whether the switch stays on. I

The app can't read Application Insights directly at run time. Azure Monitor Logs isn't on the managed-runtime default allow-list and is a premium connector. Calling the query API from the browser would need a token the app can't hold. So the list written by the flow is the only route we recommend. DI At build time, a local coding agent (section 22.6) can use the Azure MCP Server's Log Analytics query and metrics tools with your own Azure sign-in. D Whether Copilot Code can attach that server isn't documented. Exporting query results to CSV and attaching them to a Code session also works. I

Copy link

Copy link

Copy link