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