Déboguer des applications WebView2 avec Visual Studio Code

Utilisez Microsoft Visual Studio Code pour déboguer des scripts qui s’exécutent dans les contrôles WebView2.

Contenu détaillé :

Introduction

Utilisez Microsoft Visual Studio Code pour déboguer des scripts qui s’exécutent dans les contrôles WebView2.

Visual Studio Code dispose d’un débogueur intégré pour le débogage du navigateur. Consultez Débogage du navigateur dans VS Code.

Créer un fichier launch.json

Pour déboguer votre code, votre projet doit avoir un launch.json fichier. Un launch.json fichier est un fichier de configuration du débogueur permettant de configurer et de personnaliser le débogueur de Visual Studio Code. L’une des propriétés nécessaires pour configurer le débogueur est la request propriété. Il en existe deux request types : launch et attach.

Le code suivant illustre le lancement de l’application à partir de Visual Studio Code (plutôt que d’attacher le débogueur à une instance en cours d’exécution de l’application). Pour ce faire, l’application doit avoir été créée au préalable. Si votre projet n’a launch.json pas de fichier, créez un launch.json fichier dans le .vscode sous-dossier de votre projet actuel, puis collez-y le code suivant :

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

Utilisation d’une valeur de Registre

Au lieu de définir la variable d’environnement WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS , vous pouvez ajouter une nouvelle valeur de Registre nommée <myApp.exe> avec des données --remote-debugging-port=9222 au Registre sous la clé Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArgumentsde Registre , afin que le débogueur puisse trouver le port approprié. Pour plus d’informations, consultez Indicateurs de navigateur WebView2.

Paramètre d’URL de ligne de commande transmis dans

Le mappage de chemin d’accès source de Visual Studio Code nécessite désormais une URL, de sorte que votre application reçoit désormais un url paramètre de ligne de commande au démarrage. Vous pouvez ignorer le url paramètre en toute sécurité, si nécessaire.

Déboguer votre code

  1. Pour définir un point d’arrêt dans votre code source, cliquez sur une ligne de code, puis appuyez sur F9 :

    Un point d’arrêt défini dans Visual Studio Code

  2. Sous l’onglet Exécuter , sélectionnez la configuration de lancement dans le menu déroulant.

  3. Cliquez sur Démarrer le débogage, qui est le triangle vert en regard de la liste déroulante de la configuration de lancement :

    L’onglet Exécuter dans Visual Studio Code

  4. Pour afficher la sortie de débogage et les erreurs, ouvrez la console de débogage :

    Console de débogage dans Visual Studio Code

Débogage WebView2 ciblé

Dans certaines applications WebView2, vous pouvez utiliser plusieurs contrôles WebView2. Pour choisir le contrôle WebView2 à déboguer dans cette situation, vous pouvez utiliser le débogage WebView2 ciblé.

Ouvrez launch.json et effectuez les actions suivantes pour utiliser le débogage WebView2 ciblé.

  1. Vérifiez que le useWebview paramètre est défini sur true.

  2. Ajoutez le urlFilter paramètre. Lorsque le contrôle WebView2 navigue vers une URL, la valeur du urlFilter paramètre est utilisée pour comparer les chaînes qui apparaissent dans l’URL.

"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",

Lors du débogage de votre application, vous devrez peut-être parcourir le code depuis le début du processus de rendu. Si vous effectuez le rendu de pages web sur des sites et que vous n’avez pas accès au code source, vous pouvez utiliser l’option ?=value , car les pages web ignorent les paramètres non reconnus.

Impossible de déboguer deux contrôles WebView2 en même temps

Une fois la première correspondance trouvée dans l’URL, le débogueur s’arrête. Vous ne pouvez pas déboguer deux contrôles WebView2 en même temps, car le port CDP est partagé par tous les contrôles WebView2 et utilise un seul numéro de port.

Déboguer les processus en cours d’exécution

Vous devrez peut-être attacher le débogueur aux processus WebView2 en cours d’exécution. Pour ce faire, dans , mettez à launch.jsonjour le request paramètre en changeant sa valeur sur 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; "
}

Votre contrôle WebView2 doit ouvrir le port Chrome Developer Protocol (CDP) pour permettre le débogage du contrôle WebView2. Votre code doit être créé pour s’assurer qu’un seul contrôle WebView2 a un port CDP ouvert, avant de démarrer le débogueur.

