Docker Compose 生成属性

除了用于控制各个 Docker 项目的属性（如容器工具生成属性中所述），还可以通过设置 MSBuild 用于生成解决方案的 Docker Compose 属性来自定义 Visual Studio 生成 Docker Compose 项目的方式。 还可以通过设置 Docker Compose 配置文件中的文件标签来控制 Visual Studio 调试程序运行 Docker Compose 应用的方式。

注释

在 Visual Studio 中使用 Podman Compose 作为 Compose 运行时时，这些生成属性也适用。

如何设置 MSBuild 属性

若要设置属性的值，请编辑项目文件。 对于 Docker Compose 属性，此项目文件是扩展名为 .dcproj 扩展名的文件，除非在下一部分的表中另有说明。 例如，假设要指定在开始调试时启动浏览器。 可以在项目文件中设置属性DockerLaunchAction.dcproj，如下所示。

<PropertyGroup>
   <DockerLaunchAction>LaunchBrowser</DockerLaunchAction>
</PropertyGroup>

可以向现有 PropertyGroup 元素添加属性设置，如果没有，则新建一个 PropertyGroup 元素。

Docker Compose MSBuild 属性

下表显示了可用于 Docker Compose 项目的 MSBuild 属性（.dcproj 文件）。

属性名称	描述
AdditionalComposeFilePaths	以分号分隔的列表指定要发送给 docker-compose.exe 供所有命令使用的其他撰写文件。 允许 Docker Compose 项目文件 （dcproj） 中的相对路径。
DependencyAwareStart	启用支持 Docker Compose 属性 depends_on 和 healthcheck的应用的不同方式，这些属性控制服务启动顺序和运行状况检查。 需要 Visual Studio 17.13 或更高版本。 默认值：False
DockerComposeBaseFilePath	指定 Docker Compose 文件文件名的第一部分，而不指定 .yml 扩展名。 例如： 1. DockerComposeBaseFilePath = null/undefined：使用基本文件路径 docker-compose，文件将命名 为docker-compose.yml 和 docker-compose.override.yml。 2. DockerComposeBaseFilePath = mydockercompose：文件将命名为 mydockercompose.yml 和 mydockercompose.override.yml。 3. DockerComposeBaseFilePath = ..\mydockercompose：文件将向上提升一级。 默认值：30docker-compose
DockerComposeBuildArguments	指定要传递给 docker-compose build 命令的额外参数。 例如，--parallel --pull。
DockerComposeDownArguments	指定要传递给 docker-compose down 命令的额外参数。 例如，--timeout 500。
DockerComposeEnvFilePath	传递给 docker compose 命令 --env-file的 .env 文件的相对路径。 请参阅 “使用env_file属性”。 默认值：空
DockerComposeProjectName	如果指定，则重写 Docker Compose 项目的项目名称。 默认值：“dockercompose”+ 自动生成的哈希
DockerComposeProjectsToIgnore	指定要在调试期间由 Docker Compose 工具忽略的项目。 此属性可用于任何项目。 可通过以下两种方式之一来指定文件路径： 1. 相对于 dcproj。 例如，<DockerComposeProjectsToIgnore> path\to\AngularProject1.csproj </DockerComposeProjectsToIgnore>。 2. 绝对路径。 注意：路径应由分隔符 分隔。
DockerComposeUpArguments	指定要传递给 docker-compose up 命令的额外参数。 例如，--timeout 500。
DockerDevelopmentMode	控制是否在容器中生成用户项目。 可取值为“Fast”或“Regular”，用于控制在 Dockerfile 中生成哪些阶段。 调试配置默认为“Fast”模式，否则为“Regular”模式。 默认值：快速
DockerLaunchAction	指定要针对 F5 或 Ctrl+F5 执行的启动操作。 允许的值为 None、LaunchBrowser 和 LaunchWCFTestClient。 默认值： 无
DockerLaunchBrowser	指示是否启动浏览器。 如果指定了 DockerLaunchAction，则忽略。 默认值：False
DockerServiceName	如果指定了 DockerLaunchAction 或 DockerLaunchBrowser，则 DockerServiceName 指定启动文件中引用的服务 docker-compose 。
DockerServiceUrl	启动浏览器时将使用的 URL。 有效的替换令牌为“{ServiceIPAddress}”、“{ServicePort}”和“{Scheme}”。 例如：{Scheme}://{ServiceIPAddress}:{ServicePort}
DockerTargetOS	生成 Docker 映像时使用的目标 OS。

此外，DockerComposeProjectPath 或 .csproj 项目文件中的属性 .vbproj 指定 Docker Compose 项目 （.dcproj） 文件的相对路径。 发布服务项目以查找存储在 docker-compose.yml 文件中的关联映像生成设置时设置此属性。

例

