From ab108a409c8ba0ed58afbc757e9bf94978c38d1a Mon Sep 17 00:00:00 2001
From: "aspire-repo-bot[bot]"
<268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Date: Fri, 9 Oct 2026 14:04:25 +0000
Subject: [PATCH] Document Dockerfile builder API graduation (Aspire 17.0)
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>
---
.../content/docs/app-host/withdockerfile.mdx | 10 -------
.../docs/deployment/docker-compose.mdx | 8 ------
.../aspiredockerfilebuilder001.mdx | 28 +++++++++++--------
.../src/content/docs/diagnostics/overview.mdx | 2 +-
.../docs/integrations/compute/docker.mdx | 8 ------
.../integrations/frameworks/javascript.mdx | 2 --
.../src/content/docs/whats-new/aspire-17.mdx | 11 ++++++++
7 files changed, 28 insertions(+), 41 deletions(-)
diff --git a/src/frontend/src/content/docs/app-host/withdockerfile.mdx b/src/frontend/src/content/docs/app-host/withdockerfile.mdx
index df30b82577..22023ec091 100644
--- a/src/frontend/src/content/docs/app-host/withdockerfile.mdx
+++ b/src/frontend/src/content/docs/app-host/withdockerfile.mdx
@@ -128,12 +128,6 @@ await pgsql.withPgAdmin(); // Still works because it's still a PostgreSQL resour
Use `AddDockerfileBuilder` or `WithDockerfileBuilder` when you need Aspire to generate a Dockerfile from AppHost code. These APIs are useful when the Dockerfile depends on AppHost configuration, when you want to compose Dockerfile fragments, or when you want to keep multi-stage image build logic near the resource definition.
-
-
`AddDockerfileBuilder` creates a new container resource and configures the generated Dockerfile in one step:
@@ -143,7 +137,6 @@ using Aspire.Hosting.ApplicationModel.Docker;
var builder = DistributedApplication.CreateBuilder(args);
-#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddDockerfileBuilder("frontend", "../frontend", context =>
{
var build = context.Builder.From("node:22-alpine", "build");
@@ -159,7 +152,6 @@ builder.AddDockerfileBuilder("frontend", "../frontend", context =>
return Task.CompletedTask;
}, stage: "runtime");
-#pragma warning restore ASPIREDOCKERFILEBUILDER001
builder.Build().Run();
```
@@ -206,7 +198,6 @@ using Aspire.Hosting.ApplicationModel.Docker;
var builder = DistributedApplication.CreateBuilder(args);
-#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddContainer("frontend", "nginx:alpine")
.WithDockerfileBuilder("../frontend", context =>
{
@@ -216,7 +207,6 @@ builder.AddContainer("frontend", "nginx:alpine")
return Task.CompletedTask;
}, stage: "runtime");
-#pragma warning restore ASPIREDOCKERFILEBUILDER001
builder.Build().Run();
```
diff --git a/src/frontend/src/content/docs/deployment/docker-compose.mdx b/src/frontend/src/content/docs/deployment/docker-compose.mdx
index b55a1a80c5..d0f26f69bf 100644
--- a/src/frontend/src/content/docs/deployment/docker-compose.mdx
+++ b/src/frontend/src/content/docs/deployment/docker-compose.mdx
@@ -219,12 +219,6 @@ When you publish or deploy, Aspire generates the following artifacts in the `asp
Docker Compose deployments can build images from Dockerfiles that are generated by your AppHost. Use `AddDockerfileBuilder` to create a new container resource from a generated Dockerfile, or `WithDockerfileBuilder` to replace the image for an existing container resource with a generated Dockerfile build.
-
-
```csharp title="AppHost.cs"
@@ -234,7 +228,6 @@ var builder = DistributedApplication.CreateBuilder(args);
builder.AddDockerComposeEnvironment("env");
-#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddDockerfileBuilder("frontend", "../frontend", context =>
{
var build = context.Builder.From("node:22-alpine", "build");
@@ -250,7 +243,6 @@ builder.AddDockerfileBuilder("frontend", "../frontend", context =>
return Task.CompletedTask;
}, stage: "runtime");
-#pragma warning restore ASPIREDOCKERFILEBUILDER001
builder.Build().Run();
```
diff --git a/src/frontend/src/content/docs/diagnostics/aspiredockerfilebuilder001.mdx b/src/frontend/src/content/docs/diagnostics/aspiredockerfilebuilder001.mdx
index 84f8a6ee1a..af354f31e0 100644
--- a/src/frontend/src/content/docs/diagnostics/aspiredockerfilebuilder001.mdx
+++ b/src/frontend/src/content/docs/diagnostics/aspiredockerfilebuilder001.mdx
@@ -1,7 +1,7 @@
---
title: Compiler Warning ASPIREDOCKERFILEBUILDER001
-seoTitle: "ASPIREDOCKERFILEBUILDER001: Dockerfile builder types and"
-description: Learn what causes the Aspire compiler warning ASPIREDOCKERFILEBUILDER001 and how to fix it so your AppHost builds cleanly.
+seoTitle: "ASPIREDOCKERFILEBUILDER001: Dockerfile builder APIs"
+description: Learn why Aspire 17.0 removed ASPIREDOCKERFILEBUILDER001 from the Dockerfile builder APIs, which are now generally available.
---
import { Badge, Tabs, TabItem } from '@astrojs/starlight/components';
@@ -13,19 +13,24 @@ import { Badge, Tabs, TabItem } from '@astrojs/starlight/components';
class:list={'mb-1'}
/>
+:::note[Removed in Aspire 17.0]
+The Dockerfile builder APIs — `AddDockerfileBuilder`, `WithDockerfileBuilder`, `DockerfileBuilderCallbackContext`, and related programmatic Dockerfile generation types — have graduated from experimental. Starting with Aspire 17.0, these APIs no longer emit `ASPIREDOCKERFILEBUILDER001`, and you can remove any existing suppressions for them. The API shape, signatures, and behavior are unchanged by this graduation.
+:::
+
> Dockerfile builder types and members are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed.
-This diagnostic warning is reported when using experimental Dockerfile builder APIs in Aspire, specifically the `DockerfileBuilderCallbackContext` class and related programmatic Dockerfile generation functionality.
+Before Aspire 17.0, this diagnostic warning was reported when using experimental Dockerfile builder APIs in Aspire, specifically the `DockerfileBuilderCallbackContext` class and related programmatic Dockerfile generation functionality.
These APIs enable programmatic creation of Dockerfiles at build time, allowing dynamic generation of container images based on application configuration and requirements.
-## Example
+## 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:
```csharp title="AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);
+#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddDockerfileBuilder("my-service", "./service", context =>
{
var stage = context.Builder.From("node:22-alpine", "runtime");
@@ -37,18 +42,18 @@ builder.AddDockerfileBuilder("my-service", "./service", context =>
return Task.CompletedTask;
}, stage: "runtime");
+#pragma warning restore ASPIREDOCKERFILEBUILDER001
```
## AppHost examples
-TypeScript AppHosts can use the same Dockerfile builder callback surface. The warning suppression options below apply to C# compiler diagnostics; TypeScript code doesn't use `#pragma` or `.editorconfig` to suppress `ASPIREDOCKERFILEBUILDER001`.
+With Aspire 17.0 or later, the same code no longer requires a suppression. TypeScript AppHosts can use the same Dockerfile builder callback surface.
```csharp title="AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);
-#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddDockerfileBuilder("my-service", "./service", context =>
{
var stage = context.Builder.From("node:22-alpine", "runtime");
@@ -60,7 +65,6 @@ builder.AddDockerfileBuilder("my-service", "./service", context =>
return Task.CompletedTask;
}, stage: "runtime");
-#pragma warning restore ASPIREDOCKERFILEBUILDER001
```
@@ -95,7 +99,6 @@ The callback can also be applied to an existing container resource with `WithDoc
```csharp title="AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);
-#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddContainer("my-service", "node:22-alpine")
.WithDockerfileBuilder("./service", context =>
{
@@ -108,7 +111,6 @@ builder.AddContainer("my-service", "node:22-alpine")
return Task.CompletedTask;
}, stage: "runtime");
-#pragma warning restore ASPIREDOCKERFILEBUILDER001
```
@@ -170,9 +172,11 @@ The `DockerfileBuilderCallbackContext` provides context information for Dockerfi
In TypeScript AppHosts, callback context values use camelCase names and asynchronous methods. For example, use `await context.builder()` to get the `DockerfileBuilder` instance.
-## To suppress this warning
+## To correct this warning
+
+Upgrade to Aspire 17.0 or later. After upgrading, remove `ASPIREDOCKERFILEBUILDER001` suppressions from _.editorconfig_ files, project `NoWarn` properties, and `#pragma warning` directives.
-Suppress the warning with either of the following methods:
+For earlier versions, suppress the warning with one of the following methods:
- Set the severity of the rule in the _.editorconfig_ file.
diff --git a/src/frontend/src/content/docs/diagnostics/overview.mdx b/src/frontend/src/content/docs/diagnostics/overview.mdx
index 9e0b41b8ed..1897f6ca88 100644
--- a/src/frontend/src/content/docs/diagnostics/overview.mdx
+++ b/src/frontend/src/content/docs/diagnostics/overview.mdx
@@ -47,7 +47,7 @@ The following table lists the possible MSBuild and analyzer warnings and errors
| [ASPIRECONTAINERSHELLEXECUTION001](/diagnostics/aspirecontainershellexecution001/) | (Experimental) Warning | Container shell execution property is for evaluation purposes only and is subject to change or removal in future updates. |
| [ASPIRECOSMOSDB001](/diagnostics/aspirecosmosdb001/) | (Experimental) Error | `RunAsPreviewEmulator` is for evaluation purposes only and is subject to change or removal in future updates. |
| [ASPIRECSHARPAPPS001](/diagnostics/aspirecsharpapps001/) | (Experimental) Error | `AddCSharpApp` is for evaluation purposes only and is subject to change or removal in future updates. |
-| [ASPIREDOCKERFILEBUILDER001](/diagnostics/aspiredockerfilebuilder001/) | (Experimental) Warning | Dockerfile builder types and members are for evaluation purposes only and are subject to change or removal in future updates. |
+| [ASPIREDOCKERFILEBUILDER001](/diagnostics/aspiredockerfilebuilder001/) | (Experimental) Warning | Removed from the Dockerfile builder APIs in Aspire 17.0. These APIs are now generally available and no longer require suppression. |
| [ASPIREDOTNETPROJECT001](/diagnostics/aspiredotnetproject001/) | (Experimental) Warning | Removed from the prerelease `Aspire.Hosting.Dotnet` and `Aspire.Hosting.Blazor` packages in Aspire 13.6. Their APIs remain unstable and may change. |
| [ASPIREDOTNETTOOL001](/diagnostics/aspiredotnettool001/) | (Experimental) Warning | .NET tool resource types and members are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIREEXTENSION001](/diagnostics/aspireextension001/) | (Experimental) Warning | Extension debugging support APIs are for evaluation purposes only and are subject to change or removal in future updates. |
diff --git a/src/frontend/src/content/docs/integrations/compute/docker.mdx b/src/frontend/src/content/docs/integrations/compute/docker.mdx
index 0a4e99d443..26681074c8 100644
--- a/src/frontend/src/content/docs/integrations/compute/docker.mdx
+++ b/src/frontend/src/content/docs/integrations/compute/docker.mdx
@@ -420,12 +420,6 @@ The `configure` callback receives the `DockerComposeServiceResource` and the gen
Use `AddDockerfileBuilder` to create a container resource from a Dockerfile generated by AppHost code. Use `WithDockerfileBuilder` when you want to apply the generated Dockerfile to an existing container resource.
-
-
```csharp title="AppHost.cs"
@@ -433,7 +427,6 @@ using Aspire.Hosting.ApplicationModel.Docker;
var builder = DistributedApplication.CreateBuilder(args);
-#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddDockerfileBuilder("frontend", "../frontend", context =>
{
var build = context.Builder.From("node:22-alpine", "build");
@@ -449,7 +442,6 @@ builder.AddDockerfileBuilder("frontend", "../frontend", context =>
return Task.CompletedTask;
}, stage: "runtime");
-#pragma warning restore ASPIREDOCKERFILEBUILDER001
builder.Build().Run();
```
diff --git a/src/frontend/src/content/docs/integrations/frameworks/javascript.mdx b/src/frontend/src/content/docs/integrations/frameworks/javascript.mdx
index 203bff73c0..a529b93bda 100644
--- a/src/frontend/src/content/docs/integrations/frameworks/javascript.mdx
+++ b/src/frontend/src/content/docs/integrations/frameworks/javascript.mdx
@@ -791,8 +791,6 @@ When publishing to a container, `WithBun` / `withBun` automatically configures a
```csharp title="AppHost.cs"
-#pragma warning disable ASPIREDOCKERFILEBUILDER001
-
var builder = DistributedApplication.CreateBuilder(args);
var app = builder.AddViteApp("app", "./app")
diff --git a/src/frontend/src/content/docs/whats-new/aspire-17.mdx b/src/frontend/src/content/docs/whats-new/aspire-17.mdx
index 4c5cbc2c5e..155ccb98a0 100644
--- a/src/frontend/src/content/docs/whats-new/aspire-17.mdx
+++ b/src/frontend/src/content/docs/whats-new/aspire-17.mdx
@@ -51,6 +51,17 @@ Once Aspire 17.0 is available on the stable channel, use the [`aspire update` co
CLI](/get-started/install-cli/).
+## 🧩 App model and AppHost
+
+#### Dockerfile builder APIs are generally available
+
+The Dockerfile builder APIs — `AddDockerfileBuilder`, `WithDockerfileBuilder`, and the related `DockerfileBuilderCallbackContext` type — have graduated from experimental. You no longer need to suppress [`ASPIREDOCKERFILEBUILDER001`](/diagnostics/aspiredockerfilebuilder001/) to use them in C# or TypeScript AppHosts. The API shape and behavior are unchanged.
+
+
+ See [Generate a Dockerfile programmatically](/app-host/withdockerfile/#generate-a-dockerfile-programmatically)
+ for usage guidance.
+
+
## ⚠️ Breaking changes