[docs] Document ASPIREWATCH001 run mode configuration diagnostic - #1471
Conversation
Documents microsoft/aspire#18863, which adds RunConfiguration and the experimental ASPIREWATCH001 diagnostic. 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
Adds documentation for the new experimental ASPIREWATCH001 diagnostic so users can understand when it appears and how to suppress it, and wires the page into the diagnostics index and navigation.
Changes:
- Added a new diagnostics page documenting
ASPIREWATCH001, including a usage example and suppression guidance. - Added
ASPIREWATCH001to the diagnostics overview table. - Added
ASPIREWATCH001to the Reference sidebar under Warnings.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| src/frontend/src/content/docs/diagnostics/overview.mdx | Adds ASPIREWATCH001 to the diagnostics table for discoverability. |
| src/frontend/src/content/docs/diagnostics/aspirewatch001.mdx | New dedicated documentation page for the ASPIREWATCH001 warning. |
| src/frontend/config/sidebar/reference.topics.ts | Adds the new diagnostic page to the sidebar navigation. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 32c349b4-907d-42e9-aad8-2f0edc267779
| @@ -0,0 +1,85 @@ | |||
| --- | |||
| title: Compiler Warning ASPIREWATCH001 | |||
| seoTitle: "ASPIREWATCH001: Run mode configuration types and members are for" | |||
There was a problem hiding this comment.
This seoTitle ends mid-sentence at “are for”, so search results will show a truncated title. Could we use a complete title, maybe ASPIREWATCH001: Experimental run mode configuration APIs?
Co-authored-by: David Pine <david.pine@microsoft.com>
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 8ab6999850d96e0023670799edbd4bdc245ad63c)
Claims extracted: 15 → ✅ 14 verified, 🟡 1 verified-with-nuance, unverifiable, ❌ 0 contradicted
Phase B (doc-tester): served PR head 271fc817 at http://localhost:4321/ · pages exercised: /diagnostics/aspirewatch001/, /diagnostics/overview/, /app-host/resource-lifetimes/, /get-started/glossary/ · 0 critical, 1 warning
Verdict: 💬 COMMENT — every factual claim matches the source on release/13.5; one navigation warning from the blind‑user pass is worth addressing.
Phase A — Claim verification (microsoft/aspire@release/13.5)
No contradicted or unverifiable claims. Every API‑shape, behavior, config, and cross‑reference claim in the diff matches the source on the release branch.
✅ Verified claims (15) with evidence — expand to audit
Evidence paths are on microsoft/aspire@8ab6999850d96e0023670799edbd4bdc245ad63c.
| # | Claim | Verdict | Evidence |
|---|---|---|---|
| C1 | RunConfiguration class exists |
verified | src/Aspire.Hosting/RunConfiguration.cs:20 — public sealed class RunConfiguration |
| C2 | DistributedApplicationExecutionContext.RunConfiguration property |
verified | src/Aspire.Hosting/DistributedApplicationExecutionContext.cs:70 — public RunConfiguration RunConfiguration { get; } |
| C3 | DistributedApplicationExecutionContextOptions.RunConfiguration property |
verified | src/Aspire.Hosting/DistributedApplicationExecutionContextOptions.cs:66 — public RunConfiguration RunConfiguration { get; init; } |
| C4 | All three marked [Experimental("ASPIREWATCH001", …)] |
verified | RunConfiguration.cs:18, DistributedApplicationExecutionContext.cs:69, DistributedApplicationExecutionContextOptions.cs:65 |
| C5 | RunConfiguration.WatchEnabled is a bool |
verified | RunConfiguration.cs:38 — public bool WatchEnabled { get; init; } |
| C6 | WatchEnabled = "watch mode if able … hint … normal fashion" |
verified | RunConfiguration.cs XML doc (≈ lines 31‑36), near‑verbatim to the PR prose |
| C7 | In publish mode every property holds its default value | verified | RunConfiguration.cs remarks ("In Publish mode every property holds its default value") + DistributedApplicationExecutionContext.cs:56 (Publish → RunConfiguration.Default) |
| C8 | RunConfiguration applies only in run mode; integrations vary launches without changing core hosting behavior |
verified | RunConfiguration.cs summary + remarks (second sentence verbatim) |
| C9 | Example uses builder.ExecutionContext.IsRunMode / .RunConfiguration / .WatchEnabled |
verified | IsRunMode DistributedApplicationExecutionContext.cs:109; ExecutionContext DistributedApplicationBuilder.cs:99; mirrors tests/Aspire.Hosting.Tests/OperationModesTests.cs |
| C10 | Overview lists it as "(Experimental) Warning" with the standard message | verified | [Experimental] defaults to a warning; no .editorconfig/.props escalation to error for ASPIREWATCH001 (consistent with ASPIREUSERSECRETS001) |
| C11 | Suppress via .editorconfig severity = none, NoWarn, #pragma warning disable ASPIREWATCH001 |
verified | Correct diagnostic ID; #pragma warning disable ASPIREWATCH001 is itself used in DistributedApplicationBuilder.cs:11 and DistributedApplicationExecutionContext.cs:53 |
| C12 | Badge "Version introduced: 13.5" | verified‑with‑nuance | Present on release/13.5; source PR microsoft/aspire#18863 is milestone 13.5. Presence confirmed on 13.5; not diffed against 13.4 to prove first introduction. |
| C13 | Link /app-host/resource-lifetimes/ — target exists |
verified | Resolves HTTP 200 (but see Phase B Warning 1 on relevance) |
| C14 | Link /diagnostics/overview/#suppress-in-the-editorconfig-file |
verified | Heading "Suppress in the .editorconfig file" → anchor suppress-in-the-editorconfig-file matches |
| C15 | Sidebar + overview table link to /diagnostics/aspirewatch001/ |
verified | New page created at that route in this same PR |
Phase B — doc-tester results (blind user, live site only)
Focus area: ASPIREWATCH001 diagnostic page + diagnostics overview table + reference sidebar
Served: PR head 271fc817 via pnpm dev at http://localhost:4321/
Tester: doc-tester agent — navigated the rendered site with browser automation; no microsoft/aspire source consulted in this phase.
Summary
| Category | Passed | Failed | Warnings |
|---|---|---|---|
| Content Accuracy | 5 | 0 | 0 |
| Code Examples | 3 | 0 | 0 |
| Links | 4 | 0 | 1 |
| Navigation / Render | 3 | 0 | 0 |
Critical Issues
None.
Warnings
Warning 1: the "run mode" link lands on a page that never explains run mode
Location: /diagnostics/aspirewatch001/ → "Understanding run mode configuration" (new file, line 48)
Issue: The sentence "RunConfiguration holds settings that only apply when the AppHost is running in run mode (as opposed to publish mode)…" links the phrase run mode to /app-host/resource-lifetimes/. That page is titled "Configure resource lifetimes in Aspire" and covers session / persistent / parent‑process / resource‑scoped lifetimes. A full‑text search of the rendered page for "run mode" and "publish mode" returns no matches, so a new user who clicks "run mode" to learn what run mode (vs publish mode) means does not find that concept there.
Evidence: /app-host/resource-lifetimes/ headings — Lifetime modes → Session/Persistent/Parent‑process/Resource‑scoped lifetime, Defer resource start…, Configure a persistent container/executable/project, Match another resource's lifetime, …. No "run mode"/"publish mode" text.
Suggestion: Re‑target the link to a page that actually defines the modes. On this same build, /get-started/glossary/#run-mode has a dedicated Run mode heading ("Run mode is local development. When you execute aspire run…") and a sibling Publish mode heading — a far better fit for "(as opposed to publish mode)". e.g. [run mode](/get-started/glossary/#run-mode/).
Passed Checks
- Page renders at
/diagnostics/aspirewatch001/(HTTP 200, title "Compiler Warning ASPIREWATCH001 | Aspire"); 0 console errors, 0 console warnings. - "Version introduced: 13.5" badge renders.
- Experimental‑message blockquote renders.
- The three inline API references render (
RunConfiguration,DistributedApplicationExecutionContext.RunConfiguration,DistributedApplicationExecutionContextOptions.RunConfiguration). - "Reading run mode configuration" example renders with a working copy button; the code is internally consistent (
IsRunModegate → readRunConfiguration→ checkWatchEnabled). WatchEnabledsubsection renders with its description.- All three suppression methods render (
.editorconfigseverity = none,<NoWarn>,#pragma warning disable/restore). - Diagnostics overview table shows the new row: ASPIREWATCH001 →
/diagnostics/aspirewatch001/· "(Experimental) Warning" · correct message; the row link resolves. - The page's anchor link
/diagnostics/overview/#suppress-in-the-editorconfig-fileresolves to the real heading. - Sidebar entry "ASPIREWATCH001" is present under Warnings and navigates to the new page.
Recommendations
- Priority fix: re‑target the "run mode" link to a page that defines run vs publish mode (for example
/get-started/glossary/#run-mode/). - No documentation gaps or product issues otherwise — the page is accurate and copy‑paste ready as rendered.
Knowledge gap
The new page relies on the "run mode" link to teach the reader what "run mode (as opposed to publish mode)" means. Because the linked page omits that concept, a blind user has to fall back on prior knowledge to understand the distinction the page is built around.
Reviewed revision 271fc81721bbb1553d83eb1936e6a2fb30ec3d10. Phase A read only from microsoft/aspire@release/13.5; Phase B consulted only the locally‑served, rendered docs site.
|
|
||
| ## Understanding run mode configuration | ||
|
|
||
| `RunConfiguration` holds settings that only apply when the AppHost is running in [run mode](/app-host/resource-lifetimes/) (as opposed to publish mode). Integrations use it to vary how their resources are launched without changing the core hosting behavior. |
There was a problem hiding this comment.
[doc-tester / Phase B] The "run mode" link target doesn't explain run mode.
This links run mode to /app-host/resource-lifetimes/, but that page ("Configure resource lifetimes in Aspire") never mentions "run mode" or "publish mode" — a full-text search of the rendered page returns no matches, so a reader who clicks here to learn the concept won't find it.
On this build, /get-started/glossary/#run-mode has dedicated Run mode and Publish mode headings and is a better target for "(as opposed to publish mode)":
[run mode](/get-started/glossary/#run-mode/)
5db4f1d
into
release/13.5
Documents changes from microsoft/aspire#18863
@karolz-msTargeting
release/13.5based on the source PR milestone13.5.Why
microsoft/aspire#18863 adds a new experimental
RunConfigurationtype and aDistributedApplicationExecutionContextOptions.RunConfiguration/DistributedApplicationExecutionContext.RunConfigurationproperty, both marked[Experimental("ASPIREWATCH001", ...)]. This diagnostic previously had no entry on the docs site.What changed
src/frontend/src/content/docs/diagnostics/aspirewatch001.mdx— describes theRunConfigurationclass and itsWatchEnabledproperty, includes a usage example, and documents the standard suppression methods (.editorconfig,NoWarn,#pragma warning disable), following the same structure as the existingASPIREPROBES001page.src/frontend/src/content/docs/diagnostics/overview.mdx— addedASPIREWATCH001to the diagnostics table.src/frontend/config/sidebar/reference.topics.ts— added the new page to the sidebar's Warnings list.No existing pages needed structural changes; this is purely additive.