Compiler Warning ASPIREDOCKERFILEBUILDER001

此内容尚不支持你的语言。

Version introduced: 13.0

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.

These APIs enable programmatic creation of Dockerfiles at build time, allowing dynamic generation of container images based on application configuration and requirements.

Example

The following code generates ASPIREDOCKERFILEBUILDER001 in a C# AppHost:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddDockerfileBuilder("my-service", "./service", context =>
{
    var stage = context.Builder.From("node:22-alpine", "runtime");
    stage.WorkDir("/app")
        .Copy("package*.json", "./")
        .Run("npm ci --omit=dev")
        .Copy(".", ".")
        .Cmd(["node", "index.js"]);

    return Task.CompletedTask;
}, stage: "runtime");

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.

C#
TypeScript

var builder = DistributedApplication.CreateBuilder(args);

#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddDockerfileBuilder("my-service", "./service", context =>
{
    var stage = context.Builder.From("node:22-alpine", "runtime");
    stage.WorkDir("/app")
        .Copy("package*.json", "./")
        .Run("npm ci --omit=dev")
        .Copy(".", ".")
        .Cmd(["node", "index.js"]);

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

import { createBuilder } from './.modules/aspire.js';
import type { DockerfileBuilderCallbackContext } from './.modules/aspire.js';

const builder = await createBuilder();

const configureDockerfile = async (context: DockerfileBuilderCallbackContext) => {
  const dockerfile = await context.builder();
  await dockerfile
    .from("node:22-alpine", { stageName: "runtime" })
    .workDir("/app")
    .copy("package*.json", "./")
    .run("npm ci --omit=dev")
    .copy(".", ".")
    .cmd(["node", "index.js"]);
};

await builder.addDockerfileBuilder("my-service", "./service", configureDockerfile, {
  stage: "runtime",
});

The callback can also be applied to an existing container resource with WithDockerfileBuilder:

C#
TypeScript

var builder = DistributedApplication.CreateBuilder(args);

#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddContainer("my-service", "node:22-alpine")
    .WithDockerfileBuilder("./service", context =>
    {
        var stage = context.Builder.From("node:22-alpine", "runtime");
        stage.WorkDir("/app")
            .Copy("package*.json", "./")
            .Run("npm ci --omit=dev")
            .Copy(".", ".")
            .Cmd(["node", "index.js"]);

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

import { createBuilder } from './.modules/aspire.js';
import type { DockerfileBuilderCallbackContext } from './.modules/aspire.js';

const builder = await createBuilder();

const configureDockerfile = async (context: DockerfileBuilderCallbackContext) => {
  const dockerfile = await context.builder();
  await dockerfile
    .from("node:22-alpine", { stageName: "runtime" })
    .workDir("/app")
    .copy("package*.json", "./")
    .run("npm ci --omit=dev")
    .copy(".", ".")
    .cmd(["node", "index.js"]);
};

await builder
  .addContainer("my-service", "node:22-alpine")
  .withDockerfileBuilder("./service", configureDockerfile, {
    stage: "runtime",
  });

Understanding Dockerfile builder callbacks

The DockerfileBuilderCallbackContext provides context information for Dockerfile build callbacks, enabling dynamic Dockerfile generation. This is useful when:

You need to generate Dockerfiles programmatically based on application state
Different build configurations require different Dockerfile instructions
You want to keep Dockerfile logic close to your application model definition

Key properties

Resource

The resource being built (implements IResource)
Provides access to resource metadata and configuration

Builder

The DockerfileBuilder instance used to construct the Dockerfile
Provides a fluent API for adding Dockerfile instructions

Services

The service provider for dependency injection
Allows access to other services during Dockerfile generation

CancellationToken

Token to observe for cancellation requests
Enables cooperative cancellation of long-running operations

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

Suppress the warning with either of the following methods:

Set the severity of the rule in the .editorconfig file.
.editorconfig
```
[*.{cs,vb}]
dotnet_diagnostic.ASPIREDOCKERFILEBUILDER001.severity = none
```
For more information about editor config files, see Configuration files for code analysis rules.

Add the following PropertyGroup to your project file:

<PropertyGroup>
    <NoWarn>$(NoWarn);ASPIREDOCKERFILEBUILDER001</NoWarn>
</PropertyGroup>

Suppress in code with the #pragma warning disable ASPIREDOCKERFILEBUILDER001 directive:

var builder = DistributedApplication.CreateBuilder(args);

#pragma warning disable ASPIREDOCKERFILEBUILDER001
builder.AddDockerfileBuilder("my-service", "./service", context =>
{
    var stage = context.Builder.From("node:22-alpine", "runtime");
    stage.WorkDir("/app")
        .Copy(".", ".")
        .Cmd(["node", "index.js"]);

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