[docs] Document ASPIRE010 inline help link in CLI bundle docs - #1504
[docs] Document ASPIRE010 inline help link in CLI bundle docs#1504aspire-repo-bot[bot] wants to merge 1 commit into
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
aspire-repo-bot
Bot
added
the
docs-from-code
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.
Pull request overview
This PR updates the Aspire SDK “CLI bundle” documentation to explicitly describe the ASPIRE010 warning behavior and how its help link is surfaced in console build output, aligning aspire.dev guidance with the referenced upstream documentation change.
Changes:
- Added a new bullet under the
AspireUseCliBundlesection describing when warningASPIRE010is emitted. - Documented that the warning text includes the
aka.msdiagnostics URL inline so it shows up in terminal/console output (not only via MSBuildHelpLinkmetadata).
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| 1. Explicit `AspireCliBundlePath` / `AspireCliPath` properties in the project file. | ||
| 2. The `aspire` executable on `PATH`. | ||
| - If the bundle cannot be found, the build emits error `ASPIRE009` with a message directing you to [get.aspire.dev](https://get.aspire.dev) to install the Aspire CLI. | ||
| - If your AppHost sets `AspireUseCliBundle` to `false` (opting out after previously opting in, or overriding a default of `true`), the build emits warning `ASPIRE010`. The warning text includes a direct link to `https://aka.ms/aspire/diagnostics/aspire010` so the help link is visible in console/terminal build output, not just in the `HelpLink` metadata. |
David Pine (IEvangelist)
left a comment
David Pine (IEvangelist)
left a comment
There was a problem hiding this comment.
🤖 Automated docs-accuracy review
Phase A source of truth: microsoft/aspire @ release/13.5 (SHA ca6cbec37b822bf2ec5ee5eb76bb4a7bda2fedcd)
Claims extracted: 4 — ✅ verified: 3 ·
Phase B (doc-tester): 1 page exercised (/get-started/aspire-sdk/) · 0 critical · 2 warnings
Verdict: COMMENT — every factual claim in the added sentence checks out against the release branch. One wording nuance (Phase A) and two rendered-page readability observations (Phase B) are worth a look; none are blocking.
Phase A — Claim verification
All four factual sub-claims in the single added line are supported by Aspire.Hosting.AppHost.in.targets on release/13.5. There are no contradicted or unverifiable claims, so no inline blocking comments. One item is verified-with-nuance.
✅ Verified & ⚠️ verified-with-nuance claims (4) — evidence
C1 — ✅ verified (api-behavior)
"If your AppHost sets
AspireUseCliBundletofalse… the build emits warningASPIRE010."
Evidence: src/Aspire.Hosting.AppHost/build/Aspire.Hosting.AppHost.in.targets:156-159 — Target Name="_WarnOnAspireCliBundleDisabled" with Condition="'$(IsAspireHost)' == 'true' and '$(AspireUseCliBundle)' == 'false'" emits <Warning Code="ASPIRE010" … />.
C2 — api-behavior)
"(opting out after previously opting in, or overriding a default of
true)"
Evidence for "a default of true": the project templates set the property to true — src/Aspire.ProjectTemplates/templates/aspire-apphost/Aspire.AppHost1.csproj:8, …/aspire-empty/…AppHost.csproj:8, …/aspire-starter/…AppHost.csproj:8, …/aspire-ts-cs-starter/…AppHost.csproj:8, and src/Aspire.Cli/Templating/Templates/empty-apphost/apphost.cs:2 (#:property AspireUseCliBundle=true).
Nuance: the SDK/build default when the property is unset is false, not true — src/Aspire.AppHost.Sdk/SDK/Sdk.in.targets:25 and src/Aspire.Hosting.AppHost/build/Aspire.Hosting.AppHost.props:7 both resolve to false when empty. So "a default of true" is accurate for new projects generated from Aspire templates, but is not the SDK-level default (this same page frames AspireUseCliBundle as a preview opt-in). The warning fires purely on the resolved value being false, regardless of prior state or where the value came from. Consider wording like "a template default of true" to avoid implying the SDK itself defaults to true.
C3 — ✅ verified (config-key)
"The warning text includes a direct link to
https://aka.ms/aspire/diagnostics/aspire010"
Evidence: Aspire.Hosting.AppHost.in.targets:158 — Text="… See https://aka.ms/aspire/diagnostics/aspire010 for more information."
C4 — ✅ verified (api-behavior)
"so the help link is visible in console/terminal build output, not just in the
HelpLinkmetadata."
Evidence: the URL appears inside Text= (line 158, which MSBuild renders to console/terminal output) and separately as the HelpLink= attribute (line 159). This confirms the URL is embedded in the message text, not only in HelpLink metadata.
Phase B — Doc-tester results
Blind "new user" pass; Aspire source code was not consulted for this phase. Served the PR head (bc1ae1d) locally via pnpm dev at http://localhost:4321/ and viewed /get-started/aspire-sdk/ in a browser.
Documentation Test Report
Focus Area: get-started/aspire-sdk → section "Use the Aspire CLI bundle for orchestration dependencies" (the one bullet this PR adds)
Date: 2026-08-15
Tester: doc-tester agent
Summary
| Category | Passed | Failed | Warnings |
|---|---|---|---|
| Content Accuracy | 1 | 0 | 1 |
| Code Examples | n/a | 0 | 0 |
| CLI Commands | n/a | 0 | 0 |
| Links | 1 | 0 | 1 |
Critical Issues
None.
Warnings
Warning 1: A "When AspireUseCliBundle is true" list ends with a "when it's false" bullet
- Location:
/get-started/aspire-sdk/→ "Use the Aspire CLI bundle for orchestration dependencies", inside the bullet list introduced by "WhenAspireUseCliBundleistrue:". - Issue: The new bullet describes what happens when the AppHost sets the value to
false, yet it sits in a list explicitly framed as thetruecase. As a first-time reader I had to re-read to notice this bullet flips the condition. - Suggestion: Pull the
false/ASPIRE010behavior out of the "when true" list (its own sentence or a separate bullet group), or reword the list intro so both outcomes fit.
Warning 2: "direct link" renders as plain code, not a clickable link
- Location: same bullet.
- Issue: The sentence says the warning includes "a direct link to
https://aka.ms/aspire/diagnostics/aspire010", but on the rendered page that URL is inline code (non-clickable), whereas the neighboringASPIRE009bullet rendersget.aspire.devas an actual link. - Note: Likely intentional — the sentence describes the link that appears in build console output, not a docs hyperlink — so this may be by design. Flagging only because "direct link" next to a bare, non-clickable URL is slightly ambiguous on the page.
Passed Checks
- Page loads and renders without errors (0 browser console errors).
- The added bullet displays correctly;
AspireUseCliBundle,false,true,ASPIRE010, the URL, andHelpLinkall render as inline code as intended. - Wording is consistent with the adjacent
ASPIRE009bullet.
Recommendations
- Priority fixes: none (no critical issues).
- Documentation gaps: clarify where the "default of
true" comes from so a reader doesn't infer the SDK defaults totrue. - Product issues: none discovered.
Knowledge gaps
- From the page alone it is not stated where the "default of
true" originates (template vs. SDK). A new reader can't resolve this without prior knowledge.
Reviewed at PR head SHA bc1ae1d8a7e8d21daa61a8a07666727766819ba2.
| 1. Explicit `AspireCliBundlePath` / `AspireCliPath` properties in the project file. | ||
| 2. The `aspire` executable on `PATH`. | ||
| - If the bundle cannot be found, the build emits error `ASPIRE009` with a message directing you to [get.aspire.dev](https://get.aspire.dev) to install the Aspire CLI. | ||
| - If your AppHost sets `AspireUseCliBundle` to `false` (opting out after previously opting in, or overriding a default of `true`), the build emits warning `ASPIRE010`. The warning text includes a direct link to `https://aka.ms/aspire/diagnostics/aspire010` so the help link is visible in console/terminal build output, not just in the `HelpLink` metadata. |
There was a problem hiding this comment.
This warning is nested under When AspireUseCliBundle is true, but it only applies when the property is false. Could we move it outside this list? As written, the condition reads as impossible.
Documents changes from microsoft/aspire#19375
@joperezrTargeting
release/13.5— the latest release branch onmicrosoft/aspire.dev— becauserelease/13.6(from the source PR milestone13.6) does not exist there.Why this PR is needed
Source PR microsoft/aspire#19375 updated
docs/list-of-diagnostics.md(triggering thediagnostic_documentation_changedsignal) to surface theASPIRE010help link ((aka.ms/redacted) inline in the warning text, since MSBuild'sHelpLinkmetadata isn't rendered in console/terminal build output. The aspire.dev docs describeASPIRE009/AspireUseCliBundlebehavior inget-started/aspire-sdk.mdxbut didn't mentionASPIRE010at all (only thewhats-new/aspire-13-5.mdx` release notes mention it in passing).What changed
src/frontend/src/content/docs/get-started/aspire-sdk.mdx: added a bullet describing whenASPIRE010is emitted (opting out ofAspireUseCliBundle) and noting that the warning text now includes theaka.mshelp link directly in console output.Files modified
src/frontend/src/content/docs/get-started/aspire-sdk.mdx(updated)No new pages were created; this is a small addition to an existing reference page.