Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 0 additions & 10 deletions src/frontend/src/content/docs/app-host/withdockerfile.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Aside type="caution">
The Dockerfile builder APIs are experimental and may change in future
releases. In C# AppHosts, suppress diagnostic
[`ASPIREDOCKERFILEBUILDER001`](/diagnostics/aspiredockerfilebuilder001/) when you choose to use them.
</Aside>

`AddDockerfileBuilder` creates a new container resource and configures the generated Dockerfile in one step:

<Tabs syncKey='aspire-lang'>
Expand All @@ -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");
Expand All @@ -159,7 +152,6 @@ builder.AddDockerfileBuilder("frontend", "../frontend", context =>

return Task.CompletedTask;
}, stage: "runtime");
#pragma warning restore ASPIREDOCKERFILEBUILDER001

builder.Build().Run();
```
Expand Down Expand Up @@ -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 =>
{
Expand All @@ -216,7 +207,6 @@ builder.AddContainer("frontend", "nginx:alpine")

return Task.CompletedTask;
}, stage: "runtime");
#pragma warning restore ASPIREDOCKERFILEBUILDER001

builder.Build().Run();
```
Expand Down
8 changes: 0 additions & 8 deletions src/frontend/src/content/docs/deployment/docker-compose.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Aside type="caution">
The Dockerfile builder APIs are experimental and may change in future
releases. In C# AppHosts, suppress diagnostic
[`ASPIREDOCKERFILEBUILDER001`](/diagnostics/aspiredockerfilebuilder001/) when you choose to use them.
</Aside>

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>
```csharp title="AppHost.cs"
Expand All @@ -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");
Expand All @@ -250,7 +243,6 @@ builder.AddDockerfileBuilder("frontend", "../frontend", context =>

return Task.CompletedTask;
}, stage: "runtime");
#pragma warning restore ASPIREDOCKERFILEBUILDER001

builder.Build().Run();
```
Expand Down
Original file line number Diff line number Diff line change
@@ -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';
Expand All @@ -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");
Expand All @@ -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.

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>
```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");
Expand All @@ -60,7 +65,6 @@ builder.AddDockerfileBuilder("my-service", "./service", context =>

return Task.CompletedTask;
}, stage: "runtime");
#pragma warning restore ASPIREDOCKERFILEBUILDER001
```
</TabItem>
<TabItem id='typescript' label='TypeScript'>
Expand Down Expand Up @@ -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 =>
{
Expand All @@ -108,7 +111,6 @@ builder.AddContainer("my-service", "node:22-alpine")

return Task.CompletedTask;
}, stage: "runtime");
#pragma warning restore ASPIREDOCKERFILEBUILDER001
```
</TabItem>
<TabItem id='typescript' label='TypeScript'>
Expand Down Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion src/frontend/src/content/docs/diagnostics/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -420,20 +420,13 @@ 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.

<Aside type="caution">
The Dockerfile builder APIs are experimental and may change in future
releases. In C# AppHosts, suppress diagnostic
[`ASPIREDOCKERFILEBUILDER001`](/diagnostics/aspiredockerfilebuilder001/) when you choose to use them.
</Aside>

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>
```csharp title="AppHost.cs"
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");
Expand All @@ -449,7 +442,6 @@ builder.AddDockerfileBuilder("frontend", "../frontend", context =>

return Task.CompletedTask;
}, stage: "runtime");
#pragma warning restore ASPIREDOCKERFILEBUILDER001

builder.Build().Run();
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -791,8 +791,6 @@ When publishing to a container, `WithBun` / `withBun` automatically configures a
<TabItem id='csharp' label='C#'>

```csharp title="AppHost.cs"
#pragma warning disable ASPIREDOCKERFILEBUILDER001

var builder = DistributedApplication.CreateBuilder(args);

var app = builder.AddViteApp("app", "./app")
Expand Down
11 changes: 11 additions & 0 deletions src/frontend/src/content/docs/whats-new/aspire-17.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,17 @@ Once Aspire 17.0 is available on the stable channel, use the [`aspire update` co
CLI](/get-started/install-cli/).
</LearnMore>

## 🧩 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.

<LearnMore>
See [Generate a Dockerfile programmatically](/app-host/withdockerfile/#generate-a-dockerfile-programmatically)
for usage guidance.
</LearnMore>

## ⚠️ Breaking changes

<span id="breaking-changes"></span>
Expand Down
Loading