Compartilhar via

Personalizar imagens de contêiner para depuração

Este artigo descreve como você pode personalizar seus contêineres do Docker ao escolher o tipo de build de contêiner do Dockerfile. Se você estiver usando o tipo de build do SDK do .NET, as opções de personalização serão diferentes e a maioria das informações nesta seção não será aplicável. Em vez disso, confira Colocar em contêiner um aplicativo .NET com dotnet publish.

Este artigo descreve como você pode personalizar seus contêineres ao escolher o tipo de build de contêiner do Dockerfile. Se você estiver usando o tipo de build do SDK do .NET, as opções de personalização serão diferentes e a maioria das informações nesta seção não será aplicável. Em vez disso, confira Colocar em contêiner um aplicativo .NET com dotnet publish.

Pré-requisitos

Pré-requisitos

  • Área de Trabalho do Docker.
  • Visual Studio com o ASP.NET e desenvolvimento na Web, carga de trabalho de desenvolvimento do Azure e/ou carga de trabalho de desenvolvimento da área de trabalho do .NET instalada.

Otimizações do Modo Rápido

Ao compilar na configuração de Depuração, o Visual Studio faz várias otimizações que ajudam no desempenho do processo de compilação para projetos conteinerizados. O processo de build para aplicativos em contêineres não é tão simples quanto simplesmente seguir as etapas descritas no Dockerfile. A construção em um contêiner é mais lenta do que a compilação no computador local. Portanto, quando você compila na configuração de Depuração, o Visual Studio realmente compila seus projetos no computador local e compartilha a pasta de saída para o contêiner usando a montagem de volume. Um build com essa otimização habilitada é chamado de build do modo Fast.

No modo Fast, o Visual Studio chama docker build com um argumento que informa ao Docker para criar apenas o primeiro estágio no Dockerfile (normalmente o estágio base). Você pode alterá-lo definindo a propriedade do MSBuild, DockerfileFastModeStage, descrita nas propriedades do MSBuild das Ferramentas de Contêiner. O Visual Studio manipula o restante do processo sem levar em conta o conteúdo do Dockerfile. Portanto, ao modificar o Dockerfile, como personalizar o ambiente de contêiner ou instalar dependências adicionais, você deverá colocar as modificações no primeiro estágio. Todas as etapas personalizadas colocadas nos estágios build, publishou final do Dockerfile não são executadas.

No modo Rápido, o Visual Studio chama docker build ou podman build com um argumento que instrui o tempo de execução do contêiner a construir apenas o primeiro estágio no Dockerfile (normalmente o estágio base). Você pode alterá-la definindo a propriedade MSBuild, ContainerFastModeStageque substitui o obsoleto DockerfileFastModeStage. Consulte as propriedades do MSBuild de Ferramentas de Contêiner. O Visual Studio manipula o restante do processo sem levar em conta o conteúdo do Dockerfile. Portanto, ao modificar o Dockerfile, como personalizar o ambiente de contêiner ou instalar dependências adicionais, você deverá colocar as modificações no primeiro estágio. Todas as etapas personalizadas colocadas nos estágios build, publishou final do Dockerfile não são executadas.

Normalmente essa otimização de desempenho só ocorre quando você compila na configuração de Depuração. Na configuração de lançamento , o build ocorre no contêiner, conforme especificado no Dockerfile. Você pode habilitar esse comportamento para a configuração de liberação definindo ContainerDevelopmentMode para Rápida no arquivo de projeto.

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
   <ContainerDevelopmentMode>Fast</ContainerDevelopmentMode>
</PropertyGroup>

Se você quiser desabilitar a otimização de desempenho para todas as configurações e compilar como o Dockerfile especifica, defina a propriedade ContainerDevelopmentMode para Regular no arquivo de projeto da seguinte maneira:

<PropertyGroup>
   <ContainerDevelopmentMode>Regular</ContainerDevelopmentMode>
</PropertyGroup>

Para restaurar a otimização de desempenho, remova a propriedade do arquivo de projeto.

Quando você inicia a depuração (F5), um contêiner iniciado anteriormente é reutilizado, se possível. Se você não quiser reutilizar o contêiner anterior, poderá usar os comandos Recompilar ou Limpar no Visual Studio para forçar o Visual Studio a usar um novo contêiner.

