From 01e571fb31bf0bc096c4f35e162fe0db1b06c87c Mon Sep 17 00:00:00 2001 From: Maddy Montaquila Date: Mon, 16 Nov 2026 16:13:50 -0500 Subject: [PATCH 1/2] docs: add 'Try a prerelease build' walkthrough to upgrade guide Fixes #2181 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../content/docs/whats-new/upgrade-aspire.mdx | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/src/frontend/src/content/docs/whats-new/upgrade-aspire.mdx b/src/frontend/src/content/docs/whats-new/upgrade-aspire.mdx index e156111304..f43ca02c37 100644 --- a/src/frontend/src/content/docs/whats-new/upgrade-aspire.mdx +++ b/src/frontend/src/content/docs/whats-new/upgrade-aspire.mdx @@ -43,6 +43,61 @@ If you're new to Aspire, there's no reason to upgrade anything. See [prerequisit For more information, see [`aspire update` command reference](/reference/cli/commands/aspire-update/). +## Try a prerelease build + +To test your app against an upcoming release before it ships, switch both the CLI and your app to the `staging` channel. Staging builds come from the current release branch and aren't intended for production use. Use a branch or a throwaway copy of your repository. + + + +1. **Update the Aspire CLI to a staging build:** + + ```bash title="Update the CLI to staging" + aspire update --self --channel staging + ``` + + In CI, install the matching CLI with the install script's [`--quality staging`](/reference/cli/install-script/#options) option (`-Quality 'staging'` in PowerShell) instead of the default `release` quality. + +2. **Update your app to the staging channel:** + + ```bash title="Update the app to staging" + aspire update --channel staging --migrate + ``` + + Besides updating package versions, this command: + + - Writes `"channel": "staging"` to `aspire.config.json` when that file exists, so later `aspire add` and `aspire update` runs keep resolving staging packages. + - Creates or updates a project-level `NuGet.config` with the staging feed and a package source mapping that routes `Aspire*` packages to it. + - Sets `globalPackagesFolder` to a repository-local `.nugetpackages` folder in that `NuGet.config`, so prerelease packages don't mix with your global package cache. Add `.nugetpackages/` to your `.gitignore`. + + `--migrate` applies only automatic migrations. Build the app afterward and review any new warnings, such as `ASPIRE012`, which flags approval-gated changes that `aspire update` doesn't make for you. See the [diagnostics overview](/diagnostics/overview/) for each warning's fix. + +3. **Point `aspire docs` at the prerelease documentation.** The prerelease site, reached through `https://aka.ms/aspire/vnext`, documents features that aren't on aspire.dev yet. Open that link once to find the prerelease host, then set both documentation sources so guide search and API lookup (including AI agent skills that call `aspire docs`) read the same content: + + ```json title="aspire.config.json" + { + "docs": { + "llmsTxtUrl": "https:///llms-full.txt", + "api": { + "sitemapUrl": "https:///sitemap-0.xml" + } + } + } + ``` + + For details, see [`docs.llmsTxtUrl` and `docs.api.sitemapUrl`](/reference/cli/configuration/). The prerelease sitemap still lists canonical `aspire.dev` page URLs. + +4. **Verify the switch.** Run `aspire --version` to confirm the CLI build, check that your Aspire package references resolve to the staging version, and run `aspire docs search` for a feature that's new in the release. + +5. **Check for anything the updater skipped.** `aspire update` updates the AppHost it selects and the package versions it uses. Check these by hand: + + - Central package pins that no project currently references. + - Other AppHosts in the repository. + - CLI versions or install qualities pinned in CI workflows and dev container definitions. + +6. **Switch back to stable** when you're done by running `aspire update --channel stable` for the app, then `aspire update --self --channel stable` for the CLI. Remove the `docs` overrides from `aspire.config.json`. If your app was already up to date, `aspire update` can leave the staging `NuGet.config` entries in place; remove them manually. + + + ## Update standalone dashboard container references If you manage the standalone dashboard as a container, its stable image repository is now `mcr.microsoft.com/aspire/dashboard`; nightly images use `mcr.microsoft.com/aspire/nightly/dashboard`. Updating the Aspire CLI or packages doesn't rewrite image references in your own Docker commands, Compose files, or Kubernetes manifests. From 58d9085b2e0f76ac107e7202930fc8cb30c71458 Mon Sep 17 00:00:00 2001 From: Maddy Montaquila Date: Mon, 16 Nov 2026 17:17:48 -0500 Subject: [PATCH 2/2] docs: clarify staging update behavior by install type and AppHost language Address review feedback: npm/.NET tool CLIs don't switch channels via --self, C# AppHosts follow NuGet policy without --channel, NuGet side effects are C#-only and conditional, and link ASPIRE012 help directly. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../src/content/docs/whats-new/upgrade-aspire.mdx | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/frontend/src/content/docs/whats-new/upgrade-aspire.mdx b/src/frontend/src/content/docs/whats-new/upgrade-aspire.mdx index f43ca02c37..a3b27b74b1 100644 --- a/src/frontend/src/content/docs/whats-new/upgrade-aspire.mdx +++ b/src/frontend/src/content/docs/whats-new/upgrade-aspire.mdx @@ -55,7 +55,7 @@ To test your app against an upcoming release before it ships, switch both the CL aspire update --self --channel staging ``` - In CI, install the matching CLI with the install script's [`--quality staging`](/reference/cli/install-script/#options) option (`-Quality 'staging'` in PowerShell) instead of the default `release` quality. + This switches CLIs installed with the install script. If you installed the CLI as a .NET tool or with npm, `aspire update --self` prints the package manager's update command instead and doesn't switch channels. Reinstall with the install script and the [`--quality staging`](/reference/cli/install-script/#options) option (`-Quality 'staging'` in PowerShell) instead. Use the same option in CI instead of the default `release` quality. 2. **Update your app to the staging channel:** @@ -63,13 +63,16 @@ To test your app against an upcoming release before it ships, switch both the CL aspire update --channel staging --migrate ``` - Besides updating package versions, this command: + Besides updating package versions, this command writes `"channel": "staging"` to `aspire.config.json` when that file exists. For TypeScript and other non-C# AppHosts, later `aspire add` and `aspire update` runs use that saved channel. For C# AppHosts, an `aspire update` run without `--channel` follows your NuGet configuration instead of the saved channel, so pass `--channel staging` on each update while you test. - - Writes `"channel": "staging"` to `aspire.config.json` when that file exists, so later `aspire add` and `aspire update` runs keep resolving staging packages. - - Creates or updates a project-level `NuGet.config` with the staging feed and a package source mapping that routes `Aspire*` packages to it. - - Sets `globalPackagesFolder` to a repository-local `.nugetpackages` folder in that `NuGet.config`, so prerelease packages don't mix with your global package cache. Add `.nugetpackages/` to your `.gitignore`. + For C# AppHosts, the command can also create or update a project-level `NuGet.config` that adds the staging feed. Depending on your existing configuration, it can also: - `--migrate` applies only automatic migrations. Build the app afterward and review any new warnings, such as `ASPIRE012`, which flags approval-gated changes that `aspire update` doesn't make for you. See the [diagnostics overview](/diagnostics/overview/) for each warning's fix. + - Add a package source mapping that routes `Aspire*` packages to the staging feed. + - Set `globalPackagesFolder` to a repository-local `.nugetpackages` folder when one isn't already set, so prerelease packages don't mix with your global package cache. If it does, add `.nugetpackages/` to your `.gitignore`. + + Review the resulting `NuGet.config` before you commit it. + + `--migrate` applies only automatic migrations. Build the app afterward and review any new warnings, such as `ASPIRE012`, which flags approval-gated changes that `aspire update` doesn't make for you. For the `ASPIRE012` migration steps, see [aka.ms/aspire/diagnostics/aspire012](https://aka.ms/aspire/diagnostics/aspire012). For other warnings, see the [diagnostics overview](/diagnostics/overview/). 3. **Point `aspire docs` at the prerelease documentation.** The prerelease site, reached through `https://aka.ms/aspire/vnext`, documents features that aren't on aspire.dev yet. Open that link once to find the prerelease host, then set both documentation sources so guide search and API lookup (including AI agent skills that call `aspire docs`) read the same content: