[docs] Document AspireCliInvocationMode for dotnet run DNX invocation

[aspire-repo-bot]

Documents changes from microsoft/aspire#19310

@DamianEdwards

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

Why

Source PR microsoft/aspire#19310 adds AspireCliInvocationMode=Dnx support for AppHosts started via dotnet run, allowing DNX to honor an in-scope .NET local tool manifest (.config/dotnet-tools.json) that pins Aspire.Cli, instead of only invoking the pinned SDK-paired version. It also renames the previous Dnx behavior to DnxPinned and updates the ASPIRE011 diagnostic message accordingly. This is a user-facing MSBuild property behavior change with no prior documentation of AspireCliInvocationMode on the docs site.

What changed

• src/frontend/src/content/docs/get-started/aspire-sdk.mdx: Added a new "Running with dotnet run" subsection under "Use the Aspire CLI bundle for orchestration dependencies", documenting the AspireCliInvocationMode property and its three supported values (Path, Dnx, DnxPinned), including the ASPIRE011 error scenario and remediation.

This is an update to an existing page (no new pages created).

Generated by PR Documentation Check for #19310 · auto · 91.3 AIC · ⌖ 11 AIC · ⊞ 19.6K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

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

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

[Copilot]

Pull request overview

This PR updates the Aspire SDK “Use the Aspire CLI bundle for orchestration dependencies” documentation to cover the new AspireCliInvocationMode behavior when running an opted-in AppHost via dotnet run, aligning the docs site with the behavior change introduced in microsoft/aspire#19310.

Changes:

• Adds a new “Running with dotnet run” subsection describing AspireCliInvocationMode and its supported values (Path, Dnx, DnxPinned).
• Documents the ASPIRE011 failure mode when dnx isn’t available and provides remediation guidance.

Suppressed comments (1)

src/frontend/src/content/docs/get-started/aspire-sdk.mdx:168

• The note says ASPIRE011 is emitted only when Dnx/DnxPinned is configured, but the Path mode description above also states it can fall back to invoking via dnx when no compatible aspire is found. Clarifying that ASPIRE011 can also occur in that fallback scenario makes the troubleshooting guidance consistent.

`dotnet run` is noninteractive, so `dnx` restores and executes without prompting for confirmation. If `dnx` can't be found on `PATH` when `Dnx` or `DnxPinned` mode is configured, the build emits error `ASPIRE011`. Install or use the .NET SDK 10.0 or later, set `AspireCliInvocationMode` to `Path` to use the global `aspire` command, or set `AspireCliPath` to an explicit Aspire CLI executable.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[David Pine (IEvangelist)]

Automated docs-accuracy review — Phase A (claims) + Phase B (doc-tester)

