Debuggen von Apps in einem lokalen Docker-Container

Visual Studio bietet eine zuverlässige Möglichkeit der Entwicklung in Docker-Containern und der lokalen Überprüfung Ihrer Anwendung. Sie können Ihre Anwendungen in Linux- oder Windows-Containern ausführen und debuggen, die auf Ihrem lokalen Windows-Desktop mit installiertem Docker ausgeführt werden, und Sie müssen den Container nicht jedes Mal neu starten, wenn Sie eine Codeänderung vornehmen.

In diesem Artikel erfahren Sie, wie Sie das Feature zum Bearbeiten und Aktualisieren nutzen, um eine App in einem lokalen Docker-Container zu starten, die erforderlichen Änderungen vorzunehmen und den Browser dann zu aktualisieren, um die Änderungen anzuzeigen. Außerdem erfahren Sie in diesem Artikel, wie Sie Haltepunkte für das Debuggen für die sich in Containern befindenden Apps festlegen. Unterstützte Projekttypen umfassen Web-App, Konsolen-App und Azure Function-Ziel .NET Framework und .NET Core. Die in diesem Artikel dargestellten Beispiele sind ein Projekt vom Typ ASP.NET Core Web App und ein Projekt vom Typ Konsolen-App (.NET Framework).

Wenn Sie bereits über ein Projekt eines unterstützten Typs verfügen, kann Visual Studio eine Dockerfile erstellen und Ihr Projekt für die Ausführung in einem Container konfigurieren. Weitere Informationen finden Sie unter Containertools in Visual Studio.

Voraussetzungen

Zum Debuggen von Apps in einem lokalen Docker-Container müssen die folgenden Tools installiert werden:

• Visual Studio 2022 mit installierter Workload für Webentwicklung

Sie benötigen einen lokalen Docker-Client, um Docker-Container lokal ausführen zu können. Sie können Docker Desktopverwenden. Hierfür ist Windows 10 oder höher erforderlich.

Erstellen einer Web-App

Wenn Sie über ein Projekt verfügen und die Docker-Unterstützung wie in der Übersicht beschrieben hinzugefügt haben, überspringen Sie diesen Abschnitt.

1. Klicken Sie im Startfenster von Visual Studio auf Neues Projekt erstellen.

2. Wählen Sie ASP.NET Core-Web-App und anschließend Weiter aus.

3. Geben Sie einen Namen für Ihre neue Anwendung ein (oder verwenden Sie den Standardnamen), geben Sie den Speicherort auf dem Datenträger an, und klicken Sie auf Weiter.

4. Wählen Sie die .NET-Version aus, die Sie als Ziel verwenden möchten. Wenn Sie sich nicht sicher sind, wählen Sie die LTS-Veröffentlichung (Long-Term Support) aus.

   

5. Aktivieren oder deaktivieren Sie das Kontrollkästchen neben Für HTTPS konfigurieren, um festzulegen, ob SSL unterstützt werden soll.

6. Aktivieren Sie das Kontrollkästchen Docker aktivieren.

7. Verwenden Sie die Docker OS-Dropdownliste, um den gewünschten Containertyp auszuwählen: Windows oder Linux.

8. Wählen Sie Erstellen aus, um den Vorgang abzuschließen.

Bearbeiten Ihrer Razor-Seiten und Aktualisieren

Sie können die Anwendung in einem Container starten, um Änderungen in Ihren Razor-Seiten schnell zu durchlaufen. Nehmen Sie dann weiterhin Änderungen vor, und betrachten Sie sie wie Internet Information Services (IIS) Express.

1. Stellen Sie sicher, dass Docker so eingerichtet ist, dass der von Ihnen verwendete Containertyp (Linux oder Windows) verwendet wird. Klicken Sie mit der rechten Maustaste auf das Docker-Symbol auf der Taskleiste und wählen Sie die Option zum Wechseln zu Linux-Containern oder Wechseln zu Windows-Containern aus.

2. Die in diesem Abschnitt beschriebene Bearbeitung von Code und Aktualisierung der ausgeführten Website ist in den Standardvorlagen von .NET Core und .NET 5 und höher nicht aktiviert. Fügen Sie zur Aktivierung das NuGet-Paket Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation hinzu. Fügen Sie der Erweiterungsmethode AddRazorRuntimeCompilation einen Aufruf in der Startup.ConfigureServices-Methode zum Code hinzu. Sie benötigen die Aktivierung nur im Debugmodus, verwenden Sie also folgenden Code in der Main-Methode:

   // Add services to the container.
   var mvcBuilder = builder.Services.AddRazorPages();
   #if DEBUG
       if (Env.IsDevelopment())
       {
           mvcBuilder.AddRazorRuntimeCompilation();
       }
   #endif
   

   Weitere Informationen finden Sie unter Kompilieren einer Razor-Datei in ASP.NET Core. Der genaue Code kann je nach Zielframework und verwendeter Projektvorlage variieren.

3. Legen Sie die Lösungskonfiguration auf Debuggen fest. Drücken Sie dann STRG+F5, um Ihr Docker-Image zu erstellen und lokal auszuführen.

   Wenn das Containerimage erstellt wurde und in einem Docker-Container ausgeführt wird, startet Visual Studio die Web-App in Ihrem Standardbrowser.

4. Wechseln Sie zur Index-Seite. Wir nehmen auf dieser Seite Änderungen vor.

5. Kehren Sie zu Visual Studio zurück, und öffnen Sie Index.cshtml.

6. Fügen Sie den folgenden HTML-Inhalt am Ende der Datei hinzu, und speichern Sie dann die Änderungen.

   <h1>Hello from a Docker container!</h1>
   

7. Sobald der .NET-Build fertig gestellt ist, sehen Sie im Ausgabefenster diese Zeilen. Kehren Sie zu Ihrem Browser zurück, und aktualisieren Sie die Seite:

   Now listening on: http://*:80
   Application started. Press Ctrl+C to shut down.
   

Ihre Änderungen wurden übernommen!

Debuggen mit Haltepunkten

Häufig ist für Änderungen eine weitere Überprüfung erforderlich. Sie können die Debugfunktionen von Visual Studio für diese Aufgabe verwenden.

1. Öffnen Sie Index.cshtml.cs in Visual Studio.

2. Ersetzen Sie den Inhalt der OnGet-Methode durch folgenden Code:

       ViewData["Message"] = "Your application description page from within a container";
   

3. Legen Sie links neben die Codezeile einen Haltepunkt fest.

4. Drücken Sie F5, um das Debuggen zu starten und den Haltepunkt zu erreichen.

5. Wechseln Sie zu Visual Studio, um den Haltepunkt anzuzeigen. Überprüfen Sie die Werte.

   

Erneut laden im laufenden Betrieb

Außerdem wird in Visual Studio 17.10 und höher Hot Reload in Containern unterstützt. Allerdings sollten Sie beachten, dass Sie die Seite in einem Container aktualisieren müssen, damit Änderungen angezeigt werden. Wenn die Änderung an einer CSS-Datei vorgenommen wird, müssen Sie die Seite erneut aktualisieren, um diese Änderungen anzuzeigen. Beachten Sie auch, dass Aktualisierungen bereichsbezogener CSS-Dateien (.razor.css-Dateien siehe CSS-Isolierung in ASP.NET Core Blazor) nicht als Teil des Hot Reload unterstützt werden.

Erstellen einer .NET Framework-Konsolen-App

In diesem Abschnitt wird erläutert, wie Sie ein .NET Framework-Konsolen-App-Projekt in einem lokalen Docker-Container debuggen, indem Sie zunächst zeigen, wie Docker-Unterstützung zum Projekt hinzugefügt wird. Es ist wichtig zu erkennen, dass verschiedene Projekttypen unterschiedliche Ebenen der Docker-Unterstützung haben. Es gibt sogar verschiedene Ebenen der Docker-Unterstützung für .NET Core (einschließlich .NET 5 und höher) Konsolen-App-Projekte im Vergleich zu .NET Framework-Konsolen-App-Projekten.

Wenn ein .NET Framework-Konsolen-App-Projekt erstellt wird, gibt es keine Option zum Aktivieren der Docker-Unterstützung. Nach dem Erstellen eines solchen Projekts gibt es keine Möglichkeit, dem Projekt die Docker-Unterstützung explizit hinzuzufügen. Für ein .NET Framework-Konsolen-App-Projekt ist es möglich, Unterstützung für die Container-Orchestrierung hinzuzufügen. Ein Nebeneffekt des Hinzufügens der Orchestrierungsunterstützung zum .NET Framework-Konsolen-App-Projekt besteht darin, dass es Docker-Unterstützung zum Projekt hinzufügt,

Im folgenden Verfahren wird veranschaulicht, wie Sie einem .NET Framework Konsolen-App-Projekt Orchestrierungsunterstützung hinzufügen, das anschließend Docker-Unterstützung zum Projekt hinzufügt und es dem Projekt ermöglicht, in einem lokalen Docker-Container debuggen zu können.

1. Erstellen Sie ein neues .NET Framework-Konsolen-App-Projekt.
2. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektknoten, und wählen Sie dann Hinzufügen>Unterstützung für Containerorchestrierung aus. Klicken Sie im angezeigten Dialogfeld auf Docker Compose. Dem Projekt wird eine Dockerfile-Datei hinzugefügt, und es wird ein Docker Compose-Projekt mit zugeordneten Unterstützungsdateien hinzugefügt.

Debuggen mit Haltepunkten

1. Öffnen Sie Program.cs im Projektmappen-Explorer.

2. Ersetzen Sie den Inhalt der Main-Methode durch folgenden Code:

       System.Console.WriteLine("Hello, world!");
   

3. Legen Sie links neben die Codezeile einen Haltepunkt fest.

4. Drücken Sie F5, um das Debuggen bis zum Breakpoint zu starten.

5. Kehren Sie zu Visual Studio zurück, um den Haltepunkt anzuzeigen und die Werte zu überprüfen.

Authentifizieren bei Azure-Diensten mithilfe des Tokenproxys

Wenn Sie Azure-Dienste aus einem Container verwenden, können Sie DefaultAzureCredential (mit aktiviertem VisualStudioCredential) verwenden, um sich mit Azure-Diensten mit Ihrem Microsoft Entra-Konto ohne zusätzliche Konfiguration im Container zu authentifizieren. Informationen zum Aktivieren finden Sie unter Konfigurieren von Visual Studio-Containertools. Außerdem müssen Sie die Azure-Authentifizierung in Visual Studio einrichten, indem Sie die Anweisungen unter Authentifizieren von Visual Studio mit Azure befolgen. Die Unterstützung für VisualStudioCredential in einem Container ist in Visual Studio ab Version 17.6 verfügbar.

Azure-Funktionen

Wenn Sie ein integriertes Azure Functions-Projekt debuggen und den Tokenproxy im Container verwenden, um die Authentifizierung für Azure-Dienste zu verarbeiten, müssen Sie die .NET-Laufzeit in den Container kopieren, damit der Tokenproxy ausgeführt wird. Wenn Sie ein isoliertes Azure Functions-Projekt debuggen, verfügt es bereits über die .NET-Runtime, daher ist dieser zusätzliche Schritt nicht erforderlich.

Um sicherzustellen, dass die .NET-Laufzeit für den Tokenproxy verfügbar ist, fügen Sie die debug-Ebene in der Dockerfile-Datei hinzu, welche die .NET-Runtime in das Containerimage kopiert. Für Linux-Container können Sie Dockerfile-Datei den folgenden Code hinzufügen:

# This layer is to support debugging, VS's Token Proxy requires the runtime to be installed in the container
FROM mcr.microsoft.com/dotnet/runtime:8.0 AS runtime
FROM base as debug
COPY --from=runtime /usr/share/dotnet /usr/share/dotnet
RUN ln -s /usr/share/dotnet/dotnet /usr/bin/dotnet

Außerdem müssen Sie im Visual Studio-Projekt einige Änderungen vornehmen, um dies als Ebene anzugeben, die beim Debuggen im Schnellmodus verwendet werden soll. Eine Erläuterung des Fast Mode finden Sie unter Anpassen von Docker-Containern in Visual Studio. Legen Sie für einzelne Containerszenarien (nicht Docker Compose) die MSBuild-Eigenschaft DockerfileFastModeStage auf debug fest, um diese Ebene für das Debuggen zu verwenden. Ändern Sie für Docker Compose docker-compose.vs.debug.yml folgendermaßen:

# Set the stage to debug to use an image with the .NET runtime in it
services:
  functionappintegrated:
    build:
      target: debug

Ein Codebeispiel für die Authentifizierung mit Azure-Funktionen, einschließlich integrierter und isolierter Szenarien, finden Sie unter VisualStudioCredentialExample.

Wiederverwendung von Containern

Wenn Sie den Fast Mode verwenden, den Visual Studio normalerweise für die Debugkonfiguration verwendet, erstellt Visual Studio nur Ihre Containerimages und den Container selbst neu, wenn Sie die Dockerfile-Datei ändern. Wenn Sie die Dockerfile-Datei nicht ändern, verwendet Visual Studio den Container von einem früheren Testlauf wieder.

Wenn Sie den Container manuell geändert haben und ihn mit einem sauberen Containerimage neu starten möchten, verwenden Sie den Befehl Erstellen>Bereinigen in Visual Studio, und führen Sie dann wie gewohnt den Erstellungsprozess aus.

Wenn Sie den Fast Mode nicht verwenden, der für die Releasekonfiguration typisch ist, erstellt Visual Studio den Container jedes Mal neu, wenn das Projekt erstellt wird.

Sie können konfigurieren, wann der Fast Mode verwendet wird; Informationen dazu finden Sie unter Konfigurieren von Visual Studio-Containertools.

Problembehandlung

Informationen zur Problembehandlung bei der Docker-Entwicklung in Visual Studio.

Zugehöriger Inhalt

Weitere Informationen finden Sie unter Wie Visual Studio Containeranwendungen erstellt.

Weitere Informationen zu Docker mit Visual Studio, Windows und Azure

• Nähere Informationen zur Containerentwicklung mit Visual Studio.
• Informationen zum Erstellen und Bereitstellen eines Docker-Containers finden Sie unter Docker-Integration für Azure Pipelines.
• Einen Index von Windows Server- und Nano Server-Artikeln finden Sie unter Informationen zu Windows-Containern.
• Erfahren Sie mehr über den Azure Kubernetes Service und überprüfen Sie die Dokumentation zum Azure Kubernetes Service.