[docs] cli: document channel persistence in aspire.config.json for init and update

[aspire-repo-bot]

test

Generated by PR Documentation Check for issue #17452 · ● 50.8M · ◷

[Copilot]

Pull request overview

Documents how the Aspire CLI persists the selected package/template channel by writing a top-level channel value into aspire.config.json, so later CLI commands continue using the same channel.

Changes:

• Add aspire update --channel documentation noting it rewrites aspire.config.json’s top-level channel.
• Add an aspire init section explaining when and why channel is persisted, including an example aspire.config.json.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx	Documents that switching channels via aspire update persists the channel in aspire.config.json.
src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx	Adds a section describing channel persistence behavior during aspire init, with an example config file.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[IEvangelist]

Docs accuracy review

Source of truth: microsoft/aspire@ad839e24 (main, fetched 2026-05-29)
PR head: e48b8d872cad7269c637cd4b02c92300754c7b83

Verdict	Count
verified	5
verified-with-nuance	2
unverifiable	0
contradicted	0
out-of-scope (pre-existing)	1

Overall: the channel-persistence behavior described in this PR matches the implementation in Aspire.Cli. Two inline comments below flag verified-with-nuance items worth tightening (the example simplifies profiles and the "implicit stable default" phrasing conflates two distinct channel kinds). Nothing is contradicted.

Doc-tester (UX) notes

I read the new section the way a new user would, top-to-bottom on the rendered aspire init page:

• "explicit" / "implicit" / "the packaging service" are internal PackageChannelType / PackagingService terms that surface in the prose without a definition. They're accurate, but a user landing on this section has no glossary for them. Consider linking once to a channels overview rather than introducing _explicit_ italics as new vocabulary.
• pr-<N> build is mentioned with no example expansion (e.g. pr-17452). A first-time reader can guess, but it's not stated anywhere on this page.
• The JSON example shows empty profiles objects. A real aspire init writes applicationUrl plus OTLP / resource-service endpoint env vars into both https and http profiles. Users who copy the example verbatim would have a config that aspire run cannot use. (Filed inline below.)
• The new section sits between "AppHost detection" and "The aspireify skill" — placement is fine; the heading is discoverable.

No broken links / nav, no missing prerequisites called out, and the section is self-contained enough that someone who already understands channels would learn the persistence behavior correctly.

Verified claims (with evidence)

ID	Claim	Evidence
c1	aspire init writes top-level channel into aspire.config.json when the CLI's identity channel is an explicit, non-stable channel (e.g. daily, staging, pr-<N>).	src/Aspire.Cli/Commands/InitCommand.cs:495-505 (ResolvePersistableChannelNameAsync gate) + :565-573 (DropAspireConfig writes settings["channel"]). Gate uses PackageChannel.ShouldPersistChannelName() (src/Aspire.Cli/Packaging/PackageChannel.cs:37-38). Channels registered in src/Aspire.Cli/Packaging/PackagingService.cs:88-145.
c2	aspire.config.json has a top-level channel string key.	src/Aspire.Cli/Configuration/AspireConfigFile.cs:93-95 — [JsonPropertyName("channel")] public string? Channel.
c3	Subsequent aspire add / aspire update / etc. resolve packages and templates against the persisted channel.	aspire add/integration commands: PackagingService.cs:130 reads _configuration["channel"]. aspire update: UpdateCommand.cs:194-198 calls GetConfigurationFromDirectoryAsync("channel", ...). Templates: PackageChannel.cs:60-79 GetTemplatePackagesAsync uses the same Mappings derived from the channel.
c5	If aspire.config.json already contains a channel, the value is preserved and not overwritten.	InitCommand.cs:570-573 only writes when settings["channel"] is null. Polyglot path adds defense-in-depth at :495-503 via TryLoadExistingChannel (:691-700).
c6	Only channels registered as explicit in the packaging service are persisted; implicit stable default is not.	PackageChannel.cs:30 derives Type (Implicit when mappings is null, otherwise Explicit). :37-38 ShouldPersistChannelName() returns true only for Type is Explicit && Name != Stable. PackagingService.cs:88 creates default as Implicit, lines 90/95/137/170 create stable/daily/staging/PR as Explicit.

Verified-with-nuance claims

ID	Claim	Nuance
c4	Example aspire.config.json shape (appHost.path, top-level channel, profiles{https,http}).	Shape is correct, but DropAspireConfig (InitCommand.cs:607-628) writes each profile with applicationUrl plus three environmentVariables (ASPIRE_DASHBOARD_OTLP_GRPC_ENDPOINT_URL, ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL, and ASPIRE_ALLOW_UNSECURED_TRANSPORT on http). The example shows empty {} objects.
c8	aspire update rewrites top-level channel when switching to a non-default explicit channel.	(1) ProjectUpdater.cs:222-229 only enqueues the ChannelUpdateStep when an aspire.config.json already exists — aspire update does not create one. (2) "Any value other than the implicit stable default" treats default (Implicit) and stable (Explicit) as one thing. ShouldPersistChannelName() (PackageChannel.cs:37-38) explicitly excludes both, by different mechanisms. The user-visible behavior is what the doc claims, but the phrasing collapses the distinction.

Out of scope

• aspire-update.mdx line 51 — Channel to update to (stable, staging, daily). is the pre-existing description of --channel; this PR does not modify it. (For reference, the underlying resource swaps between ChannelOptionDescription = "Channel to update to (stable, daily)" and ChannelOptionDescriptionWithStaging = "Channel to update to (stable, staging, daily)" — see UpdateCommandStrings.resx:137-148.)