在本地 Docker 容器中调试应用

Visual Studio 提供了一种一致方法来开发 Docker 容器，并在本地验证应用程序。 可以在安装了 Docker 的本地 Windows 桌面上运行的 Linux 或 Windows 容器中运行和调试应用，且每次更改代码时都无需重新启动容器。

本文介绍了如何使用 Visual Studio 在本地 Docker 容器中启动应用、进行更改，并刷新浏览器以查看所做的更改。 本文还介绍了如何为容器化的应用设置用于调试的断点。 支持的项目类型包括面向 .NET Framework 和 .NET Core 的 Web 应用、控制台应用和 Azure 函数。 本文中提供的示例是 ASP.NET Core Web 应用类型的项目和控制台应用 (.NET Framework) 类型的项目。

如果你具有支持类型的项目，则 Visual Studio 可以创建 Dockerfile 并将项目配置为在容器中运行。 请参阅 Visual Studio 中的容器工具。

先决条件

若要在本地 Docker 容器中调试应用，必须安装以下工具：

• 安装了 Web 开发工作负荷的 Visual Studio 2022

若要在本地运行 Docker 容器，必须安装本地 Docker 客户端。 你可以使用 Docker Desktop，这需要 Windows 10 或更高版本。

创建 Web 应用

如果你有一个项目，并且已按照概述中的说明添加了 Docker 支持，请跳过此部分。

1. 在 Visual Studio“启动”窗口，选择“创建新项目”。

2. 选择 ASP.NET Core Web 应用，然后选择下一步。

3. 输入新应用程序的名称（或使用默认名称），指定磁盘上的位置，然后选择下一步。

4. 选择要作为目标的 .NET 版本。 如果你不确定具体版本，请选择 LTS（长期支持）版本。

   

5. 通过选择或清除“HTTPS 配置”复选框，选择是否需要 SSL 支持。

6. 选择“启用 Docker”复选框。

7. 使用 Docker OS 下拉列表选择所需的容器类型：Windows 或 Linux。

8. 选择创建以完成过程。

编辑 Razor 页面并刷新

若要在 Razor 页面中快速循环访问所做的更改，可以在容器中启动应用程序。 然后，继续进行更改，就像查看 Internet Information Services (IIS) Express 一样查看这些更改。

1. 请确保 Docker 设置为使用你所使用的容器类型（Linux 或 Windows）。 右键单击任务栏上的 Docker 图标，然后选择相应的切换到 Linux 容器或切换到 Windows 容器。

2. 在 .NET Core 和 .NET 5 及更高版本中，默认模板不支持按此部分所述的方式编辑代码和刷新运行的站点。 为了启用此功能，请添加 NuGet 包 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation 将对扩展方法 AddRazorRuntimeCompilation 的调用添加到 Startup.ConfigureServices 方法中的代码。 只需在调试模式下启用此功能，因此请按 Main 方法进行编码：

   // Add services to the container.
   var mvcBuilder = builder.Services.AddRazorPages();
   #if DEBUG
       if (Env.IsDevelopment())
       {
           mvcBuilder.AddRazorRuntimeCompilation();
       }
   #endif
   

   有关详细信息，请参阅 ASP.NET Core 中的 Razor 文件编译。 确切代码可能会有所不同，具体取决于目标框架和所使用的项目模板。

3. 将解决方案配置设置为调试。 然后，按 Ctrl+F5 以生成 Docker 映像并在本地运行该映像。

   在 Docker 容器中生成映像并运行该映像后，Visual Studio 会在默认浏览器中启动 Web 应用。

4. 转到索引页。 我们将在此页上进行更改。

5. 返回到 Visual Studio 并打开 Index.cshtml。

6. 将以下 HTML 内容添加到文件末尾，然后保存所做的更改。

   <h1>Hello from a Docker container!</h1>
   

7. 在输出窗口中，在 .NET 生成完成并看到下面的行后，切换回浏览器并刷新页面：

   Now listening on: http://*:80
   Application started. Press Ctrl+C to shut down.
   

你的更改已应用！

使用断点进行调试

通常，需要对所做的更改进行进一步检查。 可以使用 Visual Studio 的调试功能来完成此任务。

1. 在 Visual Studio 中，打开 Index.cshtml.cs。

2. 将 OnGet 方法的内容替换为以下代码：

       ViewData["Message"] = "Your application description page from within a container";
   

3. 在代码行的左侧设置一个断点。

4. 要启动调试并命中断点，请按 F5。

5. 切换到 Visual Studio 以查看断点。 检查值。

   

热重载

此外，在 Visual Studio 17.10 及更高版本中，容器中支持热重载；但请注意，在容器中，必须刷新页面才能查看更改。 如果更改是针对 CSS 文件，则必须再次刷新页面才能看到这些更改。 另请注意，作为热重载的一部分，不支持对限定范围的 CSS 文件（.razor.css 文件，请参阅 ASP.NET 核心 Blazor CSS 隔离）的更新。

创建 .NET Framework 控制台应用

