Debuggen von WebView2-Apps mit Visual Studio Code

Verwenden Sie Microsoft Visual Studio Code zum Debuggen von Skripts, die in WebView2-Steuerelementen ausgeführt werden.

Detaillierter Inhalt:

Einführung

Verwenden Sie Microsoft Visual Studio Code zum Debuggen von Skripts, die in WebView2-Steuerelementen ausgeführt werden.

Visual Studio Code verfügt über einen integrierten Debugger für das Browserdebugging. Siehe Browserdebugging in VS Code.

Erstellen einer launch.json Datei

Zum Debuggen deines Codes muss dein Projekt über eine launch.json Datei verfügen. Eine launch.json Datei ist eine Debuggerkonfigurationsdatei zum Konfigurieren und Anpassen des Visual Studio Code-Debuggers. Eine der Eigenschaften, die zum Konfigurieren des Debuggers erforderlich ist, ist die request Eigenschaft. Es gibt zwei request Arten: launch und attach.

Der folgende Code veranschaulicht das Starten der App über Visual Studio Code (anstatt den Debugger an eine ausgeführte instance der App anzufügen). Dazu muss die App zuvor erstellt worden sein. Wenn Ihr Projekt keine Datei enthält launch.json , erstellen Sie eine neue launch.json Datei im .vscode Unterordner im aktuellen Projekt, und fügen Sie den folgenden Code ein:

"name": "Hello debug world",
"type": "msedge",
"port": 9222, // The port value is optional, and the default value is 9222.
"request": "launch",
"runtimeExecutable": "C:/path/to/your/webview2/app.exe",
"env": {
   // The following variable is needed when the "runtimeExecutable" property is set.
   // The port number below must match the value of the "port" property above.
   "WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS": "--remote-debugging-port=9222"
   // Customize for your app location.
   "Path": "%path%;e:/path/to/your/app/location; "
},
"useWebView": true,
// The following two lines set up source path mapping, where "url" is the start page
// of your app, and "webRoot" is the top-level directory containing all your code files.
"url": "file:///${workspaceFolder}/path/to/your/toplevel/foo.html",
"webRoot": "${workspaceFolder}/path/to/your/assets"

Verwenden eines Registrierungswerts

Anstatt die WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS Umgebungsvariable festzulegen, können Sie der Registrierung unter dem Registrierungsschlüssel Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArgumentseinen neuen Registrierungswert namens <myApp.exe> with data --remote-debugging-port=9222 hinzufügen, damit der Debugger den richtigen Port finden kann. Weitere Informationen finden Sie unter WebView2-Browserflags.

Parameter der Befehlszeilen-URL übergeben

Für die Quellpfadzuordnung in Visual Studio Code ist jetzt eine URL erforderlich, sodass Ihre App beim Starten einen url Befehlszeilenparameter empfängt. Sie können den url Parameter bei Bedarf ignorieren.

Debuggen des Codes

  1. Klicken Sie zum Festlegen eines Haltepunkts in Ihrem Quellcode auf eine Codezeile, und drücken Sie F9:

    Ein Haltepunkt, der in Visual Studio Code festgelegt wurde

  2. Wählen Sie auf der Registerkarte Ausführen die Startkonfiguration aus dem Dropdownmenü aus.

  3. Klicken Sie auf "Debuggen starten", welches grüne Dreieck neben der Dropdownliste der Startkonfiguration angezeigt wird:

    Die Registerkarte

  4. Um die Debugausgabe und die Fehler anzuzeigen, öffnen Sie die Debugkonsole:

    Die Debugkonsole in Visual Studio Code

Gezieltes WebView2-Debuggen

In einigen WebView2-Apps können Sie mehr als ein WebView2-Steuerelement verwenden. Verwenden Sie das gezielte WebView2-Debuggen, um auszuwählen, welches WebView2-Steuerelement in dieser Situation debuggen soll.

Öffnen Sie die folgenden Aktionen, und führen Sie launch.json die folgenden Aktionen aus, um gezieltes WebView2-Debuggen zu verwenden.

  1. Vergewissern Sie sich, dass der useWebview Parameter auf truefestgelegt ist.

  2. Fügen Sie den urlFilter Parameter hinzu. Wenn das WebView2-Steuerelement zu einer URL navigiert, wird der urlFilter Parameterwert verwendet, um Zeichenfolgen zu vergleichen, die in der URL angezeigt werden.

"useWebview": "true",
"urlFilter": "*index.ts",

// Options for "urlFilter":
// Match any url that ends with "index.ts":
"urlFilter": "*index.ts",
// Match any url that contains "index" anywhere in the URL:
"urlFilter": "*index*",
// Explicitly match a file named "index.ts":
"urlFilter": "file://C:/path/to/my/index.ts",

