Déboguer des applications WebView2 avec Visual Studio Code

Utilisez Microsoft Visual Studio Code pour déboguer des scripts qui s’exécutent dans des contrôles WebView2. Visual Studio Code dispose d’un débogueur intégré pour le débogage du navigateur. Consultez Débogage de 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 pour configurer et personnaliser le débogueur Visual Studio Code. L’une des propriétés nécessaires à la configuration du débogueur est la request propriété . Il 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 à un instance en cours d’exécution de l’application). Pour ce faire, l’application doit avoir été créée précédemment. Si votre projet n’a pas de launch.json fichier, créez-en un launch.json 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 WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS variable d’environnement, vous pouvez ajouter une nouvelle valeur de Registre nommée <myApp.exe> avec des données --remote-debugging-port=9222 au Registre sous 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 WewbView2.

Paramètre d’URL de ligne de commande transmis

Visual Studio Code mappage du chemin source nécessite désormais une URL, votre application reçoit désormais un url paramètre de ligne de commande au démarrage. Si nécessaire, vous pouvez ignorer le url paramètre en toute sécurité.

Déboguer votre code

Pour définir un point d’arrêt dans votre code source, cliquez sur une ligne de code, puis appuyez sur F9 :
Sous l’onglet Exécuter , sélectionnez la configuration de lancement dans le menu déroulant.
Cliquez sur Démarrer le débogage, qui est le triangle vert en regard de la liste déroulante de configuration de lancement :
Pour afficher la sortie de débogage et les erreurs, ouvrez console de débogage :

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 et effectuez launch.json les actions suivantes pour utiliser le débogage WebView2 ciblé.

Vérifiez que le useWebview paramètre est défini sur true.
Ajoutez le urlFilter paramètre . Lorsque le contrôle WebView2 accède à 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 à partir du début du processus de rendu. Si vous affichez des 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 à des processus WebView2 en cours d’exécution. Pour ce faire, dans launch.json, mettez à jour le request paramètre, en remplaçant sa valeur attachpar :

"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 CDP (Chrome Developer Protocol) pour permettre le débogage du contrôle WebView2. Votre code doit être généré pour garantir qu’un seul contrôle WebView2 dispose d’un port CDP ouvert avant de démarrer le débogueur.

Vous devez également ajouter un nouveau REGKEY <myApp.exe> = --remote-debugging-port=9222 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 :

Appuyez sur la touche de logo Windows , puis recherchez Éditeur du Registre. Ouvrez l’application Éditeur du Registre , puis cliquez sur Oui pour autoriser la modification.
Dans l’arborescence de dossiers à gauche, essayez de développer HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments.
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 \Edge sous-dossier : dans l’arborescence 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 comme 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 maintenant développée sur HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments.
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 New Value #1droit sur , sélectionnez Renommer, puis entrez le nom de fichier de votre exécutable d’application, par myApp.exeexemple .
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.
Dans la zone de texte Données de la valeur, entrez --remote-debugging-port=9222:
Cliquez sur le bouton OK , puis vérifiez que la clé de Registre correspond à ce qui suit (avec le nom de votre .exe fichier dans la colonne Nom ) :

Utilisation d’une variable d’environnement

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

Options de suivi de débogage

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

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.

Visual Studio Code sortie dans le volet CONSOLE DEBUG, avec le suivi détaillé activé :

Visual Studio Code Sortie de débogage avec le suivi 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 un instance distinct de Visual Studio Code. Ouvrez launch.json dans votre application WebView2. Ajoutez le code suivant dans launch.json, pour attacher le débogueur au complément Office :

,"debugServer": 4711

Déboguer des applications WebView2 WinUI 2 (UWP)

Installez une version du runtime WebView2 après 106.0.1370.34.
Ouvrez l’Éditeur du Registre en appuyant sur la touche de logo Windows , puis en recherchant Éditeur du Registre. Ouvrez l’application Éditeur du Registre et sélectionnez Oui pour autoriser la modification.
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 en cours d’exécution ci-dessus.
Vérifiez que la clé de Registre est définie dans l’éditeur et qu’elle correspond à ce qui suit :

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

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

Mappage de la source avec le mappage de l’événement `WebResourceRequested` ou du nom d’hôte virtuel

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é, comme SASS ou SCSS.

WebView2 ne charge pas les mappages sources référencés par le contenu qui a été chargé à l’aide de l’une ou l’autre approche :

Événement WebResourceRequested . Voir :
- Chargement du contenu local en gérant l’événement WebResourceRequested dans Utilisation du contenu local dans les applications WebView2.
- La source est mappée à l’événement WebResourceRequested dans Utilisation du contenu local dans les applications WebView2.
Mappage du nom d’hôte virtuel. Voir :
- Chargement de contenu local à l’aide du mappage de nom d’hôte virtuel dans Utilisation du contenu local dans les applications WebView2.
- La source est mappée avec le mappage de nom d’hôte virtuel dans Utilisation du contenu local dans les applications WebView2.

Résoudre les problèmes liés au 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 disposez d’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 le mappage du chemin source.

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

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

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

Prise en main de WebView2
Référentiel WebView2Samples : un exemple complet de fonctionnalités WebView2.
Informations de référence sur l’API WebView2

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-03-27