Compartir a través de

Personalizar imágenes de contenedor para depurar

En este artículo se describe cómo personalizar los contenedores de Docker al elegir el tipo de compilación de contenedor dockerfile. Si usa el tipo de compilación del SDK de .NET, las opciones de personalización son diferentes y la mayoría de la información de esta sección no es aplicable. En su lugar, consulte Inclusión de una aplicación .NET en un contenedor mediante dotnet publish.

En este artículo se describe cómo personalizar los contenedores al elegir el tipo de compilación de contenedor dockerfile. Si usa el tipo de compilación del SDK de .NET, las opciones de personalización son diferentes y la mayoría de la información de esta sección no es aplicable. En su lugar, consulte Inclusión de una aplicación .NET en un contenedor mediante dotnet publish.

Prerrequisitos

Prerrequisitos

  • Docker Desktop.
  • Visual Studio con las cargas de trabajo desarrollo de ASP.NET y web, desarrollo de Azure y/o desarrollo de escritorio de .NET instaladas.

Optimizaciones del modo rápido

Al compilar en la configuración de depuración , Visual Studio realiza varias optimizaciones que mejoran el rendimiento del proceso de compilación para los proyectos en contenedores. El proceso de compilación para aplicaciones en contenedores no es tan sencillo como simplemente seguir los pasos descritos en dockerfile. La compilación en un contenedor es más lenta que la compilación en el equipo local. Por lo tanto, al compilar en la configuración Debug, Visual Studio compila los proyectos en el equipo local y, a continuación, comparte la carpeta de salida con el contenedor mediante el montaje del volumen. Una compilación con esta optimización habilitada se denomina compilación en modo rápido.

En modo fast, Visual Studio llama a docker build con un argumento que indica a Docker que compile solo la primera fase del Dockerfile (normalmente la fase base). Puede cambiarlo estableciendo la propiedad MSBuild, DockerfileFastModeStage, que se describe en Propiedades de MSBuild de herramientas de contenedor. Visual Studio controla el resto del proceso sin tener en cuenta el contenido del Dockerfile. Por lo tanto, al modificar el Dockerfile, como personalizar el entorno de contenedor o instalar dependencias adicionales, debe colocar las modificaciones en la primera fase. No se ejecutan los pasos personalizados colocados en las fases build, publisho final de Dockerfile.

En el modo Rápido , Visual Studio llama a docker build o podman build con un argumento que indica al entorno de ejecución del contenedor que compile solo la primera fase del Dockerfile (normalmente la base fase). Puede cambiarlo estableciendo la propiedad MSBuild, ContainerFastModeStage, que reemplaza a la obsoleta DockerfileFastModeStage. Consulte Propiedades de MSBuild de las herramientas de contenedores. Visual Studio controla el resto del proceso sin tener en cuenta el contenido del Dockerfile. Por lo tanto, al modificar el Dockerfile, como personalizar el entorno de contenedor o instalar dependencias adicionales, debe colocar las modificaciones en la primera fase. No se ejecutan los pasos personalizados colocados en las fases build, publisho final de Dockerfile.

Normalmente, esta optimización del rendimiento solo se produce cuando compila en la configuración Debug. En la configuración del lanzamiento , la compilación se produce en el contenedor tal como se especifica en el Dockerfile. Puede habilitar este comportamiento para la configuración de liberación estableciendo ContainerDevelopmentMode en Fast en el archivo de proyecto:

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

Si desea deshabilitar la optimización de rendimiento para todas las configuraciones y compilar como especifica Dockerfile, establezca la propiedad ContainerDevelopmentMode en Normal en el archivo de proyecto de la siguiente manera:

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

Para restaurar la optimización del rendimiento, elimínela del archivo del proyecto.

Cuando se inicia la depuración (F5), se vuelve a usar un contenedor iniciado previamente, si es posible. Si no desea reutilizar el contenedor anterior, puede usar los comandos "Reconstruir" o "Clean" en Visual Studio para forzar que Visual Studio use un contenedor nuevo.

El proceso de ejecución del depurador depende del tipo de sistema operativo de proyecto y contenedor:

Escenario Proceso del depurador
aplicaciones de .NET Core (contenedores de Linux) Visual Studio descarga vsdbg y lo asigna al contenedor, después se llama con el programa y los argumentos (es decir, dotnet webapp.dll).
aplicaciones de .NET Core (contenedores de Windows) Visual Studio usa onecoremsvsmon y lo asigna al contenedor, lo ejecuta como punto de entrada.
Escenario Proceso del depurador
aplicaciones de .NET Core (contenedores de Linux) Visual Studio descarga vsdbg y lo asigna al contenedor, después se llama con el programa y los argumentos (es decir, dotnet webapp.dll) y luego el depurador se asocia al proceso.
aplicaciones de .NET Core (contenedores de Windows) Visual Studio usa onecoremsvsmon y lo asigna al contenedor, lo ejecuta como punto de entrada.
Aplicaciones .NET Framework Visual Studio usa msvsmon y lo asigna al contenedor, lo ejecuta como parte del punto de entrada donde Visual Studio puede conectarse a él y se asocia al programa. Es similar a como normalmente se configuraría la depuración remota en otro equipo o máquina virtual.

Para obtener información sobre vsdbg.exe, consulte Depuración fuera de ruta de .NET Core en Linux y OSX desde Visual Studio.

Modificación de la imagen de contenedor para la depuración y producción

Para modificar la imagen de contenedor tanto para la depuración como para la producción, modifique la primera etapa en el dockerfile, normalmente denominada base. Consulte las referencias Dockerfile y en la documentación de Docker para obtener información sobre los comandos de Dockerfile.

Sugerencia

Si el proyecto usa la DockerfileFastModeStage propiedad MSBuild, debe seleccionar una fase adecuada para implementar personalizaciones que se apliquen en la fase final y el DockerfileFastModeStage, si es posible. Consulte Propiedades de construcción de Container Tools.

Para modificar la imagen de contenedor tanto para la depuración como para la producción, modifique la primera etapa en el dockerfile, normalmente denominada base. Consulte las referencias Dockerfile y en la documentación de Docker para obtener información sobre los comandos de Dockerfile.

Sugerencia

Si tu proyecto utiliza la propiedad MSBuild ContainerFastModeStage (o su equivalente obsoleto DockerfileFastModeStage), deberías seleccionar una etapa adecuada para la personalización que se transmita a la etapa final y a ContainerFastModeStage, si es posible. Consulte Propiedades de construcción de 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"]

Modificación de la imagen de contenedor solo para la depuración

Puedes personalizar los contenedores de ciertas formas para ayudar en la depuración, como instalar componentes con fines de diagnóstico, sin afectar a las compilaciones de producción.

Para modificar el contenedor solo para la depuración, cree una etapa y, a continuación, use la propiedad MSBuild DockerfileFastModeStage para indicar a Visual Studio que use su etapa personalizada durante la depuración. Consulte las referencias Dockerfile y en la documentación de Docker para obtener información sobre los comandos de Dockerfile.

Para modificar el contenedor solo para la depuración, cree una etapa y, a continuación, use la propiedad MSBuild ContainerFastModeStage para indicar a Visual Studio que use su etapa personalizada durante la depuración. Consulte las referencias Dockerfile y en la documentación de Docker para obtener información sobre los comandos de Dockerfile.

Nota

Las instrucciones que se indican aquí se aplican al caso de contenedor único. También puede hacer lo mismo para varios contenedores con Docker Compose, pero las técnicas necesarias para Docker Compose son ligeramente diferentes. Por ejemplo, la fase se controla mediante una configuración del archivo dockercompose.debug.yml.

En el ejemplo siguiente, instalamos el paquete procps-ng, pero solo en modo de depuración. Este paquete proporciona el comando pidof, que Visual Studio requiere (cuando el destino es .NET 5 y versiones anteriores), pero no está en la imagen de Mariner que se usa aquí. La fase que usamos para la depuración en modo rápido es debug, una fase personalizada definida aquí. La fase de modo rápido no necesita heredar de la fase de build o publish, puede heredar directamente de la fase de base, ya que Visual Studio monta un volumen que contiene todo lo necesario para ejecutar la aplicación, como se describe anteriormente en este artículo.

#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"]

En el archivo del proyecto, agregue esta configuración para indicar a Visual Studio que use la fase personalizada debug al depurar.

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

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

Personalización de imágenes de depuración con la implementación de AOT

Para admitir la implementación nativa de AOT, se instala el depurador GNU (GDB), pero solo en la imagen usada al depurar, no en la imagen en tiempo de ejecución final. Dockerfile incluye un argumento de compilación LAUNCHING_FROM_VS que puede ser true o false. Si true, se utiliza la etapa aotdebug, que es donde se instala GDB. Tenga en cuenta que Visual Studio solo admite contenedores nativos de AOT y 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"]

Puede usar aotstage en el Dockerfile para personalizar la imagen utilizada en tiempo de depuración, sin afectar a la imagen final utilizada cuando no se inicia desde Visual Studio o en producción. Por ejemplo, podría instalar una herramienta para su uso solo durante la depuración.

Contenido relacionado

  • Last updated on