Beim Debuggen Ihrer App müssen Sie möglicherweise den Code vom Anfang des Renderingprozesses an durchlaufen. Wenn Sie Webseiten auf Websites rendern und keinen Zugriff auf den Quellcode haben, können Sie die ?=value Option verwenden, da Webseiten unbekannte Parameter ignorieren.

Gleichzeitiges Debuggen von zwei WebView2-Steuerelementen nicht möglich

Nachdem die erste Übereinstimmung in der URL gefunden wurde, wird der Debugger beendet. Sie können nicht zwei WebView2-Steuerelemente gleichzeitig debuggen, da der CDP-Port von allen WebView2-Steuerelementen gemeinsam genutzt wird und eine einzige Portnummer verwendet.

Debuggen laufender Prozesse

Möglicherweise müssen Sie den Debugger an ausgeführte WebView2-Prozesse anfügen. Aktualisieren Sie dazu launch.jsonin den request Parameter, und ändern Sie seinen Wert in attach:

"name": "Hello debugging world",
"type": "msedge",
"port": 9222,
"request": "attach",
"runtimeExecutable": "C:/path/to/your/webview2/myApp.exe",
"env": {
   "Path": "%path%;e:/path/to/your/build/location; "
}

Ihr WebView2-Steuerelement muss den Chrome Developer Protocol (CDP)-Port öffnen, um das Debuggen des WebView2-Steuerelements zu ermöglichen. Der Code muss so erstellt werden, dass nur ein WebView2-Steuerelement einen CDP-Port geöffnet hat, bevor der Debugger gestartet wird.

Sie müssen auch einen neuen REGKEY <myApp.exe> = --remote-debugging-port=9222 unter Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArgumentshinzufügen, damit der Debugger den richtigen Port finden kann. So fügen Sie diesen Registrierungsschlüssel hinzu:

  1. Drücken Sie die Windows-Logo-Taste und suchen Sie dann nach dem Registrierungs-Editor. Öffnen Sie die App "Registrierungs-Editor ", und klicken Sie dann auf "Ja ", um die Bearbeitung zuzulassen.

  2. Versuchen Sie in der Ordnerstruktur auf der linken Seite zu erweitern HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments.

  3. Wenn der \Edge\WebView2\AdditionalBrowserArguments Teil dieses Pfads nicht vorhanden ist, erstellen Sie diese drei geschachtelten Unterordner wie folgt:

    1. So erstellen Sie den \Edge Unterordner: Klicken Sie in der Ordnerstruktur mit der rechten Maustaste auf den HKEY_CURRENT_USER\Software\Policies\Microsoft Ordner, zeigen Sie auf Neu, und wählen Sie dann Schlüssel aus. Ein Ordner wird als untergeordnetes Element des Ordners Microsoft hinzugefügt und ursprünglich mit dem Namen New Key #1"" benannt. Klicken Sie mit der rechten Maustaste auf den New Key #1 Ordner, und wählen Sie Umbenennen aus. Geben Sie den Namen des neuen Schlüssels ein Edge .

    2. Erstellen Sie den \WebView2 Unterordner, wie im vorherigen Schritt beschrieben.

    3. Erstellen Sie den \AdditionalBrowserArguments Unterordner, wie im vorherigen Schritt beschrieben.

      Der Baum ist jetzt erweitert zu HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments.

  4. Klicken Sie mit der rechten Maustaste auf den AdditionalBrowserArguments Ordner, zeigen Sie auf Neu, und wählen Sie dann Zeichenfolgenwert aus. Klicken Sie in der Spalte Name mit der rechten Maustaste auf New Value #1, wählen Sie Umbenennen aus, und geben Sie dann den Dateinamen der ausführbaren App-Datei ein, z. BmyApp.exe. . .

  5. Klicken Sie in der Spalte Name mit der rechten Maustaste auf den Namen der ausführbaren Datei, z. B myApp.exe. , und wählen Sie dann Ändern aus. Das Dialogfeld "Zeichenfolge bearbeiten " wird geöffnet.

  6. Geben Sie in das Textfeld Wertdaten folgendes ein --remote-debugging-port=9222:

    Das Dialogfeld

  7. Klicken Sie auf die Schaltfläche "OK ", und überprüfen Sie dann, ob der Registrierungsschlüssel folgendermaßen übereinstimmt (mit dem Dateinamen der .exe Datei in der Spalte "Name "):

    Der resultierende Registrierungsschlüssel im Registrierungs-Editor

Verwenden einer Umgebungsvariablen

Anstatt den obigen Registrierungsschlüssel hinzuzufügen, können Sie die WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS Umgebungsvariable auf --remote-debugging-port=9222setzen. Stellen Sie sicher, dass Ihre Anwendung gestartet wird, nachdem die Umgebungsvariable festgelegt wurde, und stellen Sie sicher, dass Ihre Anwendung die Umgebungsvariable erbt. Weitere Informationen finden Sie unter WebView2-Browserflags.