本部分介绍如何在本地 Docker 容器中调试 .NET Framework 控制台应用项目，首先演示如何向项目添加 Docker 支持。 必须认识到不同的项目类型具有不同级别的 Docker 支持。 .NET Core（包括 .NET 5 及更高版本）控制台应用项目与 .NET Framework 控制台应用项目甚至有不同级别的 Docker 支持。

创建 .NET Framework 控制台应用项目时，没有启用 Docker 支持的选项。 创建此类项目后，无法向项目显式添加 Docker 支持。 对于 .NET Framework 控制台应用项目，可以添加对容器业务流程的支持。 向 .NET Framework 控制台应用项目添加业务流程支持的副作用是，它会将 Docker 支持添加到项目中。

以下过程演示如何将业务流程支持添加到 .NET Framework 控制台应用项目，随后将 Docker 支持添加到项目，并允许在本地 Docker 容器中调试项目。

1. 创建新的 .NET Framework 控制台应用项目。
2. 在解决方案资源管理器中，右键单击项目节点，然后选择添加>容器业务流程支持。 在出现的对话框中，选择 Docker Compose。 将 Dockerfile 添加到项目中，并添加一个包含相关支持文件的 Docker Compose 项目。

使用断点进行调试

1. 在解决方案资源管理器中，打开 Program.cs。

2. 将 Main 方法的内容替换为以下代码：

       System.Console.WriteLine("Hello, world!");
   

3. 在代码行的左侧设置一个断点。

4. 要启动调试并命中断点，请按 F5。

5. 切换到 Visual Studio 以查看断点，并检查值。

使用令牌代理向 Azure 服务进行身份验证

通过容器使用 Azure 服务时，可以使用 DefaultAzureCredential（已启用 VisualStudioCredential）通过 Microsoft Entra 帐户对 Azure 服务进行身份验证，而无需在容器中执行任何其他配置。 若要启用此功能，请参阅如何配置 Visual Studio 容器工具。 此外，需要按照使用 Azure 验证 Visual Studio 中的说明在 Visual Studio 中设置 Azure 身份验证。 Visual Studio 版本 17.6 及更高版本中提供了对容器中的 VisualStudioCredential 的支持。

Azure Functions

如果要调试集成的 Azure Functions 项目并使用容器中的令牌代理来处理对 Azure 服务的身份验证，则需要将 .NET 运行时复制到容器中，以便令牌代理运行。 如果调试的是独立的 Azure Functions 项目，由于它已有 .NET 运行时，因此无需执行此额外的步骤。

若要确保 .NET 运行时可用于令牌代理，请在 Dockerfile 中添加或修改将 .NET 运行时复制到容器映像中的 debug 层。 对于 Linux 容器，可以将以下代码添加到 Dockerfile：

# This layer is to support debugging, VS's Token Proxy requires the runtime to be installed in the container
FROM mcr.microsoft.com/dotnet/runtime:8.0 AS runtime
FROM base as debug
COPY --from=runtime /usr/share/dotnet /usr/share/dotnet
RUN ln -s /usr/share/dotnet/dotnet /usr/bin/dotnet

此外，在 Visual Studio 项目中，需要进行一些更改，以将其指定为在快速模式下调试时要使用的层。 有关快速模式的说明，请参阅在 Visual Studio 中自定义 Docker 容器。 对于单个容器方案（而不是 Docker Compose），请将 MSBuild 属性 DockerfileFastModeStage 设置为 debug 以使用该层进行调试。 对于 Docker Compose，请按如下所示修改 docker-compose.vs.debug.yml：

# Set the stage to debug to use an image with the .NET runtime in it
services:
  functionappintegrated:
    build:
      target: debug

有关使用 Azure Functions 进行身份验证的代码示例（包括集成和隔离方案），请参阅 VisualStudioCredentialExample。

容器重复使用

使用快速模式（Visual Studio 通常用于调试配置）时，Visual Studio 仅在更改 Dockerfile 时重新生成容器映像和容器本身。 如果不更改 Dockerfile，Visual Studio 将重复使用以前运行的容器。

如果你手动修改了容器，并希望使用干净的容器映像重启，请使用 Visual Studio 中的 Build>Clean 命令，然后按常规操作生成。

如果不使用快速模式（这是发布配置的典型模式），则每次生成项目时，Visual Studio 都会重新生成容器。

可以配置何时使用快速模式；请参阅如何配置 Visual Studio 容器工具。

疑难解答

了解如何对 Visual Studio Docker 开发进行故障排除。

相关内容

有关更多详细信息，请参阅 Visual Studio 如何构建容器化应用。

有关 Visual Studio、Windows 和 Azure 中 Docker 的详细信息

• 详细了解使用 Visual Studio 进行容器开发。
• 要生成和部署 Docker 容器，请参阅 Azure Pipelines 的 Docker 集成。
• 有关 Windows Server 和 Nano Server 文章的索引，请参阅 Windows 容器信息。
• 详细了解 Azure Kubernetes 服务并查看 Azure Kubernetes 服务文档。