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:

var builder = DistributedApplication.CreateBuilder(args);
  
builder.AddContainer("my-service", "base-image")
    .WithDockerfile(ctx =>
    {
        // ctx is of type DockerfileBuilderCallbackContext
        ctx.Builder
            .From("node:20-alpine")
            .WorkDir("/app")
            .Copy("package*.json", "./")
            .Run("npm install")
            .Copy(".", ".")
            .Cmd("node", "index.js");
    });

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

To suppress this warning

Suppress the warning with either of the following methods:

Set the severity of the rule in the .editorconfig file.
```
[*.{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.AddContainer("my-service", "base-image")
    .WithDockerfile(ctx =>
    {
        // Dockerfile building logic
    });
#pragma warning restore ASPIREDOCKERFILEBUILDER001