Personalizar imagens de contêiner para depuração

Este artigo descreve como você pode personalizar seus contêineres ao escolher o tipo de compilação de contêiner do Dockerfile. Se você estiver usando o tipo de compilação 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, consulte Containerize uma aplicação .NET com dotnet publish.

Pré-requisitos

• Docker Desktop ou Podman Desktop.
• Visual Studio ou, para suporte ao Podman, Visual Studio 2026, com a carga de trabalho de desenvolvimento ASP.NET e web, carga de trabalho de desenvolvimento do Azure e/ou carga de trabalho de desenvolvimento de desktop .NET instalada.

Otimizações do Modo Rápido

Quando se compila na configuração de Depuração , há várias otimizações que o Visual Studio realiza e que ajudam no desempenho do processo de compilação para projetos em contentores. O processo de compilação para aplicativos em contêineres não é tão simples quanto simplesmente seguir as etapas descritas no Dockerfile. Construir em um contêiner é mais lento do que construir na máquina local. Portanto, quando se cria a configuração de de depuração do, o Visual Studio realmente compila os seus projetos na máquina local e, em seguida, partilha a pasta de saída com o contêiner utilizando montagem por volume. Uma compilação com essa otimização habilitada é chamada de compilação do modo Fast.

No modo rápido, o Visual Studio chama docker build ou podman build com um argumento que indica ao runtime do contentor para compilar apenas a primeira fase no Dockerfile (normalmente a fase base). Você pode alterar isso definindo a propriedade MSBuild, ContainerFastModeStage, que substitui o obsoleto DockerfileFastModeStage. Consulte Ferramentas de contêiner Propriedades do MSBuild. Visual Studio lida com o resto do processo sem considerar o conteúdo do Dockerfile. Portanto, quando você modifica seu Dockerfile, como para personalizar o ambiente de contêiner ou instalar dependências adicionais, você deve colocar suas modificações no primeiro estágio. Todas as etapas personalizadas colocadas nos estágios build, publishou final do Dockerfile não são executadas.

Esta otimização de desempenho geralmente só ocorre quando se cria na configuração Debug. Na configuração do Release, a compilação ocorre no contêiner conforme especificado no Dockerfile. Você pode habilitar esse comportamento para a configuração Release definindo ContainerDevelopmentMode para Fast 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 conforme especificado pelo Dockerfile, defina a propriedade ContainerDevelopmentMode como 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 inicias a depuração (F5), um contentor iniciado anteriormente é reutilizado, se possível. Se você não quiser reutilizar o contêiner anterior, você pode usar Rebuild ou comandos Clean no Visual Studio para forçar o Visual Studio a usar um contêiner novo.

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

Cenário	Processo do depurador
aplicativos .NET Core (contêineres Linux)	Visual Studio baixa vsdbg e mapeia para o contêiner, em seguida, ele é chamado com seu programa e argumentos (ou seja, dotnet webapp.dll).
aplicativos .NET Core (contêineres do Windows)	Visual Studio utiliza onecoremsvsmon, mapeia-o para o contentor e executa-o como o ponto de entrada.

Para obter informações sobre vsdbg.exe, consulte depuração offroad do .NET Core no Linux e OS X do Visual Studio.

Modificar imagem de container para debug e produção

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

Sugestão

Se o seu projeto usa a propriedade MSBuild ContainerFastModeStage (ou o obsoleto equivalente DockerfileFastModeStage), deve selecionar um estágio apropriado para personalização que flua para o estágio final e ContainerFastModeStage, se possível. Veja Propriedades de build do Container Tools.

# 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 imagem de contêiner somente para depuração

Você pode personalizar seus contêineres de determinadas 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 contentor somente para depuração, crie um estágio e use a propriedade MSBuild ContainerFastModeStage para indicar ao Visual Studio para usar seu estágio personalizado quando fizer a depuração. Consulte a referência Dockerfile na documentação do Docker para obter informações sobre os comandos do Dockerfile.

Observação

As instruções aqui se aplicam à caixa 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, no modo de depuração, apenas o pacote procps-ng. Este pacote fornece o comando pidof, que o Visual Studio requer (quando direcionado para o .NET 5 e versões anteriores), mas não está incluído na imagem Mariner usada aqui. A plataforma que usamos para depuração em modo rápido é debug, uma plataforma 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, porque 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 ficheiro de projeto, adicione essa configuração para dizer ao Visual Studio para usar seu estágio personalizado debug ao depurar.

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

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

Para suportar a implementação AOT nativa, o depurador GNU (GDB) é instalado, mas apenas na imagem usada durante a depuração, não na imagem de tempo de execução final. O Dockerfile inclui um argumento de compilação LAUNCHING_FROM_VS que pode ser true ou false. Se true, o estágio aotdebug é usado, que é onde o GDB está instalado. Observe que o Visual Studio oferece suporte apenas a AOT nativo e GDB para contêineres 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 no momento da depuração, sem afetar a imagem final usada quando não é iniciada a partir do Visual Studio ou em produção. Por exemplo, pode-se instalar uma ferramenta para uso apenas durante a depuração.

Conteúdo relacionado

• Personalizar contêineres do Docker no Visual Studio
• Criar um projeto de contêiner a partir da linha de comando