如果通过设置为docker-compose相对路径更改文件的位置DockerComposeBaseFilePath，则还需要确保生成上下文已更改，以便引用解决方案文件夹。 例如，如果 docker-compose 文件是名为 DockerComposeFiles的文件夹，则 Docker Compose 文件应将生成上下文设置为“..”或“.”。/..“，具体取决于它相对于解决方案文件夹的位置。

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" Sdk="Microsoft.Docker.Sdk">
  <PropertyGroup Label="Globals">
    <ProjectVersion>2.1</ProjectVersion>
    <DockerTargetOS>Windows</DockerTargetOS>
    <ProjectGuid>154022c1-8014-4e9d-bd78-6ff46670ffa4</ProjectGuid>
    <DockerLaunchAction>LaunchBrowser</DockerLaunchAction>
    <DockerServiceUrl>{Scheme}://{ServiceIPAddress}{ServicePort}</DockerServiceUrl>
    <DockerServiceName>webapplication1</DockerServiceName>
    <DockerComposeBaseFilePath>DockerComposeFiles\mydockercompose</DockerComposeBaseFilePath>
    <AdditionalComposeFilePaths>AdditionalComposeFiles\myadditionalcompose.yml</AdditionalComposeFilePaths>
  </PropertyGroup>
  <ItemGroup>
    <None Include="DockerComposeFiles\mydockercompose.override.yml">
      <DependentUpon>DockerComposeFiles\mydockercompose.yml</DependentUpon>
    </None>
    <None Include="DockerComposeFiles\mydockercompose.yml" />
    <None Include=".dockerignore" />
  </ItemGroup>
</Project>

mydockercompose.yml 文件应如下所示，其中生成上下文设置为解决方案文件夹的相对路径（在本例中为 ） 。

version: '3.4'

services:
  webapplication1:
    image: ${DOCKER_REGISTRY-}webapplication1
    build:
      context: ..
      dockerfile: WebApplication1\Dockerfile

注释

DockerComposeBuildArguments、DockerComposeDownArguments 和 DockerComposeUpArguments 是 Visual Studio 2019 版本 16.3 中的新增内容。

替代 Visual Studio 的 Docker Compose 配置

通常 docker-compose.override.yml 用于替代 docker-compose.yml 中的某些设置 。 此外，Visual Studio 使用特定于在 Visual Studio 中运行应用程序的设置docker-compose.vs.debug.g.yml（适用于快速模式）和docker-compose.vs.release.g.yml（常规模式）文件生成替代文件。 可以替代这些 Visual Studio 设置，具体方法是将名为 docker-compose.vs.debug.yml（对于“Fast”模式）或 docker-compose.vs.release.yml（对于“Regular”模式）的文件放置在与 docker-compose.yml 文件相同的目录中。 右键单击 Docker Compose 项目并选择文件资源管理器中的“打开文件夹”，然后使用>”将文件添加到 Docker Compose 项目。

小贴士

若要找出任意 Visual Studio 设置的默认值，请查看 docker-compose.vs.debug.g.yml 或 docker-compose.vs.release.g.yml 的中间输出目录（例如，obj/Docker）。 这些文件由 Visual Studio 生成，不应进行修改。

Docker Compose 文件标签

在 docker-compose.vs.debug.yml 或 docker-compose.vs.release.yml 中，可以定义特定于替代的标签，如下所示：

services:
  webapplication1:
    labels:
      com.microsoft.visualstudio.debuggee.workingdirectory: "C:\\my_app_folder"

如前面的示例所示，用双引号将这些值括起来，并在路径中使用反斜杠作为转义字符。

标签名称	描述
com.microsoft.visualstudio.debuggee.program	启动调试时启动的程序。 对于 .Net Core 应用，此设置通常为“dotnet” 。
com.microsoft.visualstudio.debuggee.arguments	开始调试时传递给程序的参数。 对于 .NET Core 应用，这些参数通常是 NuGet 包的其他搜索路径，后面是指向项目输出程序集的路径。
com.microsoft.visualstudio.debuggee.workingdirectory	开始调试时用作起始目录的目录。 对于 Linux 容器，此设置通常为 /app；对于 Windows 容器，此设置通常为 C:\app 。
com.microsoft.visualstudio.debuggee.killprogram	此命令用于停止在容器中运行的调试对象程序（如有必要）。
com.microsoft.visualstudio.debuggee.noattach.program	在独立进程中运行的 Azure Functions 项目中使用 Start（Ctrl+F5）时启动的程序。 通常 F5 和 CtrlF5 都使用相同的程序，但如果独立进程中的任何项目类型（如 Azure Functions）都需要不同于 F5 的程序，则会使用此程序。
com.microsoft.visualstudio.debuggee.noattach.arguments	在独立进程中运行的 Azure Functions 项目中使用 F5）时传递给程序的参数。
com.microsoft.visual-studio.project-name	项目的名称，如果项目与 Dockerfile 不在同一文件夹中，则有助于 Visual Studio 查找项目。
com.microsoft.visualstudio.launch-url.path-query	打开端口选项卡中的链接时容器窗口使用的路径和查询。 需要 Visual Studio 17.13 或更高版本。

自定义 Docker 生成过程

通过在 target 属性中使用 build 设置，可以声明在 Dockerfile 中生成哪个阶段。 此替代只能在 docker-compose.vs.debug.yml 或 docker-compose.vs.release.yml 中使用。

services:
  webapplication1:
    build:
      target: customStage
    labels:
      ...

自定义应用启动过程

在启动应用之前，可以通过使用 entrypoint 设置并使其依赖于 DockerDevelopmentMode，运行命令或自定义脚本。 例如，如果只需要在“Fast”模式下通过运行 update-ca-certificates 来创建证书，而不需要在“Regular”模式下这样做，则可以只在 docker-compose.vs.debug.yml 中添加以下代码：

services:
  webapplication1:
    entrypoint: "sh -c 'update-ca-certificates && tail -f /dev/null'"
    labels:
      ...

有关详细信息，请参阅 容器入口点

后续步骤

有关 MSBuild 属性的一般信息，请参阅 MSBuild 属性。

另请参阅

容器工具生成属性

容器工具启动设置

管理 Visual Studio 中 Docker Compose 的启动配置文件

MSBuild 保留属性和已知属性