Vous devez également ajouter une nouvelle clé <myApp.exe> = --remote-debugging-port=9222 de Registre sous Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments, afin que le débogueur puisse trouver le port approprié. Pour ajouter cette clé de Registre :

  1. Appuyez sur la touche Windows , puis recherchez Éditeur du Registre. Ouvrez l’application Éditeur du Registre , puis cliquez sur Oui pour autoriser la modification.

  2. Dans l’arborescence des dossiers à gauche, essayez de développer HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments.

  3. Si la \Edge\WebView2\AdditionalBrowserArguments partie de ce chemin d’accès n’existe pas, créez ces trois sous-dossiers imbriqués, comme suit :

    1. Pour créer le sous-dossier : Dans l’arborescence \Edge des dossiers, cliquez avec le bouton droit sur le HKEY_CURRENT_USER\Software\Policies\Microsoft dossier, pointez sur Nouveau, puis sélectionnez Clé. Un dossier est ajouté en tant qu’enfant du Microsoft dossier, initialement nommé New Key #1. Cliquez avec le bouton droit sur le New Key #1 dossier, puis sélectionnez Renommer. Entrez Edge le nom de la nouvelle clé.

    2. Créez le \WebView2 sous-dossier, comme à l’étape précédente.

    3. Créez le \AdditionalBrowserArguments sous-dossier, comme à l’étape précédente.

      L’arborescence est désormais étendue à HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments.

  4. Cliquez avec le bouton droit sur le AdditionalBrowserArguments dossier, pointez sur Nouveau, puis sélectionnez Valeur de chaîne. Dans la colonne Nom , cliquez avec le bouton droit sur New Value #1, sélectionnez Renommer, puis entrez le nom de fichier de l’exécutable de votre application, tel que myApp.exe.

  5. Dans la colonne Nom , cliquez avec le bouton droit sur le nom de votre fichier exécutable, par myApp.exeexemple, puis sélectionnez Modifier. La boîte de dialogue Modifier la chaîne s’ouvre.

  6. Dans la zone de texte Données de la valeur , entrez --remote-debugging-port=9222:

    La boîte de dialogue « Modifier la chaîne » pour définir la clé de Registre

  7. Cliquez sur le bouton OK , puis vérifiez que la clé de Registre correspond aux éléments suivants (avec le nom de votre .exe fichier dans la colonne Nom ) :

    Clé de Registre résultante dans l’Éditeur du Registre

Utilisation d’une variable d’environnement

Au lieu d’ajouter la clé de Registre ci-dessus, vous pouvez définir la variable d’environnement WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS sur --remote-debugging-port=9222. Assurez-vous que votre application est démarrée après la définition de la variable d’environnement et que votre application hérite de la variable d’environnement. Pour plus d’informations, consultez Indicateurs de navigateur WebView2.

Options de suivi de débogage

Pour activer le suivi de débogage, ajoutez le trace paramètre à launch.json , comme suit :

  1. Ajoutez le trace paramètre :
"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.

Enregistrement de la sortie de débogage dans un fichier journal :

Enregistrer la sortie de débogage dans un fichier journal 

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

Sortie de Visual Studio Code dans le volet DEBUG CONSOLE, avec le traçage détaillé activé :

Sortie de débogage de Visual Studio Code avec traçage détaillé activé

Débogage des compléments Office

Si vous déboguez des compléments Office, ouvrez le code source du complément dans une instance distincte de Visual Studio Code. Ouvrez launch.json dans votre application WebView2. Ajoutez le code suivant dans launch.jsonpour attacher le débogueur au complément Office :

,"debugServer": 4711

Débogage d’applications WebView2 WinUI 2 (UWP)

  1. Installer une version du runtime WebView2 antérieure au .106.0.1370.34

  2. Ouvrez l’Éditeur du Registre en appuyant sur la touche Windows , puis en recherchant Éditeur du Registre. Ouvrez l’application Éditeur du Registre et sélectionnez Oui pour autoriser la modification.

  3. Définissez la clé HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments de Registre sur --remote-debugging-pipe. Pour ce faire, suivez les étapes décrites dans la section Déboguer les processus d’exécution ci-dessus.

  4. Vérifiez que la clé de Registre est définie dans l’éditeur et qu’elle correspond aux éléments suivants :

    Définition de la clé de Registre AdditionalBrowserArguments sur --remote-debugging-pipe

  5. Ajoutez une nouvelle configuration à votre launch.json fichier. Ouvrez launch.json et ajoutez le code suivant :

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

  6. Lancez votre application.

  7. Cliquez sur le bouton Démarrer le débogage pour l’attacher au processus et commencer le débogage.

    Exécuter et déboguer

Cartes source avec le mappage de nom d’hôte virtuel ou d’événement WebResourceRequested

Les mappages sources sont nécessaires pour déboguer le code source du contenu compilé, notamment :

  • JavaScript transpilé, tel que TypeScript ou JavaScript minifié.
  • CSS compilé, tel que SASS ou SCSS.

WebView2 ne charge pas les cartes sources qui sont référencées par le contenu qui a été chargé en utilisant l’une ou l’autre approche :

Dépanner le débogueur

Vous pouvez rencontrer ces scénarios lors de l’utilisation du débogueur.

Ne s’arrête pas au point d’arrêt

Si le débogueur ne s’arrête pas au point d’arrêt et que vous avez une sortie de débogage :

Pour résoudre le problème, vérifiez que le fichier avec le point d’arrêt est le même que celui utilisé par le contrôle WebView2. Le débogueur n’effectue pas de mappage de chemin source.

Impossible d’attacher au processus en cours d’exécution

Si vous ne pouvez pas l’attacher à un processus en cours d’exécution et que vous obtenez une erreur de délai d’attente :

Pour résoudre le problème, vérifiez que le contrôle WebView2 a ouvert le port CDP. Vérifiez que votre additionalBrowserArguments valeur dans le Registre est correcte ou que les options sont correctes. Consultez additionalBrowserArguments pour dotnet et additionalBrowserArguments pour Win32.

Voir aussi

  • Dernière mise à jour :