Debuggen von ASP.NET Core-Apps

In diesem Artikel wird beschrieben, wie Sie Blazor-Apps debuggen, einschließlich des Debuggens von Blazor WebAssembly-Apps mit Browserentwicklertools oder einer integrierten Entwicklungsumgebung (IDE).

Voraussetzungen

In diesem Abschnitt werden die Voraussetzungen für das Debuggen erläutert.

Browservoraussetzungen

Stellen Sie sicher, dass Firewalls oder Proxys die Kommunikation mit dem Debugproxy (NodeJS-Prozess) nicht blockieren. Weitere Informationen finden Sie im Abschnitt Firewallkonfiguration.

IDE-Voraussetzungen

Die neueste Version von Visual Studio oder Visual Studio Code ist erforderlich.

Voraussetzungen für Visual Studio Code

Visual Studio Code erfordert das C# Dev Kit für Visual Studio Code (Erste Schritte mit C# in VS Code). Filtern Sie im Visual Studio Code Extensions-Marketplace die Erweiterungsliste mit „c# dev kit“, um die Erweiterung zu finden:

Durch die automatische Installation des C# Dev Kit werden die folgenden zusätzlichen Erweiterungen installiert:

• .NET-Installationstool
• C#
• IntelliCode für C# Dev Kit

Wenn Warnungen oder Fehler auftreten, können Sie ein Problem öffnen (microsoft/vscode-dotnettools GitHub-Repository) öffnen, welches das Problem beschreibt.

App-Konfigurationsvoraussetzungen

Die Anleitung in diesem Unterabschnitt gilt für das clientseitige Debuggen.

Öffnen Sie die Properties/launchSettings.json-Datei des Startprojekts. Bestätigen Sie das Vorhandensein der folgenden inspectUri-Eigenschaft in jedem Startprofil des Knotens profiles der Datei. Wenn die folgende Eigenschaft nicht vorhanden ist, fügen Sie sie zu jedem Profil hinzu:

"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"

Die inspectUri-Eigenschaft:

• ermöglicht der IDE, zu ermitteln, ob es sich bei einer App um eine Blazor-App handelt.
• Weist die Skript-Debugging-Infrastruktur an, über den Debugging-Proxy von Blazor eine Verbindung zum Browser herzustellen.

Die Platzhalterwerte für das WebSocket-Protokoll (wsProtocol), den Host (url.hostname), den Port (url.port) und den Inspektor-URI im gestarteten Browser (browserInspectUri) werden vom Framework bereitgestellt.

Pakete

Standalone Blazor WebAssembly: Microsoft.AspNetCore.Components.WebAssembly.DevServer: Entwicklungsserver für die Verwendung beim Erstellen von Blazor WebAssembly-Apps. Ruft intern UseWebAssemblyDebugging auf, um Middleware zum Debuggen von Blazor WebAssembly Apps in den Chromium-Entwicklertools hinzuzufügen.

Debuggen einer Blazor WebAssembly-App in einer IDE

<DebuggerSupport>true</DebuggerSupport>
<CopyOutputSymbolsToPublishDirectory>true</CopyOutputSymbolsToPublishDirectory>

Anfügen an eine vorhandene Visual Studio Code-Debugsitzung

Um an eine laufende Blazor-App anzufügen, öffnen Sie die .vscode/launch.json-Datei, und ersetzen Sie den {URL}-Platzhalter durch die URL, unter der die App ausgeführt wird:

{
  "name": "Attach and Debug",
  "type": "blazorwasm",
  "request": "attach",
  "url": "{URL}"
}

Startoptionen für Visual Studio Code

Die Startkonfigurationsoptionen in der folgenden Tabelle werden für den blazorwasm-Debugtyp (.vscode/launch.json) unterstützt.

Debuggen Sie Blazor WebAssembly mit Google Chrome oder Microsoft Edge

Die Anleitung in diesem Abschnitt gilt für das Debuggen von Blazor WebAssembly-Apps in:

• Google Chrome, das unter Windows oder macOS ausgeführt wird.
• Microsoft Edgeläuft unter Windows.

1. Führen Sie die App in einer Befehlsshell mit dotnet watch (oder dotnet run) aus.

2. Starten Sie einen Browser, und navigieren Sie zur URL der App.

3. Starten Sie das Remotedebugging, indem Sie Folgendes drücken:

   • Shift+Alt+d unter Windows.
   • UMSCHALT+⌘+D unter macOS.

   Der Browser muss mit aktiviertem Remotedebuggen ausgeführt werden, was nicht das Standardverhalten ist. Wenn das Remotedebuggen deaktiviert ist, wird eine Seite mit der Meldung Debugfähige Browserregisterkarte nicht gefunden gerendert, die Anweisungen zum Starten des Browsers mit geöffnetem Debuggingport enthält. Folgen Sie den Anweisungen für Ihren Browser.

   Nachdem Sie die Anweisungen zum Aktivieren des Remotedebuggens ausgeführt haben, wird die App in einem neuen Browserfenster geöffnet. Starten Sie das Remotedebuggen, indem Sie die HotKey-Kombination im neuen Browserfenster drücken:

   • UMSCHALT+ALT+D unter Windows.
   • UMSCHALT+⌘+D unter macOS.

   Eine neue Registerkarte in den Entwicklertools des Browsers wird geöffnet und zeigt ein ausgegrautes Bild der App an.

   Hinweis

   Wenn Sie die Anweisungen zum Öffnen einer neuen Browserregisterkarte mit aktiviertem Remotedebuggen befolgt haben, können Sie das ursprüngliche Browserfenster schließen und das zweite Fenster geöffnet lassen, wobei die erste Registerkarte die App ausführt und die zweite Registerkarte den Debugger.

4. Nach einem kurzen Moment zeigt die Registerkarte Quellen eine Liste der .NET-Assemblys und -Seiten der App an.

5. Öffnen Sie den Knoten file://. In Komponentencode-Dateien (.razor) und C#-Codedateien (.cs) werden von Ihnen gesetzte Haltepunkte erreicht, wenn der Code auf der Browserregisterkarte der App ausgeführt wird (der ersten Registerkarte, die nach dem Start des Remotedebuggings geöffnet wurde). Nachdem ein Breakpoint erreicht wurde, durchlaufen Sie den Code in Einzelschritten (F10) oder setzen Sie die Codeausführung normal in der Registerkarte „Debuggen“ fort (F8).

Für das Chromium-basierte Browserdebugging stellt Blazor einen Debugproxy bereit, der das Chrome DevTools-Protokoll implementiert und das Protokoll mit .NET-spezifischen Informationen erweitert. Wenn die Tastenkombination zum Debuggen gedrückt wird, verweist Blazor die Chrome DevTools auf den Proxy. Der Proxy stellt eine Verbindung mit dem Browserfenster her, das Sie debuggen möchten (daher die Notwendigkeit, das Remotedebuggen zu aktivieren).

Bei nicht behandelten Ausnahmen anhalten

Der Debugger hält bei unbehandelten Ausnahmen nicht an, da Blazor Ausnahmen abfängt, die im Entwicklerscode nicht behandelt werden.

Bei nicht behandelten Ausnahmen anhalten:

• Öffnen Sie die Ausnahmeeinstellungen des Debuggers (Debuggen>Fenster>Ausnahmeeinstellungen) in Visual Studio.
• Legen Sie die folgenden Einstellungen für JavaScript-Ausnahmen fest:
  • Alle Ausnahmen
  • Nicht abgefangene Ausnahmen

Browserquellzuordnungen

Browserquellzuordnungen ermöglichen es dem Browser, kompilierte Dateien zu ihren ursprünglichen Quelldateien zurück zuzuordnen und sie werden häufig für clientseitiges Debuggen verwendet. Blazor C# wird derzeit jedoch nicht direkt javaScript/Wasm zugeordnet. Stattdessen übernimmt Blazor die IL-Interpretation innerhalb des Browsers, sodass Quellzuordnungen nicht relevant sind.

Firewallkonfiguration

Wenn eine Firewall die Kommunikation mit dem Debugproxy blockiert, erstellen Sie eine Firewallausnahmeregel, die die Kommunikation zwischen Browser und NodeJS-Prozess zulässt.

Eine Anleitung zur Konfiguration der Windows-Firewall finden Sie unter Erstellen einer Regel für eingehende Programme oder Dienste. Weitere Informationen finden Sie unter Windows Defender-Firewall mit erweiterter Sicherheit und zugehörigen Artikeln in der Dokumentation zur Windows-Firewall.

Problembehandlung

Wenn Sie auf Fehler stoßen, könnten die folgenden Tipps helfen:

• Haltepunkte entfernen:
  • Google Chrome: Öffnen Sie auf der Registerkarte Debugger die Entwicklertools in Ihrem Browser. Führen Sie in der Konsole localStorage.clear() aus, um alle Breakpoints zu entfernen.
  • Microsoft Edge: Öffnen Sie auf der Registerkarte Anwendung den lokalen Speicher. Klicken Sie mit der rechten Maustaste auf die Website, und wählen Sie Löschen aus.
• Vergewissern Sie sich, dass Sie das ASP.NET Core-HTTPS-Entwicklungszertifikat installiert haben und diesem vertrauen. Weitere Informationen finden Sie unter Erzwingen von HTTPS in ASP.NET Core.
• Visual Studio erfordert die Option JavaScript-Debugging für ASP.NET (Chrome und Edge) aktivieren-Option in Tools>Optionen>Debuggen>Allgemein. Dies ist die Standardeinstellung für Visual Studio. Wenn das Debuggen nicht funktioniert, vergewissern Sie sich, dass die Option ausgewählt ist.
• Wenn Ihre Umgebung einen HTTP-Proxy verwendet, sorgen Sie dafür, dass localhost in den Umgehungseinstellungen des Proxys eingeschlossen ist. Dies können Sie tun, indem Sie die NO_PROXY-Umgebungsvariable an einem der beiden folgenden Orte festlegen:
  • Die launchSettings.json-Datei für das Projekt
  • Auf Ebene der Umgebungsvariablen für Benutzer oder System, damit sie auf alle Apps angewendet wird. Wenn Sie eine Umgebungsvariable verwenden, starten Sie Visual Studio neu, damit die Änderungen übernommen werden.
• Stellen Sie sicher, dass Firewalls oder Proxys die Kommunikation mit dem Debugproxy (NodeJS-Prozess) nicht blockieren. Weitere Informationen finden Sie im Abschnitt Firewallkonfiguration.

Haltepunkte in OnInitialized{Async} werden nicht erreicht

Der Debugproxy des Blazor-Frameworks wird beim Starten der App nicht sofort gestartet, sodass Haltepunkte in den OnInitialized{Async} Lebenszyklusmethoden möglicherweise nicht getroffen werden. Es wird empfohlen, am Anfang des Methodentextes eine Verzögerung hinzuzufügen, um dem Debugproxy etwas Zeit zum Starten zu geben, bevor der Breakpoint erkannt wird. Sie können die Verzögerung auf Grundlage einer if-Compileranweisung einschließen, um sicherzustellen, dass die Verzögerung für einen Releasebuild der App nicht vorhanden ist.

OnInitialized:

protected override void OnInitialized()
{
#if DEBUG
    Thread.Sleep(10000);
#endif

    ...
}

OnInitializedAsync:

protected override async Task OnInitializedAsync()
{
#if DEBUG
    await Task.Delay(10000);
#endif

    ...
}

Zeitüberschreitung in Visual Studio (Windows)

Wenn Visual Studio eine Ausnahme auslöst, dass der Debugadapter nicht gestartet werden konnte, und meldet, dass das Timeout erreicht wurde, können Sie das Timeout mit einer Registrierungseinstellung anpassen:

VsRegEdit.exe set "<VSInstallFolder>" HKCU JSDebugger\Options\Debugging "BlazorTimeoutInMilliseconds" dword {TIMEOUT}

Der Platzhalter {TIMEOUT} im vorangehenden Befehl wird in Millisekunden angegeben. Beispielsweise wird eine Minute als 60000 zugewiesen.

<PropertyGroup>
  <WasmEnableHotReload>true</WasmEnableHotReload>
</PropertyGroup>

<PropertyGroup>
  <WasmEnableHotReload>false</WasmEnableHotReload>
</PropertyGroup>