Phase A source of truth: microsoft/aspire @ release/13.5, SHA 8ab6999850d96e0023670799edbd4bdc245ad63c (matches this PR's base).
Reviewed head SHA: 5c395bb080699c51b3e4bd523d7ee0d59cd4bec5.

Phase A — claims: 9 non-narrative claims extracted → 9 verified, 0 verified-with-nuance, 0 unverifiable, 0 contradicted.
Phase B — doc-tester: 1 page exercised (/get-started/aspire-sdk/, anchor #running-with-dotnet-run) → 0 critical, 1 warning, 0 knowledge gaps.

Verdict: COMMENT — every factual claim in the new "Running with dotnet run" section is verified against the SDK targets; the only finding is a Phase B discoverability warning (non-blocking).

---

Phase A — Claim verification

No contradicted or unverifiable claims. The new section mirrors the SDK's own MSBuild targets and docs/list-of-diagnostics.md closely.

Verified claims (9) with source evidence

Evidence paths are in microsoft/aspire @ release/13.5 (8ab6999). Primary file: src/Aspire.Hosting.AppHost/build/Aspire.Hosting.AppHost.in.targets.

• AspireUseCliBundle=true opts in to CLI delegation — verified. Aspire.Hosting.AppHost.in.targets:156,214,235,448,571; summarized in docs/list-of-diagnostics.md:18.
• AspireCliInvocationMode controls how the SDK invokes the CLI under dotnet run — verified. Aspire.Hosting.AppHost.in.targets:200-201; src/Aspire.Hosting.Tasks/ResolveAspireCliInvocation.cs:23.
• Path (default): resolve aspire from PATH, else fall back to the Aspire.Cli version paired with Aspire.AppHost.Sdk via dnx — verified. Default Path at targets:200; explanatory comment targets:204-206; docs/list-of-diagnostics.md:18.
• Dnx: always via dnx, unversioned aspire.cli, honoring an in-scope .config/dotnet-tools.json tool manifest (else latest) — verified. _AspireCliDnxPackageId=aspire.cli at targets:208, invoked unversioned at targets:209; comment targets:204-206; docs/list-of-diagnostics.md:18.
• DnxPinned: always via dnx, aspire.cli@<version> pinned to the exact Aspire.Cli version paired with the SDK — verified. aspire.cli@$(AspireHostingSDKVersion) at targets:210; docs/list-of-diagnostics.md:18.
• AspireCliPath names an explicit CLI executable — verified. Remediation text at targets:622; consumed by ResolveAspireCliInvocation.
• ASPIRE011 is emitted when dnx is not on PATH in Dnx/DnxPinned — verified. <Error Code="ASPIRE011" ...> at targets:620; docs/list-of-diagnostics.md:16.
• dotnet run is noninteractive, so dnx restores and executes without prompting — verified. Comment "dotnet run is noninteractive, so DNX cannot ask for confirmation" at targets:599; dnx invoked with --yes at targets:601.
• Requires .NET SDK 10.0 or later; remediation is AspireCliInvocationMode=Path or AspireCliPath — verified. Error remediation text at targets:622.

External cross-references (learn.microsoft.com dnx docs and .NET local-tools manifest docs) are outside microsoft/aspire and out of scope for source verification; Phase B confirmed they render as links.

---

Phase B — Doc-tester results

Report reproduced verbatim from the doc-tester skill run (blind to source; navigation via Playwright; served locally with pnpm dev).

Documentation Test Report

Focus Area: PR #1484 AspireCliInvocationMode guidance for dotnet run
Date: 2026-08-14
Tester: doc-tester agent
Served Base URL: http://localhost:4321/
Served Head SHA: 5c395bb080699c51b3e4bd523d7ee0d59cd4bec5

Routes Exercised:

• http://localhost:4321/get-started/aspire-sdk/
• http://localhost:4321/get-started/aspire-sdk/#running-with-dotnet-run

Screenshots:

• pr1484-running-with-dotnet-run.png
• pr1484-running-with-dotnet-run-note.png

Summary

Category	Passed	Failed	Warnings
Content Accuracy	4	0	0
Code Examples	1	0	0
CLI Commands	0	0	0
Links	3	0	1

Critical Issues

None.

Warnings

Warning 1: New subsection is not directly reachable from "On this page" navigation

Location: http://localhost:4321/get-started/aspire-sdk/#running-with-dotnet-run
Issue: The "Running with dotnet run" heading renders and its direct anchor works, but it does not appear in the "On this page" navigation. The nav only lists the parent "Use the Aspire CLI bundle for orchestration dependencies" section, so readers scanning the page navigation may miss the new subsection.
Suggestion: Promote the heading level or otherwise make the subsection discoverable from the page navigation.

Passed Checks

• The Aspire SDK page loaded successfully.
• The direct anchor #running-with-dotnet-run resolved successfully.
• The "Running with dotnet run" subsection rendered without obvious formatting issues.
• The mode list rendered clearly with Path, Dnx, and DnxPinned.
• The dnx external documentation link rendered as a link.
• The .NET local tool manifest external documentation link rendered as a link.
• The XML MyApp.AppHost.csproj code block rendered with the expected title.
• The XML code block includes AspireUseCliBundle set to true.
• The XML code block includes AspireCliInvocationMode set to Dnx.
• The XML code block has a copy button.
• The Note callout rendered correctly.
• The note mentions noninteractive dnx, ASPIRE011, .NET SDK 10.0+, and AspireCliPath.

Recommendations

1. Priority fixes: None.
2. Documentation gaps: Improve discoverability by making "Running with dotnet run" visible in the "On this page" navigation.
3. Product issues: None discovered from blind documentation testing.

Knowledge Gaps

None.

---

Automated review: Phase A verifies claims against microsoft/aspire source at the release branch SHA; Phase B validates the rendered docs as a new user via the doc-tester skill. This is a non-blocking COMMENT.