Skip to content

[docs] Document configured channel for aspire update - #2133

Draft
aspire-repo-bot[bot] wants to merge 1 commit into
mainfrom
docs/pr-22182-43283818630-1-ba985eee6581fb1f
Draft

aspire-repo-bot[bot] wants to merge 1 commit into
mainfrom
docs/pr-22182-43283818630-1-ba985eee6581fb1f

Conversation

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Documents changes from microsoft/aspire#22182

Author: @danegsta

Targeting release/17.0 — the latest release branch on microsoft/aspire.dev — because release/17.1 (from the source PR milestone 17.1) does not exist there.

Why

aspire update for C# AppHosts now honors the configured channel setting when --channel/--quality isn't passed, reports when a non-stable channel comes from configuration, and fails with configuration-specific errors for unknown channels. Triggered signals: cli_command_file_changed, cli_resource_strings_changed, pr_body_has_cli_flag_mention, pr_body_has_user_facing_section.

Changes

Updated (existing page): src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx — --channel option section now describes configured-channel behavior, lookup order, messaging, and failure behavior.

Generated by PR Documentation Check for #22182 · copilot · auto · 24.1 AIC · ⌖ 1.17 AIC · ⊞ 7.4K · ◷

@aspire-repo-bot aspire-repo-bot Bot added the docs-from-code Copilot initiated issue from dotnet/aspire repo label Nov 12, 2026
@aspire-repo-bot

Copy link
Copy Markdown
Contributor Author

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #2133. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #2133 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The CLI documentation describes channel-selection behavior unavailable in 17.0, so it needs to target 17.1 or clearly mark the version requirement while retaining explicit --channel guidance for 17.0.

1 open issue
What changed in this PR

Updates the Aspire CLI reference to document configured-channel behavior for aspire update, based on microsoft/aspire#22182.

Changes:

  • Describes configuration lookup and fallback when --channel or --quality is omitted.
  • Explains configured-channel notifications, validation errors, and NuGet policy handling.
File Description
src/​frontend/​src/​content/​docs/​reference/​cli/​commands/​aspire-update.mdx Expands the --channel option documentation with configured-channel behavior.

Review effort: Balanced


Channel to update to (`stable`, `staging`, `daily`). When switching channels, `aspire update` applies all package version edits to your project first and then runs a single `dotnet restore`, ensuring that NuGet source mappings added for the target channel are in place before any restore is attempted.

When you don't pass `--channel` (or the legacy `--quality` option), `aspire update` uses the `channel` value from your Aspire configuration, for C# AppHosts as well as guest AppHosts. The configuration lookup uses the nearest project settings (`aspire.config.json` or legacy settings) and then falls back to the global configuration. A configured channel goes through the same NuGet policy comparison, preview, approval, validation, and rejection rules as `--channel`. For a non-stable configured channel, the command reports `Using channel 'daily' from Aspire configuration. Pass --channel to override.`; a configured `stable` channel applies the normal stable-channel cleanup without that message. An unknown or unavailable configured channel fails with an error that identifies the configuration as the source instead of silently falling back. When neither `--channel` nor a configured channel is present, C# AppHosts keep the existing NuGet policy.
David Pine (IEvangelist) pushed a commit that referenced this pull request Nov 17, 2026
…2182)

## Summary

Adds a **Try a prerelease build** section to the upgrade guide. It walks
through testing an app against a staging build from start to finish.
Each piece was already documented on a different page, so the section
links back to those references:

1. Update the CLI with `aspire update --self --channel staging`; in CI,
use install-script `--quality staging`.
2. Run `aspire update --channel staging --migrate`. The section explains
what this writes: the `channel` entry in `aspire.config.json`, the
`NuGet.config` staging feed and `Aspire*` source mapping, and the
repo-local `.nugetpackages` folder to add to `.gitignore`. It also notes
that `--migrate` doesn't apply approval-gated changes such as ASPIRE012.
3. Point `aspire docs` at the prerelease docs (`aka.ms/aspire/vnext`) by
setting **both** `docs.llmsTxtUrl` and `docs.api.sitemapUrl`.
4. Verify the switch.
5. Check what the updater skips: inactive central package pins, other
AppHosts, and pinned CI or dev container CLI versions.
6. Switch back to stable, including the stale `NuGet.config` entries
that `aspire update` can leave behind.

Each step reflects what happened when maddymontaquila/aspirifridays was
upgraded from 13.5.3 to 17.0 staging.

The section uses a `<prerelease-host>` placeholder because the
`aka.ms/aspire/vnext` link doesn't pass paths through; for example,
`/llms-full.txt` redirects to Bing.

Fixes #2181. Related: #2133, #2177, #1880, #2180, and
microsoft/aspire#22335.

## Third-party links and affiliations

None

## Validation

- Checked each statement against an actual staging upgrade:
  - `aspire.config.json` contained `"channel": "staging"`.
