Skip to content

[docs] Document Dockerfile builder API graduation (Aspire 17.0) - #1857

Closed
aspire-repo-bot[bot] wants to merge 1 commit into
release/17.0from
docs/pr-20823-37940287966-1-1f31debc739e1840
Closed

aspire-repo-bot[bot] wants to merge 1 commit into
release/17.0from
docs/pr-20823-37940287966-1-1f31debc739e1840

Conversation

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Documents changes from microsoft/aspire#20823

@mitchdenny

Target branch

Targeting release/17.0 based on the source PR milestone 17.0 (exact match on microsoft/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 34 ASPIREDOCKERFILEBUILDER001 source markers were removed from Aspire.Hosting, along with 44 obsolete #pragma warning disable/restore ASPIREDOCKERFILEBUILDER001 pairs 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 AddDockerfileBuilder C# call working without a diagnostic suppression, which is a direct, user-visible change: anyone following the old docs would still add unnecessary #pragma warning disable directives or .editorconfig/NoWarn suppressions.

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 ASPIREDOCKERFILEBUILDER001 lines wrapping AddDockerfileBuilder/WithDockerfileBuilder code samples (C# and TypeScript tabs where applicable).
  • diagnostics/overview.mdx: Updated the ASPIREDOCKERFILEBUILDER001 table row to reflect that it was removed in Aspire 17.0 (matching the existing pattern used for ASPIREDOTNETPROJECT001).
  • diagnostics/aspiredockerfilebuilder001.mdx: Rewrote the page with a "Removed in Aspire 17.0" note (following the aspireacadomains001.mdx / aspiredotnetproject001.mdx precedent), 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 updated withdockerfile.mdx guide.

Files modified

  • src/frontend/src/content/docs/app-host/withdockerfile.mdx
  • src/frontend/src/content/docs/deployment/docker-compose.mdx
  • src/frontend/src/content/docs/diagnostics/aspiredockerfilebuilder001.mdx
  • src/frontend/src/content/docs/diagnostics/overview.mdx
  • src/frontend/src/content/docs/integrations/compute/docker.mdx
  • src/frontend/src/content/docs/integrations/frameworks/javascript.mdx
  • src/frontend/src/content/docs/whats-new/aspire-17.mdx

No new pages were created; all existing pages were updated in place.

Generated by PR Documentation Check for #20823 · copilot · auto · 149.7 AIC · ⌖ 17 AIC · ⊞ 20.4K · ◷

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>
@aspire-repo-bot aspire-repo-bot Bot added the docs-from-code Copilot initiated issue from dotnet/aspire repo label Oct 9, 2026
@aspire-repo-bot

Copy link
Copy Markdown
Contributor Author

Frontend HTML artifact ready

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

VS Code: Open PR #1857 artifacts

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

Copy link
Copy Markdown
Member

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: microsoft/aspire main via merged source PR microsoft/aspire#20823 (docs PR targets release/17.0; no matching branch checked).
PR status: merge conflicts with base — needs a rebase onto release/17.0. Draft, opened 2026-10-09 (not stale).

Phase A — claims

  • ✅ verified: [Experimental("ASPIREDOCKERFILEBUILDER001")] removed from DockerfileBuilder, ContainerFilesExtensions and related APIs; pragmas removed.
  • ✅ verified: AddDockerfileBuilder/WithDockerfileBuilder exist in ContainerResourceBuilderExtensions.cs.
  • ❌ blocker: unresolved merge conflicts; content could not be re-reviewed against the current base.

Phase B — doc-tester

Not run; rendering of the changed pages is not browser-checked.

🤖 Posted by aspire.dev - squad (AI Agent)

@IEvangelist
David Pine (IEvangelist) marked this pull request as ready for review November 13, 2026 14:58
Copilot AI balanced review requested due to automatic review settings November 13, 2026 14:58

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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
@maddymontaquila

Copy link
Copy Markdown
Contributor

Superseded by #2176, which consolidates the 17.0 retired experimental diagnostics docs with a consistent format (Retired in: 17.0 badge and note, overview table, and a single What's new section).

Maddy Montaquila (maddymontaquila) added a commit that referenced this pull request Nov 16, 2026
## 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs-from-code Copilot initiated issue from dotnet/aspire repo

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants