将 Dockerfiles 添加到 .NET 应用模型

2025-04-01

通过使用 .NET.NET Aspire，您可以指定在使用 Dockerfile 或扩展方法启动 AddDockerfile 时要构建的 WithDockerfile。

将 Dockerfile 添加到应用模型

在下面的示例中，AddDockerfile 扩展方法用于通过引用容器生成的上下文路径来指定容器。

var builder = DistributedApplication.CreateBuilder(args);

var container = builder.AddDockerfile(
    "mycontainer", "relative/context/path");

除非上下文路径参数是根路径，否则上下文路径将解释为相对于应用主机项目目录（AppHost *.csproj 文件夹所在的位置）。

默认情况下，使用的Dockerfile的名称是Dockerfile，并且它应该在上下文路径目录中。可以将Dockerfile名称显式指定为绝对路径或相对于上下文路径的相对路径。

在本地运行时或应用主机正在部署时，如果希望修改所使用的特定 Dockerfile，这会非常有用。

var builder = DistributedApplication.CreateBuilder(args);

var container = builder.ExecutionContext.IsRunMode
    ? builder.AddDockerfile(
          "mycontainer", "relative/context/path", "Dockerfile.debug")
    : builder.AddDockerfile(
          "mycontainer", "relative/context/path", "Dockerfile.release");

自定义现有容器资源

使用 AddDockerfile 返回值为 IResourceBuilder<ContainerResource>。 .NET .NET Aspire 包括派生自 ContainerResource的许多自定义资源类型。

使用 WithDockerfile 扩展方法，可以继续使用这些强类型资源类型并自定义使用的基础容器。

var builder = DistributedApplication.CreateBuilder(args);

var pgsql = builder.AddPostgres("pgsql")
                   .WithDockerfile("path/to/context")
                   .WithPgAdmin();

传递生成参数

WithBuildArg 方法可用于将参数传递到容器映像生成中。

var builder = DistributedApplication.CreateBuilder(args);

var container = builder.AddDockerfile("mygoapp", "relative/context/path")
                       .WithBuildArg("GO_VERSION", "1.22");

WithBuildArg 方法上的值参数可以是文本值（boolean、string、int），也可以是参数资源的资源生成器。以下代码将 GO_VERSION 替换为可在部署时指定的参数值。

var builder = DistributedApplication.CreateBuilder(args);

var goVersion = builder.AddParameter("goversion");

var container = builder.AddDockerfile("mygoapp", "relative/context/path")
                       .WithBuildArg("GO_VERSION", goVersion);

生成参数对应于 ARG中的命令。展开前面的例子，Dockerfile 是一个多阶段的过程，它指定要用作参数的特定容器映像版本。

# Stage 1: Build the Go program
ARG GO_VERSION=1.22
FROM golang:${GO_VERSION} AS builder
WORKDIR /build
COPY . .
RUN go build mygoapp.go

# Stage 2: Run the Go program
FROM mcr.microsoft.com/cbl-mariner/base/core:2.0
WORKDIR /app
COPY --from=builder /build/mygoapp .
CMD ["./mygoapp"]

注意

建议对经常更改的值使用环境变量，而不是将值硬编码到容器映像中。这样就无需在需要更改时重新生成容器映像。

传递构建的机密信息

除了生成参数之外，还可以使用 WithBuildSecret 指定生成机密，这些机密可通过 Dockerfile 命令上的 --mount=type=secret 语法选择性地提供给 RUN 中的单个命令。

var builder = DistributedApplication.CreateBuilder(args);

var accessToken = builder.AddParameter("accesstoken", secret: true);

var container = builder.AddDockerfile("myapp", "relative/context/path")
                       .WithBuildSecret("ACCESS_TOKEN", accessToken);

例如，请考虑 RUN 中的 Dockerfile 命令，该命令向特定命令公开指定的机密：

# The helloworld command can read the secret from /run/secrets/ACCESS_TOKEN
RUN --mount=type=secret,id=ACCESS_TOKEN helloworld

谨慎

在构建环境中传递机密时，应谨慎行事。在构建之前，通常会使用令牌从私有存储库或源检索依赖项。请务必确保注入的机密不会被拷贝到最终图像或中间图像中。