[docs] Document new experimental APIs from Aspire.Hosting.Dotnet decoupling (ASPIREPROJECTS001)

[aspire-repo-bot]

Documents changes from microsoft/aspire#18918

@karolz-ms

Targeting release/13.5 based on the source PR milestone 13.5.

Why

PR #18918 decouples Aspire.Hosting.Dotnet (and other language packages) from Aspire.Hosting internals by promoting several previously-internal types to public, experimental API surface:

• New ASPIREPROJECTS001 diagnostic: WithProjectDefaults<T>, ProjectLaunchDefaultsAnnotation, and ProjectLaunchArgsOverrideAnnotation are now public/experimental.
• SupportsDebuggingAnnotation is now public (was internal), and gains a new public LaunchConfigurationType remark about implicit support for KnownLaunchConfigurationTypes.Project.
• New public types under ASPIREEXTENSION001: DebugSupportExtensions (SupportsDebugging, CreateLaunchConfigurationAsync), ExecutableLaunchConfiguration, ExecutableLaunchMode, KnownLaunchConfigurationTypes.

These are new experimental compiler diagnostics/APIs that need entries in the diagnostics catalog, per the existing pattern for other ASPIRE*001 experimental warnings.

Changes

• Added: src/frontend/src/content/docs/diagnostics/aspireprojects001.mdx — new diagnostic page for ASPIREPROJECTS001 (introduced in 13.5), inventorying WithProjectDefaults<T>, ProjectLaunchDefaultsAnnotation, and ProjectLaunchArgsOverrideAnnotation, with suppression instructions following the standard template.
• Updated: src/frontend/src/content/docs/diagnostics/overview.mdx — added a table row for ASPIREPROJECTS001.
• Updated: src/frontend/src/content/docs/diagnostics/aspireextension001.mdx — expanded the list of APIs covered by ASPIREEXTENSION001 to include the newly-public DebugSupportExtensions, ExecutableLaunchConfiguration, ExecutableLaunchMode, and KnownLaunchConfigurationTypes (previously internal/undocumented).

No new pages needed beyond the new diagnostic page; existing pages were updated in place.

Generated by PR Documentation Check · auto · 73.1 AIC · ⌖ 7.56 AIC · ⊞ 19.6K · ◷

[Copilot]

Pull request overview

This PR updates the Aspire diagnostics documentation to reflect newly public, experimental APIs introduced by the Aspire.Hosting.Dotnet decoupling work (ASPIREPROJECTS001 / ASPIREEXTENSION001), ensuring the diagnostics catalog stays aligned with the current experimental surface area in 13.5.

Changes:

• Adds a new diagnostic page documenting ASPIREPROJECTS001 and its associated project launch defaults APIs.
• Updates the diagnostics overview table to include ASPIREPROJECTS001.
• Expands ASPIREEXTENSION001 documentation to include newly public debug support APIs/types.

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 ASPIREPROJECTS001 to the diagnostics catalog table.
src/frontend/src/content/docs/diagnostics/aspireprojects001.mdx	New diagnostic page documenting ASPIREPROJECTS001, examples, and suppression guidance.
src/frontend/src/content/docs/diagnostics/aspireextension001.mdx	Updates the listed APIs covered by ASPIREEXTENSION001 to include newly public debug support types/members.

---

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

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1511. 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.

[David Pine (IEvangelist)]

Automated docs-accuracy review — PR #1511

Phase A source of truth: microsoft/aspire @ release/13.5 — SHA e076d8e427cb3afb528dbd605acd74c3aea69f94 (cross-checked release/13.4 @ 140ae21930b015454f08f06877d9a0ab69d4ed7e to confirm ASPIREPROJECTS001 is new in 13.5).
Claims: 12 non-narrative extracted — ✅ 9 verified · 🟡 3 verified-with-nuance · ⚠️ 0 unverifiable · ❌ 0 contradicted.
Phase B doc-tester: 3 routes exercised from PR head on a local pnpm dev — 0 critical, 1 knowledge-gap warning.

Verdict: COMMENT — every factual claim checks out against the release/13.5 source; the only note is a copy-paste caveat in the example (Phase B). No blocking issues.

---

Phase A — Claim verification

No contradicted or unverifiable claims, so there are no blocking inline comments. Full evidence below for audit.

✅ Verified / 🟡 verified-with-nuance claims (with source evidence)

#	Claim	Verdict	Evidence (microsoft/aspire @ release/13.5)
A1	ASPIREPROJECTS001 diagnostic id exists	✅ verified	src/Aspire.Hosting/ProjectResourceBuilderExtensions.cs:478 [Experimental("ASPIREPROJECTS001", …)]; ApplicationModel/ProjectLaunchDefaultsAnnotation.cs:15; test tests/Aspire.Hosting.Tests/ProjectResourceBuilderExtensionTests.cs:26 Assert.Equal("ASPIREPROJECTS001", attribute.DiagnosticId)
A2	WithProjectDefaults<T> extension method is covered by the diagnostic	🟡 nuance	ProjectResourceBuilderExtensions.cs:478-481. Real signature is WithProjectDefaults<TProjectResource>(this IResourceBuilder<TProjectResource>, ProjectResourceOptions options) with constraints class, IResourceWithEnvironment, IResourceWithEndpoints, IResourceWithArgs. <T> is a fine shorthand.
A3	ProjectLaunchDefaultsAnnotation is covered by the diagnostic	✅ verified	ApplicationModel/ProjectLaunchDefaultsAnnotation.cs:15-16 public sealed class ProjectLaunchDefaultsAnnotation with [Experimental("ASPIREPROJECTS001")]
A4	Opts into the same launch-profile / Kestrel / ASPNETCORE_URLS wiring as AddProject; resource must carry IProjectMetadata	✅ verified	ProjectResourceBuilderExtensions.cs:460-476 XML remarks ("launch profile selection and materialization, endpoints derived from launch profile and Kestrel configuration, ASPNETCORE_URLS … environment overrides"; "The resource must carry IProjectMetadata")
A5	Exists primarily for language integration packages (e.g. Aspire.Hosting.Dotnet) launched via the .NET SDK	✅ verified	ProjectResourceBuilderExtensions.cs:468-471 ("intended for language integration packages that add their own .NET resource type, such as Aspire.Hosting.Dotnet")
A6	Example uses new ProjectResourceOptions() + .WithProjectDefaults(options)	🟡 nuance	src/Aspire.Hosting/ProjectResourceOptions.cs:10 public class ProjectResourceOptions; signature at :480 takes ProjectResourceOptions options. Example type MyDotnetResource is illustrative — see Phase B note.
A7	"Version introduced: 13.5" and "(Experimental) Warning"	✅ verified	Present on release/13.5, absent on release/13.4 (0 occurrences); [Experimental] ⇒ warning severity
A8	overview description "Project launch defaults types and members are for evaluation purposes only …"	🟡 nuance	Not a literal source string — it is the diagnostics table's Description column, authored to match the standard [Experimental] boilerplate and neighboring rows. Semantics are correct.
A9	Suppression via dotnet_diagnostic.ASPIREPROJECTS001.severity = none and <NoWarn>$(NoWarn);ASPIREPROJECTS001</NoWarn>	✅ verified	Standard MSBuild/editorconfig suppression; diagnostic id confirmed (A1)
A10	DebugSupportExtensions.SupportsDebugging and .CreateLaunchConfigurationAsync are covered by ASPIREEXTENSION001	✅ verified	ApplicationModel/DebugSupportExtensions.cs:16 [Experimental("ASPIREEXTENSION001")], :17 class, :45 SupportsDebugging, :122 CreateLaunchConfigurationAsync
A11	ExecutableLaunchConfiguration, ProjectLaunchConfiguration, ExecutableLaunchMode, KnownLaunchConfigurationTypes are covered by ASPIREEXTENSION001	✅ verified	ApplicationModel/ExecutableLaunchConfiguration.cs — :16-17 ExecutableLaunchMode, :38-39 KnownLaunchConfigurationTypes, :78-79 ExecutableLaunchConfiguration, :107-108 ProjectLaunchConfiguration, all with [Experimental("ASPIREEXTENSION001")]
A12	Sidebar link ASPIREPROJECTS001 → /diagnostics/aspireprojects001	✅ verified	Internal cross-ref; target page added in this same PR (render confirmed in Phase B)

Note: ProjectLaunchConfiguration was added to the ASPIREEXTENSION001 list in the diff (not called out in the PR description) — it is a real public [Experimental("ASPIREEXTENSION001")] type, so the addition is correct.

---

Phase B — Doc-tester results (blind-user perspective, browser only)

Served from PR head 218a9efe via local pnpm dev (http://localhost:4321/, trailingSlash: always). Scoped to the PR's changed routes:

• /diagnostics/aspireprojects001/ (new)
• /diagnostics/aspireextension001/ (edited)
• /diagnostics/overview/ (edited)
• sidebar placement (verified via Prev/Next navigation)

🔴 Critical issues

None.

🟡 Warnings / knowledge gaps

1. Example is not copy-paste-runnable as written. The AppHost.cs sample uses an undefined custom type MyDotnetResource:

   builder.AddResource(new MyDotnetResource("resource"))
       .WithProjectDefaults(options);

   A new user copying this verbatim cannot compile it — MyDotnetResource is never defined, and while the prose correctly says the resource "must carry IProjectMetadata" (and implicitly the IResourceWithEnvironment/IResourceWithEndpoints/IResourceWithArgs constraints), the example gives no hint how to build such a type. The snippet still succeeds at its stated purpose — showing that calling .WithProjectDefaults(options) triggers ASPIREPROJECTS001 — so this is non-blocking.

✅ Passed checks

• New page renders end-to-end: title, Version introduced: 13.5 badge, experimental warning callout, API list, behavior paragraph, Example, suppression (.editorconfig + NoWarn), and See also.
• All in-page links resolve 200: /diagnostics/aspireextension001/, /integrations/custom-integrations/hosting-integrations/, and the #suppress-in-the-editorconfig-file anchor (anchor confirmed present on the overview page).
• overview table shows the new row ASPIREPROJECTS001 · (Experimental) Warning · Project launch defaults types and members … linking to /diagnostics/aspireprojects001/.
• aspireextension001 page shows both new bullets (DebugSupportExtensions.SupportsDebugging/CreateLaunchConfigurationAsync; ExecutableLaunchConfiguration, ProjectLaunchConfiguration, ExecutableLaunchMode, KnownLaunchConfigurationTypes).
• Sidebar orders ASPIREPROJECTS001 between ASPIREPROCESSCOMMAND001 and ASPIREUSERSECRETS001 (Prev/Next nav confirms).
• 0 browser console errors across all exercised pages.

Recommendations

• Optional: add a one-line note that MyDotnetResource is a stand-in custom resource that carries IProjectMetadata — the existing "Custom hosting integrations" See-also link already points readers to how to build one.

---

_{Automated docs-accuracy review · Phase A read microsoft/aspire@release/13.5; Phase B ran the doc-tester skill blind to source.}

[Adam Ratzman (adamint)]

One API is missing from the diagnostic inventory.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.