O processo de execução do depurador depende do tipo de projeto e do sistema operacional de contêiner:

Cenário Processo do depurador
aplicativos .NET Core (contêineres Linux) O Visual Studio baixa vsdbg e mapeia-o para o contêiner e, em seguida, ele é chamado com seu programa e argumentos (ou seja, dotnet webapp.dll).
aplicativos .NET Core (contêineres do Windows) O Visual Studio usa onecoremsvsmon e mapeia-o para o contêiner, executa-o como o ponto de entrada.
Cenário Processo do depurador
aplicativos .NET Core (contêineres Linux) O Visual Studio baixa vsdbg e mapeia para o contêiner. Em seguida, ele é chamado com o programa e os argumentos (ou seja, dotnet webapp.dll) e depois o depurador anexa ao processo.
aplicativos .NET Core (contêineres do Windows) O Visual Studio usa onecoremsvsmon e mapeia-o para o contêiner, executa-o como o ponto de entrada.
Aplicativos do .NET Framework O Visual Studio usa msvsmon e mapeia-o para o contêiner, executa-o como parte do ponto de entrada em que o Visual Studio pode se conectar a ele e se anexa ao programa. Isso é semelhante a como você normalmente configuraria a depuração remota em outro computador ou máquina virtual.

Para obter informações sobre vsdbg.exe, confira Depuração off-road do .NET Core no Linux e OSX do Visual Studio.

Modificar a imagem de contêiner para depuração e produção

Para modificar a imagem de contêiner para depuração e produção, modifique o primeiro estágio no Dockerfile, geralmente chamado de estágio base. Veja a referência do Dockerfile na documentação do Docker para obter informações sobre os comandos do Dockerfile.

Dica

Se o seu projeto utilizar a propriedade DockerfileFastModeStage MSBuild, você deve selecionar um estágio apropriado para adicionar personalizações que fluam para o estágio final e o DockerfileFastModeStage, se for possível. Consulte as propriedades de build das Ferramentas de Contêiner.

Para modificar a imagem de contêiner para depuração e produção, modifique o primeiro estágio no Dockerfile, geralmente chamado de estágio base. Veja a referência do Dockerfile na documentação do Docker para obter informações sobre os comandos do Dockerfile.

Dica

Se o projeto usar a propriedade MSBuild ContainerFastModeStage (ou o equivalente obsoleto DockerfileFastModeStage), você deve selecionar um estágio apropriado para personalização que leve ao estágio final e ao ContainerFastModeStage, se possível. Consulte as propriedades de build das Ferramentas de Contêiner.

# This stage is used when running from VS in fast mode (Default for Debug configuration)
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
USER $APP_UID
WORKDIR /app
EXPOSE 8080
EXPOSE 8081
# <add your commands here>

# This stage is used to build the service project
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["WebApplication3/WebApplication3.csproj", "WebApplication3/"]
RUN dotnet restore "WebApplication3/WebApplication3.csproj"
COPY . .
WORKDIR "/src/WebApplication3"
RUN dotnet build "WebApplication3.csproj" -c Release -o /app/build

# This stage is used to publish the service project to be copied to the final stage
FROM build AS publish
RUN dotnet publish "WebApplication3.csproj" -c Release -o /app/publish

# This stage is used in production or when running from VS in regular mode (Default when not using the Debug configuration)
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "WebApplication3.dll"]

Modificar a imagem de contêiner somente para depuração

Você pode personalizar seus contêineres de certas maneiras para ajudar na depuração, como instalar algo para fins de diagnóstico, sem afetar as compilações de produção.

Para modificar o contêiner apenas para depuração, crie um estágio e use a propriedade MSBuild DockerfileFastModeStage para indicar ao Visual Studio que utilize seu estágio personalizado ao depurar. Veja a referência do Dockerfile na documentação do Docker para obter informações sobre os comandos do Dockerfile.

Para modificar o contêiner apenas para depuração, crie um estágio e use a propriedade MSBuild ContainerFastModeStage para indicar ao Visual Studio que utilize seu estágio personalizado ao depurar. Veja a referência do Dockerfile na documentação do Docker para obter informações sobre os comandos do Dockerfile.

