[docs] Clarify --channel version-pinning behavior for aspire new

[aspire-repo-bot]

Documents changes from microsoft/aspire#17564 by @sebastienros.

Target branch

Targeting release/13.4 based on the source PR milestone 13.4 (exact match on microsoft/aspire.dev).

Why this PR is needed

The source PR fixed a bug in aspire new where using --channel daily (or other pre-release channels) could cause the CLI to pull template packages from a newer version than the installed CLI/SDK. For example, a 13.4 CLI using --channel daily might previously resolve Aspire.ProjectTemplates 13.5.x-preview, causing assembly loader errors (Aspire.TypeSystem, Version=13.5.0.0) and failures like No language support found for: typescript/nodejs.

The fix pins template resolution to the current CLI/SDK version when a channel is selected. The documentation for the --channel option on the aspire new command reference page did not explain this version-pinning behavior.

What changed

• Updated src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx — expanded the --channel option description to explain that aspire new always selects template packages matching the currently installed CLI/SDK version when a channel is specified, and that this prevents pulling newer pre-release templates from channel feeds.

Files modified

• src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx (updated)

Generated by PR Documentation Check for issue #17564 · ● 9.9M · ◷

[Copilot]

Pull request overview

Updates the aspire new CLI reference documentation to clarify how --channel affects template package version selection, aligning the docs with the behavior change from microsoft/aspire#17564.

Changes:

• Expanded the --channel option description to explain version-pinning behavior to the installed CLI/SDK version when selecting templates from a channel feed.

---

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

[IEvangelist]

Docs accuracy review

Source of truth: microsoft/aspire@cc4b7eaf (release/13.4, fetched 2026-05-29)
PR head: ed7ae1f0c769fc93b8fc2454c473c75b080746ce

Verdict	Count
verified	2
verified-with-nuance	1
unverifiable	0
contradicted	0

Verdict: COMMENT. The 13.4 CLI / --channel daily example is reproduced verbatim from the source comment that documents this fix. One small precision nuance: the "always" framing is exact for non-stable explicit channels and for any channel where the CLI version exactly matches a published template package; the stable channel doesn't apply the forced-pin fallback.

Doc-tester (UX) notes

The user-visible behavior the doc describes ("a 13.4 CLI using --channel daily will not pull 13.5 preview templates") is exactly the scenario the source comment uses as its motivating example. A first-time reader gets the right mental model for why --channel exists and what it protects against.

Verified claims (with evidence)

#	Claim	Evidence
1	"When a channel is specified, aspire new ... selects template packages whose version matches the currently installed CLI/SDK version." (with the nuance flagged in #3)	src/Aspire.Cli/Commands/NewCommand.cs:180-190 — TryGetCurrentCliTemplateVersionPackage first asks VersionHelper.TryGetCurrentCliVersionMatch(packages, p => p.Version, out ...) for an exact CLI-version match across the channel's template packages and returns that match when found.
2	Example: "a 13.4 CLI using --channel daily will not pull 13.5 preview templates even if the daily feed contains them."	NewCommand.cs:197-203 — the source comment reads almost verbatim: "Prerelease channels (daily, staging) filter the shipped stable package ... For those channels, pinning to the running CLI's SDK version keeps the bundled server and the restored Aspire packages in lock-step. Without this, aspire new --channel daily on a shipped 13.4 CLI floats templates to a 13.5 daily preview, which then breaks the bundled 13.4 AppHost server with Aspire.TypeSystem, Version=13.5.0.0 assembly load errors followed by No language support found for: typescript/nodejs." The fallback (:212-217) builds a synthetic NuGetPackage pinned to VersionHelper.GetDefaultSdkVersion() for non-stable explicit channels when no exact match was found in the feed.

Verified-with-nuance

#	Claim	Nuance
3	"always selects template packages whose version matches the currently installed CLI/SDK version."	The forced-pin fallback (NewCommand.cs:192-218) is gated on selectedChannel.Type is PackageChannelType.Explicit && Name != Stable && !IsLocalBuildChannel. For --channel stable with no exact CLI-version match in the feed, the code falls through to the OrderByDescending picker (see comment at :205-211: "The stable channel is excluded here on purpose..."). In that case aspire new picks the highest published stable template package, which won't necessarily match the CLI's SDK version (e.g. a 13.4.1 CLI on a stable feed that has only published 13.4.0). In practice the shipped stable feed tracks the CLI version closely enough that users won't see the gap, but "always" reads more strongly than the implementation guarantees. Suggested wording: "When a non-stable channel is specified (daily, staging, pr-<N>), aspire new pins template packages to the currently installed CLI/SDK version..."