- `NuGet.config` had the darc feed, the `Aspire*` mapping, and
`globalPackagesFolder=.nugetpackages`.
  - Both docs keys were exercised against vnext.
- Content-only change to an existing page. It adds no new routes and
links only to pages that already exist on `release/17.0`. CI covers the
build and link checks.

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
David Pine (IEvangelist) added a commit that referenced this pull request Nov 17, 2026
## Summary

Consolidates the open `docs-from-code` PRs that cover features from
@IEvangelist's product work or that request their review, all targeting
`release/17.0`, into this single PR. Each PR was checked against its
merged microsoft/aspire source PR and against product `release/17.0`, to
confirm the change shipped in 17.0 and is user-facing rather than an
implementation detail. Accepted text was corrected where the bot's
wording was inaccurate.

| PR(s) | Verdict | Notes |
| --- | --- | --- |
| #2103, #2098, #1967, #2073, #2070 | Accepted with fixes | Go AppHost
conventions, `aspire init`, and VS Code extension. Unrelated e2e test
edits from #2073 were dropped. |
| #1972 | Partially accepted | Only the verified behavior was kept. |
| #2069, #2064, #1829 | Accepted with fixes | Dashboard explore page and
`aspire describe --format Mermaid` |
| #2044 | Partially accepted | The Cards/Home/Graph layout selector text
is outdated, so it was dropped. |
| #1959, #1904, #1835, #1801 | Accepted with fixes | `WithTerminal`
options, the dashboard terminal UX, and TypeScript `configure` |
| #1902 | Accepted with fixes | `dotnet run --operation publish`
guidance |
| #2081 | Accepted with fixes | WSLc limited publish support. The
minimum version is corrected to 3.0.4.0. |
| #2014, #1862, #1809, #1936, #2140, #1997, #2051, #2068, #2022, #1963 |
Accepted with fixes | DCP timeouts, the container tunnel base image,
browser origins, the PVC `WithConfiguration` API, the interaction
service caution, secrets, `aspire update`, and agent init telemetry |
| #2092 | Rejected | Documents implementation details. |
| #2078 | Rejected | Already documented correctly; the proposed text was
wrong. |
| #2110, #2104, #2085, #2094 | Rejected | The product change isn't in
`release/17.0`; it's 17.1-only. Redo these against the next release
branch. |
| #2133 | Rejected for now | Its backport, microsoft/aspire#22219, is
still open, so redo this once it merges. |

Additional consistency fixes:

- **WSLc:** the minimum version is now 3.0.4.0, the source's
`MinimumWslcVersion`, across prerequisites, `aspire doctor`,
configuration, and what's new. The pages now describe limited publish
support and state that Docker Compose isn't supported.
- **`WithTerminal`:** `WithTerminal` and `TerminalOptions` are no longer
`[Experimental]` in 17.0. I removed the stale `ASPIRETERMINAL001`
pragmas and cautions and rewrote the diagnostic page to cover the
terminal APIs that are still experimental.

Closes #2140
Closes #2133
Closes #2110
Closes #2104
Closes #2103
Closes #2098
Closes #2094
Closes #2092
Closes #2085
Closes #2081
Closes #2078
Closes #2073
Closes #2070
Closes #2069
Closes #2068
Closes #2064
Closes #2051
Closes #2044
Closes #2022
Closes #2014
Closes #1997
Closes #1972
Closes #1967
Closes #1963
Closes #1959
Closes #1936
Closes #1904
Closes #1902
Closes #1862
Closes #1835
Closes #1829
Closes #1809
Closes #1801

## Third-party links and affiliations

None. The only added external link is to mermaid.js.org, which the page
already links elsewhere.

## Validation

- I compared each claim with the merged microsoft/aspire source and
checked that it's included in product `release/17.0`, using `gh api
compare` and searches for backport PRs.
- I checked the TypeScript sample against the generated `aspire.d.ts`.
`EndpointReferenceExpression` is an `IValueProvider`.
- I reviewed the full diff by hand for MDX and table formatting,
imports, and anchors. The new `seoTitle` is 58 characters.
- I didn't run any local unit, e2e, or build commands because frontend
dependencies aren't installed locally. CI covers the build, unit, and
e2e checks, including the updated `custom-components.spec.ts` assertion.

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danegsta
David Negstad (danegsta) marked this pull request as draft November 17, 2026 18:49
@danegsta

Copy link
Copy Markdown
Member

This feature is in main only and not backported to release/17.0 yet. We're currently targeting a 17.0.1 patch.

@maddymontaquila
Maddy Montaquila (maddymontaquila) force-pushed the docs/pr-22182-43283818630-1-ba985eee6581fb1f branch from 39a7fb0 to d184e21 Compare November 17, 2026 19:24
@maddymontaquila
Maddy Montaquila (maddymontaquila) changed the base branch from release/17.0 to main November 17, 2026 19:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs-from-code Copilot initiated issue from dotnet/aspire repo

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants