Repository navigation
[docs] Document Dockerfile builder API graduation (Aspire 17.0) - #1857
aspire-repo-bot[bot] wants to merge 1 commit into
Conversation
Removes ASPIREDOCKERFILEBUILDER001 suppression guidance from app-host/withdockerfile.mdx, integrations/compute/docker.mdx, integrations/frameworks/javascript.mdx, and deployment/docker-compose.mdx now that AddDockerfileBuilder/WithDockerfileBuilder are generally available. Updates the diagnostics overview table and diagnostics/aspiredockerfilebuilder001.mdx with a graduation note, and adds a What's new in Aspire 17.0 entry. Documents microsoft/aspire#20823 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
docs-pr-reviewer report — [partial — phase A: all extracted claims evaluated; phase B: not run (docs site was not served in this automated run)]Recommendation: changes needed Source used: Phase A — claims
Phase B — doc-testerNot run; rendering of the changed pages is not browser-checked. 🤖 Posted by aspire.dev - squad (AI Agent) |
There was a problem hiding this comment.
🟡 Changes recommended
The documentation incorrectly describes a suppressed example as generating a diagnostic and skips a heading level, reducing clarity and disrupting screen-reader navigation.
2 open issues
What changed in this PR
Updates Aspire documentation for the Dockerfile builder APIs becoming generally available in 17.0, with no API shape or behavior changes.
Changes:
- Removes experimental callouts and obsolete diagnostic suppressions from usage guides.
- Updates diagnostic guidance to distinguish pre-17.0 suppression from current usage.
- Adds a release-note entry linking to the Dockerfile generation guide.
| File | Description |
|---|---|
src/frontend/src/content/docs/whats-new/aspire-17.mdx |
Announces Dockerfile builder API graduation. |
src/frontend/src/content/docs/integrations/frameworks/javascript.mdx |
Removes suppression from the JavaScript integration example. |
src/frontend/src/content/docs/integrations/compute/docker.mdx |
Removes experimental guidance and sample suppressions. |
src/frontend/src/content/docs/diagnostics/overview.mdx |
Marks the diagnostic as removed in 17.0. |
src/frontend/src/content/docs/diagnostics/aspiredockerfilebuilder001.mdx |
Explains graduation, historical suppression, and upgrade guidance. |
src/frontend/src/content/docs/deployment/docker-compose.mdx |
Removes experimental guidance and sample suppressions. |
src/frontend/src/content/docs/app-host/withdockerfile.mdx |
Updates Dockerfile builder examples for stable usage. |
Review effort: Balanced
| ## Example before Aspire 17.0 | ||
|
|
||
| The following code generates `ASPIREDOCKERFILEBUILDER001` in a C# AppHost: | ||
| Before Aspire 17.0, the following code generated `ASPIREDOCKERFILEBUILDER001` in a C# AppHost: |
|
|
||
| ## 🧩 App model and AppHost | ||
|
|
||
| #### Dockerfile builder APIs are generally available |
|
Superseded by #2176, which consolidates the 17.0 retired experimental diagnostics docs with a consistent format ( |
## Summary <!-- Describe what this pull request changes and why. --> Consolidates the retired experimental diagnostic documentation for Aspire 17.0, superseding the individual PRs against `release/17.0`. - Marks 14 diagnostic pages as retired in 17.0, retaining their historical content and guidance for removing suppressions. - Updates the diagnostics overview and the 17.0 release notes, including `ASPIREDENO001` and `ASPIRECONNECTIONSTRINGS001`, which don't have dedicated pages. - Explains that `ASPIRECOMPUTE002` was only partially graduated: endpoint-mapping contracts are stable, while persistent-volume APIs remain experimental. - Removes retired suppressions and experimental cautions from affected guides, while retaining the experimental image-building guidance for `ASPIREPIPELINES003`. - Notes that `ASPIRECSHARPAPPS001` was retired when `AddCSharpApp` became obsolete. The broader migration and ProjectResource v2 guidance is separate in #2180. The retired diagnostic list was checked against `[Experimental("…")]` usages in `microsoft/aspire` between `v13.6.5` and `release/17.0`. Supersedes #1846, #1847, #1851, #1852, #1853, #1854, #1856, #1857, #2127, #2167, #2168, #2169, #2170, #2171. ## Third-party links and affiliations <!-- List any third-party links added or changed by this pull request and disclose any material affiliation with the linked organizations, such as employment, sponsorship, or ownership. Write "None" if this pull request doesn't add or change third-party links. --> None ## Validation <!-- List the checks you ran or explain why validation isn't needed. --> - `git diff --check origin/release/17.0 -- src/frontend/src/content/docs` — passed. - Frontend validation CI — passed; frontend build CI is pending. - Local Astro build and tests were not run; Bun and frontend dependencies were unavailable. --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Documents changes from microsoft/aspire#20823
@mitchdennyTarget branch
Targeting
release/17.0based on the source PR milestone17.0(exact match onmicrosoft/aspire.dev).Why this PR is needed
microsoft/aspire#20823 graduates the Dockerfile builder API family (
AddDockerfileBuilder,WithDockerfileBuilder,DockerfileBuilderCallbackContext, and related types) from experimental. All 34ASPIREDOCKERFILEBUILDER001source markers were removed fromAspire.Hosting, along with 44 obsolete#pragma warning disable/restore ASPIREDOCKERFILEBUILDER001pairs across production and test code. This is an attribute-only graduation — no API shape or behavior changes.The source PR's "User-facing usage" section shows the existing
AddDockerfileBuilderC# call working without a diagnostic suppression, which is a direct, user-visible change: anyone following the old docs would still add unnecessary#pragma warning disabledirectives or.editorconfig/NoWarnsuppressions.Summary of documentation changes
app-host/withdockerfile.mdx,integrations/compute/docker.mdx,integrations/frameworks/javascript.mdx,deployment/docker-compose.mdx: Removed the<Aside type="caution">callouts warning that the Dockerfile builder APIs are experimental, and removed all#pragma warning disable/restore ASPIREDOCKERFILEBUILDER001lines wrappingAddDockerfileBuilder/WithDockerfileBuildercode samples (C# and TypeScript tabs where applicable).diagnostics/overview.mdx: Updated theASPIREDOCKERFILEBUILDER001table row to reflect that it was removed in Aspire 17.0 (matching the existing pattern used forASPIREDOTNETPROJECT001).diagnostics/aspiredockerfilebuilder001.mdx: Rewrote the page with a "Removed in Aspire 17.0" note (following theaspireacadomains001.mdx/aspiredotnetproject001.mdxprecedent), reframing the existing examples as "before Aspire 17.0" (with pragma) vs. current (without pragma), and updating the "To correct this warning" section to point at upgrading to 17.0.whats-new/aspire-17.mdx: Added a new "🧩 App model and AppHost" section with a "Dockerfile builder APIs are generally available" entry, linking back to the updatedwithdockerfile.mdxguide.Files modified
src/frontend/src/content/docs/app-host/withdockerfile.mdxsrc/frontend/src/content/docs/deployment/docker-compose.mdxsrc/frontend/src/content/docs/diagnostics/aspiredockerfilebuilder001.mdxsrc/frontend/src/content/docs/diagnostics/overview.mdxsrc/frontend/src/content/docs/integrations/compute/docker.mdxsrc/frontend/src/content/docs/integrations/frameworks/javascript.mdxsrc/frontend/src/content/docs/whats-new/aspire-17.mdxNo new pages were created; all existing pages were updated in place.