Repository navigation
[docs] Document configured channel for aspire update - #2133
aspire-repo-bot[bot] wants to merge 1 commit into
Conversation
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
There was a problem hiding this comment.
🟡 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
--channelor--qualityis 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. |
…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>
## 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>
|
This feature is in main only and not backported to release/17.0 yet. We're currently targeting a 17.0.1 patch. |
39a7fb0 to
d184e21
Compare

Documents changes from microsoft/aspire#22182
Author:
@danegstaTargeting
release/17.0— the latest release branch onmicrosoft/aspire.dev— becauserelease/17.1(from the source PR milestone17.1) does not exist there.Why
aspire updatefor C# AppHosts now honors the configuredchannelsetting when--channel/--qualityisn'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—--channeloption section now describes configured-channel behavior, lookup order, messaging, and failure behavior.