Nota

As instruções aqui se aplicam ao caso de contêiner único. Você também pode fazer a mesma coisa para vários contêineres com o Docker Compose, mas as técnicas necessárias para o Docker Compose são ligeiramente diferentes. Por exemplo, o estágio é controlado por uma configuração no arquivo dockercompose.debug.yml.

No exemplo a seguir, instalamos o pacote procps-ng, mas somente no modo de depuração. Esse pacote fornece o comando pidof, que o Visual Studio requer (quando visando o .NET 5 ou versões anteriores), mas que não está na imagem Mariner usada aqui. A etapa que usamos para depuração em modo rápido é debug, uma etapa personalizada definida aqui. O estágio de modo rápido não precisa herdar do estágio build ou publish, ele pode herdar diretamente do estágio base, pois o Visual Studio monta um volume que contém tudo o que é necessário para executar o aplicativo, conforme descrito anteriormente neste artigo.

#See https://aka.ms/containerfastmode to understand how Visual Studio uses this Dockerfile to build your images for faster debugging.

# This stage is used when running from VS in fast mode (Default for Debug configuration)
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
USER $APP_UID
WORKDIR /app
EXPOSE 8080
EXPOSE 8081

FROM base AS debug
RUN tdnf install procps-ng -y

# This stage is used to build the service project
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["WebApplication1/WebApplication1.csproj", "WebApplication1/"]
RUN dotnet restore "WebApplication1/WebApplication1.csproj"
COPY . .
WORKDIR "/src/WebApplication1"
RUN dotnet build "WebApplication1.csproj" -c Release -o /app/build

# This stage is used to publish the service project to be copied to the final stage
FROM build AS publish
RUN dotnet publish "WebApplication1.csproj" -c Release -o /app/publish

# This stage is used in production or when running from VS in regular mode (Default when not using the Debug configuration)
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "WebApplication1.dll"]

No arquivo de projeto, adicione essa configuração para instruir o Visual Studio a usar seu estágio personalizado debug durante a depuração.

  <PropertyGroup>
     <!-- other property settings -->
     <DockerfileFastModeStage>debug</DockerfileFastModeStage>
  </PropertyGroup>

  <PropertyGroup>
     <!-- other property settings -->
     <ContainerFastModeStage>debug</ContainerFastModeStage>
  </PropertyGroup>

Personalizar imagens de depuração com a implantação do AOT

Para dar suporte à implantação AOT nativa, o GDB (depurador GNU) é instalado, mas somente na imagem usada durante a depuração, não na imagem final do runtime. O Dockerfile inclui um argumento de build LAUNCHING_FROM_VS que pode ser true ou false. Se true, o estágio aotdebug será usado, que é onde o GDB está instalado. Observe que o Visual Studio dá suporte apenas a contêineres nativos de AOT e GDB para Linux.

# These ARGs allow for swapping out the base used to make the final image when debugging from VS
ARG LAUNCHING_FROM_VS
# This sets the base image for final, but only if LAUNCHING_FROM_VS has been defined
ARG FINAL_BASE_IMAGE=${LAUNCHING_FROM_VS:+aotdebug}

# ... (other stages omitted)

# This stage is used as the base for the final stage when launching from VS to support debugging in regular mode (Default when not using the Debug configuration)
FROM base as aotdebug
USER root
# Install GDB to support native debugging
RUN apt-get update \
    && apt-get install -y --no-install-recommends \
    gdb
USER app

# This stage is used in production or when running from VS in regular mode (Default when not using the Debug configuration)
FROM ${FINAL_BASE_IMAGE:-mcr.microsoft.com/dotnet/runtime-deps:8.0} AS final
WORKDIR /app
EXPOSE 8080
COPY --from=publish /app/publish .
ENTRYPOINT ["./WebApplication1"]

Você pode usar aotstage no Dockerfile para personalizar a imagem usada durante a depuração, sem afetar a imagem final usada quando não iniciado no Visual Studio ou no ambiente de produção. Por exemplo, você pode instalar uma ferramenta que será utilizada apenas durante a depuração.

Conteúdo relacionado

  • Last updated on