Personalizzare le immagini del contenitore per il debug

Questo articolo descrive come personalizzare i contenitori quando si sceglie il tipo di compilazione del contenitore Dockerfile. Se si usa il tipo di compilazione .NET SDK, le opzioni di personalizzazione sono diverse e la maggior parte delle informazioni in questa sezione non è applicabile. In alternativa, vedere Containerizzare un'app .NET con dotnet publish.

Prerequisiti

• Docker Desktop o Podman Desktop.
• Visual Studio, o per il supporto di Podman, Visual Studio 2026, con il carico di lavoro sviluppo di ASP.NET e Web, il carico di lavoro Sviluppo di Azure e/o il carico di lavoro sviluppo per desktop .NET installato.

Ottimizzazioni della modalità rapida

Quando si esegue la compilazione nella configurazione debug, Visual Studio offre diverse ottimizzazioni che consentono di ottenere prestazioni del processo di compilazione per i progetti in contenitori. Il processo di compilazione per le app in contenitori non è semplice come seguire semplicemente i passaggi descritti nel Dockerfile. La compilazione in un contenitore è più lenta rispetto alla compilazione nel computer locale. Quindi, quando si esegue la compilazione nella configurazione Debug, Visual Studio compila effettivamente i progetti nel computer locale e quindi condivide la cartella di destinazione nel contenitore usando il montaggio di volumi. Una compilazione con questa ottimizzazione abilitata è chiamata compilazione in modalità veloce.

In modalità Veloce, Visual Studio chiama docker build o podman build con un argomento che indica al runtime del contenitore di compilare solo la prima fase nel Dockerfile (in genere la base fase). È possibile modificarlo impostando la proprietà MSBuild, ContainerFastModeStage, che sostituisce l'oggetto obsoleto DockerfileFastModeStage. Consultare Proprietà MSBuild degli strumenti per contenitori. Visual Studio gestisce il resto del processo senza considerare il contenuto del Dockerfile. Pertanto, quando si modifica il Dockerfile, ad esempio per personalizzare l'ambiente contenitore o installare dipendenze aggiuntive, è necessario inserire le modifiche nella prima fase. Tutti i passaggi personalizzati inseriti nelle fasi build, publisho final del Dockerfile non vengono eseguiti.

Questa ottimizzazione delle prestazioni si verifica normalmente solo quando si esegue la compilazione nella configurazione debug. Nella configurazione versione, la compilazione viene eseguita nel contenitore come specificato nel Dockerfile. È possibile abilitare questo comportamento per la configurazione versione impostando ContainerDevelopmentMode su Veloce nel file di progetto:

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

Se si vuole disabilitare l'ottimizzazione delle prestazioni per tutte le configurazioni e compilare come specificato dal Dockerfile, impostare la proprietà ContainerDevelopmentMode su Regolare nel file di progetto come indicato di seguito:

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

Per ripristinare l'ottimizzazione delle prestazioni, rimuovere la proprietà dal file di progetto.

Quando si avvia il debug (F5), un contenitore avviato in precedenza viene riutilizzato, se possibile. Se non si vuole riutilizzare il contenitore precedente, è possibile usare i comandi Ricompila o Pulisci in Visual Studio per forzare Visual Studio a usare un nuovo contenitore.

Il processo di esecuzione del debugger dipende dal tipo di progetto e dal sistema operativo del contenitore:

Scenario	Processo del debugger
App .NET Core (contenitori Linux)	Visual Studio scarica vsdbg ed esegue il mapping al contenitore, quindi viene chiamato con il programma e gli argomenti , ovvero dotnet webapp.dll.
app .NET Core (contenitori Windows)	Visual Studio usa onecoremsvsmon, lo mappa nel contenitore e lo esegue come punto di ingresso.

Per informazioni su vsdbg.exe, vedere debug Offroad di .NET Core in Linux e OS X da Visual Studio.

Modificare l'immagine del contenitore per il debug e la produzione

Per modificare l'immagine del contenitore sia in fase di debug che di produzione, modificare il primo stadio nel Dockerfile, di solito chiamato base. Fare riferimento alla nella documentazione Docker per informazioni sui comandi Dockerfile.

Suggerimento

Se il progetto usa la ContainerFastModeStage proprietà MSBuild (o l'equivalente obsoleto DockerfileFastModeStage), è consigliabile selezionare una fase appropriata per la personalizzazione che passa alla fase finale e ContainerFastModeStage, se possibile. Vedere Proprietà di compilazione degli Strumenti per container.

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

Modificare l'immagine del contenitore solo per il debug

È possibile personalizzare i contenitori in alcuni modi per facilitare il debug, ad esempio l'installazione di un elemento a scopo diagnostico, senza influire sulle compilazioni di produzione.

Per modificare il contenitore solo per il debug, creare una fase e quindi usare la proprietà MSBuild ContainerFastModeStage per indicare a Visual Studio di usare la fase personalizzata durante il debug. Fare riferimento alla nella documentazione Docker per informazioni sui comandi Dockerfile.

Nota

Le istruzioni riportate di seguito si applicano al caso a contenitore singolo. È anche possibile eseguire la stessa operazione per più contenitori con Docker Compose, ma le tecniche necessarie per Docker Compose sono leggermente diverse. Ad esempio, la fase è controllata da un'impostazione nel file dockercompose.debug.yml.

Nell'esempio seguente viene installato il pacchetto procps-ng, ma solo in modalità di debug. Questo pacchetto fornisce il comando pidof, che Visual Studio richiede (quando è destinato a .NET 5 e versioni precedenti), ma non è nell'immagine Mariner usata qui. La fase usata per il debug in modalità rapida è debug, una fase personalizzata definita qui. La fase in modalità rapida non deve ereditare dalla fase build o publish, può ereditare direttamente dalla fase di base, perché Visual Studio monta un volume contenente tutti gli elementi necessari per eseguire l'app, come descritto in precedenza in questo articolo.

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

Nel file di progetto aggiungere questa impostazione per indicare a Visual Studio di usare la fase personalizzata debug durante il debug.

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

Personalizzare le immagini di debug con la distribuzione AOT

Per supportare la distribuzione AOT nativa, il debugger GNU (GDB) è installato, ma solo sull'immagine usata durante il debug, non sull'immagine di runtime finale. Il Dockerfile include un argomento di compilazione LAUNCHING_FROM_VS che può essere true o false. Se true, viene usata la fase aotdebug, in cui è installato GDB. Si noti che Visual Studio supporta solo AOT nativo e GDB per contenitori 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"]

È possibile usare aotstage nel Dockerfile per personalizzare l'immagine usata in fase di debug, senza influire sull'immagine finale usata quando non si avvia da Visual Studio o nell'ambiente di produzione. Ad esempio, è possibile installare uno strumento per l'uso solo durante il debug.

Contenuto correlato

• Personalizzare i contenitori Docker in Visual Studio
• Compilare un progetto contenitore dalla riga di comando