Debuggen von Ablaufverfolgungsoptionen

Um die Debug-Ablaufverfolgung zu aktivieren, fügen Sie den trace Parameter wie folgt hinzu launch.json :

  1. Fügen Sie den trace Parameter hinzu:
"name": "Hello debugging world",
"type": "msedge",
"port": 9222,
"request": "attach",
"runtimeExecutable": "C:/path/to/your/webview2/app.exe",
"env": {
"Path": "%path%;e:/path/to/your/build/location; "
},
"useWebView": true
,"trace": true  // Turn on debug tracing, and save the output to a log file.

Speichern der Debugausgabe in einer Protokolldatei:

Debugausgabe in einer Protokolldatei speichern 

,"trace": "verbose"  // Turn on verbose tracing in the Debug Output pane.

Visual Studio Code-Ausgabe im Bereich "DEBUG-KONSOLE " mit aktivierter ausführlicher Ablaufverfolgung:

Visual Studio Code Debugausgabe mit aktivierter ausführlicher Ablaufverfolgung

Debuggen von Office-Add-Ins

Wenn Sie Office-Add-Ins debuggen, öffnen Sie den Add-In-Quellcode in einer separaten Instance von Visual Studio Code. Öffnen Sie launch.json in Ihrer WebView2-App. Fügen Sie den folgenden Code in launch.jsonhinzu, um den Debugger an das Office-Add-In anzuhängen:

,"debugServer": 4711

Debuggen von WebView2-WinUI 2-Apps (UWP)

  1. Installieren Sie eine WebView2-Runtime-Version von früher.106.0.1370.34

  2. Öffnen Sie den Registrierungs-Editor, indem Sie die Windows-Logo-Taste drücken und dann nach Registrierungs-Editor suchen. Öffnen Sie die Anwendung Registrierungs-Editor und wählen Sie Ja , um die Bearbeitung zuzulassen.

  3. Legen Sie den Registrierungsschlüssel HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments auf --remote-debugging-pipe. Führen Sie dazu die Schritte aus, die im Abschnitt Debuggen laufender Prozesse oben beschrieben sind.

  4. Vergewissern Sie sich, dass der Registrierungsschlüssel im Editor festgelegt wurde und mit folgendem übereinstimmt:

    Festlegen des Registrierungsschlüssels

  5. Fügen Sie Ihrer launch.json Datei eine neue Konfiguration hinzu. Öffnen Sie launch.json den folgenden Code, und fügen Sie ihn hinzu:

    "name": "Attach to UWP App",
"useWebView":{
   "pipeName":"JSDebugPipe"
}
"request": "attach",
"type": "msedge",
"webRoot":"${workspaceFolder}"

  6. Starten Sie Ihre App.

  7. Klicken Sie auf die Schaltfläche "Debuggen starten ", um sie an den Prozess anzufügen und mit dem Debuggen zu beginnen.

    Ausführen und Debuggen

Quellzuordnungen mit der WebResourceRequested Ereignis- oder virtuellen Hostnamenzuordnung

Quellzuordnungen werden benötigt, um den Quellcode kompilierter Inhalte zu debuggen, einschließlich:

  • Transpiliertes JavaScript, z. B. TypeScript oder minimiertes JavaScript.
  • Kompiliertes CSS, z. B. SASS oder SCSS.

WebView2 lädt keine Quellzuordnungen, auf die von Inhalten verwiesen wird, die mit einem der beiden Ansätze geladen wurden:

Problembehandlung für den Debugger

Diese Szenarien können bei Verwendung des Debuggers auftreten.

Hört nicht beim Haltepunkt auf

Wenn der Debugger nicht am Haltepunkt stoppt und Sie über eine Debugausgabe verfügen:

Um das Problem zu beheben, überprüfen Sie, ob die Datei mit dem Haltepunkt dieselbe Datei ist, die vom WebView2-Steuerelement verwendet wird. Der Debugger führt keine Quellpfadzuordnung durch.

Kann nicht an laufenden Prozess angefügt werden

Wenn Sie keine Verbindung zu einem laufenden Prozess herstellen können und ein Timeoutfehler angezeigt wird:

Um das Problem zu beheben, bestätigen Sie, dass das WebView2-Steuerelement den CDP-Port geöffnet hat. Stellen Sie sicher, dass Ihr additionalBrowserArguments Wert in der Registrierung korrekt ist oder die Optionen richtig sind. Siehe additionalBrowserArguments für dotnet und additionalBrowserArguments für Win32.

Siehe auch

  • Last updated on