Menyesuaikan gambar kontainer untuk debugging

Artikel ini menjelaskan cara mengkustomisasi kontainer saat Anda memilih jenis build kontainer Dockerfile. Jika Anda menggunakan jenis build .NET SDK, opsi kustomisasi berbeda, dan sebagian besar informasi di bagian ini tidak berlaku. Sebagai gantinya, lihat Containerize aplikasi .NET dengan dotnet publish.

Prasyarat

• Docker Desktop atau Podman Desktop.
• Visual Studio, atau untuk dukungan Podman, Visual Studio 2026, dengan ASP.NET dan pengembangan web, beban kerja pengembangan Azure , dan/atau beban kerja pengembangan desktop .NET terinstal.

Pengoptimalan Mode Cepat

Saat Anda membuat konfigurasi Debug, ada beberapa pengoptimalan yang dilakukan Visual Studio yang membantu performa proses build untuk proyek kontainer. Proses build untuk aplikasi dalam kontainer tidak sesederhana hanya mengikuti langkah-langkah sebagaimana diuraikan dalam Dockerfile. Membangun dalam kontainer lebih lambat daripada membangun di komputer lokal. Jadi, saat Anda membuat dalam konfigurasi Debug, Visual Studio sebenarnya membuat proyek Anda pada mesin lokal, lalu membagikan folder output ke kontainer menggunakan pemasangan volume. Build dengan pengoptimalan ini diaktifkan disebut build mode Fast.

Dalam mode Cepat, Visual Studio memanggil docker build atau podman build dengan argumen yang memberi tahu runtime kontainer untuk membuat hanya tahap pertama dalam Dockerfile (biasanya tahap base). Anda dapat mengubahnya dengan mengatur properti MSBuild, ContainerFastModeStage, yang menggantikan usang DockerfileFastModeStage. Lihat Properti MSBuild dari Alat-Alat Kontainer. Visual Studio menangani sisa proses tanpa memperhatikan konten Dockerfile. Jadi, ketika Anda memodifikasi Dockerfile Anda, seperti untuk menyesuaikan lingkungan kontainer atau menginstal dependensi tambahan, Anda harus menempatkan modifikasi Anda pada tahap pertama. Setiap langkah kustom yang ditempatkan di dalam tahap build, publish, atau final dari Dockerfile tidak dijalankan.

Pengoptimalan performa ini biasanya hanya terjadi saat Anda membuat konfigurasi Debug. Dalam konfigurasi Rilis , build terjadi dalam kontainer sesuai dengan yang ditentukan dalam Dockerfile. Anda dapat mengaktifkan perilaku ini untuk konfigurasi Rilis dengan mengatur ContainerDevelopmentMode ke Fast dalam file proyek:

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

Jika Anda ingin menonaktifkan pengoptimalan performa untuk semua konfigurasi, dan membangun seperti yang ditentukan Dockerfile, maka atur properti ContainerDevelopmentMode ke Reguler dalam file proyek sebagai berikut:

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

Untuk memulihkan pengoptimalan performa, hapus properti dari file proyek.

Saat Anda mulai men-debug (F5), kontainer yang dimulai sebelumnya digunakan kembali, jika memungkinkan. Jika Anda tidak ingin menggunakan kembali kontainer sebelumnya, Anda dapat menggunakan perintah Bangun ulang atau Bersihkan di Visual Studio untuk memaksa Visual Studio menggunakan kontainer baru.

Proses menjalankan debugger tergantung pada jenis proyek dan sistem operasi kontainer:

Skenario	Proses debugger
aplikasi .NET Core (kontainer Linux)	Visual Studio mengunduh vsdbg dan memetakannya ke kontainer, lalu akan dipanggil dengan program dan argumen Anda (yaitu, dotnet webapp.dll).
aplikasi .NET Core (kontainer Windows)	Visual Studio menggunakan onecoremsvsmon dan memetakannya ke kontainer, menjalankannya sebagai titik masuk.

Untuk informasi tentang vsdbg.exe, lihat debugging Offroad .NET Core di Linux dan OS X dari Visual Studio.

Memodifikasi citra kontainer untuk debug dan produksi

Untuk memodifikasi image kontainer untuk debugging dan produksi, ubah tahap pertama di Dockerfile, biasanya disebut sebagai tahap base. Lihat referensi Dockerfile dalam dokumentasi Docker untuk informasi tentang perintah Dockerfile.

Petunjuk / Saran

Jika proyek Anda menggunakan properti MSBuild ContainerFastModeStage (atau DockerfileFastModeStage setara usang), Anda harus memilih tahap yang sesuai untuk menyesuaikan proses yang terhubung ke tahap akhir dan memasukkan ContainerFastModeStage, jika memungkinkan. Lihat Properti pembangunan Kontainer Alat.

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

Ubah image container hanya untuk debugging

Anda dapat menyesuaikan kontainer dengan berbagai cara untuk membantu penelusuran kesalahan, seperti menginstal sesuatu untuk tujuan diagnostik, tanpa memengaruhi build produksi.

Untuk memodifikasi container hanya untuk debugging, buat tahap dan kemudian gunakan properti MSBuild ContainerFastModeStage untuk memberitahu Visual Studio agar menggunakan tahap yang telah Anda sesuaikan saat debugging. Lihat referensi Dockerfile dalam dokumentasi Docker untuk informasi tentang perintah Dockerfile.

Nota

Instruksi di sini berlaku untuk kasus kontainer tunggal. Anda juga dapat melakukan hal yang sama untuk beberapa kontainer dengan Docker Compose, tetapi teknik yang diperlukan untuk Docker Compose sedikit berbeda. Misalnya, tahap dikontrol oleh pengaturan dalam file dockercompose.debug.yml.

Dalam contoh berikut, kami menginstal paket procps-ng, tetapi hanya dalam mode debug. Paket ini menyediakan perintah pidof, yang diperlukan oleh Visual Studio (saat menargetkan .NET 5 dan versi sebelumnya) tetapi tidak ada dalam image Mariner yang digunakan di sini. Tahapan yang kami gunakan untuk debugging modus cepat adalah debug, sebuah tahap kustom yang ditentukan di sini. Tahap mode cepat tidak perlu mewarisi dari tahap build atau publish. Tahap ini bisa langsung mewarisi dari tahap base, karena Visual Studio memasang volume yang berisi semua yang diperlukan untuk menjalankan aplikasi, seperti telah dijelaskan sebelumnya dalam artikel ini.

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

Dalam file proyek, tambahkan pengaturan ini untuk memberi tahu Visual Studio agar menggunakan tahap kustom Anda debug saat debugging.

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

Sesuaikan citra debugging dengan penyebaran AOT

Untuk mendukung penyebaran AOT asli, debugger GNU (GDB) diinstal, tetapi hanya pada citra yang digunakan saat debugging, bukan citra runtime akhir. Dockerfile menyertakan argumen build LAUNCHING_FROM_VS yang dapat menjadi true atau false. Jika true, tahap aotdebug digunakan, yaitu tempat GDB diinstal. Perhatikan bahwa Visual Studio hanya mendukung AOT dan GDB asli untuk kontainer 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"]

Anda dapat menggunakan aotstage di Dockerfile untuk menyesuaikan gambar yang digunakan pada waktu debug, tanpa memengaruhi gambar akhir yang digunakan saat tidak meluncurkan dari Visual Studio, atau dalam produksi. Misalnya, Anda dapat menginstal alat yang hanya digunakan selama penelusuran kesalahan.

Konten terkait

• Menyesuaikan kontainer Docker di Visual Studio
• Membangun proyek kontainer dari baris perintah