Depurar aplicaciones WebView2 con Visual Studio Code

Use Microsoft Visual Studio Code para depurar las secuencias de comandos que se ejecutan en controles WebView2.

Contenido detallado:

Introducción

Use Microsoft Visual Studio Code para depurar las secuencias de comandos que se ejecutan en controles WebView2.

Visual Studio Code tiene un depurador integrado para la depuración del explorador. Consulte Depuración del explorador en VS Code.

Crear un archivo launch.json

Para depurar el código, el proyecto debe tener un launch.json archivo. Un launch.json archivo es un archivo de configuración del depurador para configurar y personalizar el depurador de Visual Studio Code. Una de las propiedades necesarias para configurar el depurador es la request propiedad. Hay dos request tipos: launch y attach.

El código siguiente muestra cómo iniciar la aplicación desde Visual Studio Code (en lugar de conectar el depurador a una instancia en ejecución de la aplicación). Para ello, la aplicación debe haberse creado anteriormente. Si el proyecto no tiene un launch.json archivo, cree un launch.json archivo nuevo en la subcarpeta del .vscode proyecto actual y pegue el código siguiente en él:

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

Usar un valor del Registro

En lugar de establecer la WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS variable de entorno, puede agregar un nuevo valor del Registro denominado <myApp.exe> con datos --remote-debugging-port=9222 al Registro en Clave Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArgumentsdel Registro para que el depurador pueda encontrar el puerto adecuado. Para obtener más información, vea Marcas del explorador WebView2.

Parámetro de URL de línea de comandos pasado en

La asignación de rutas de acceso de origen de Visual Studio Code ahora requiere una dirección URL, por lo que la aplicación recibe un url parámetro de línea de comandos cuando se inicia. Si es necesario, puede omitir el url parámetro de forma segura.

Depurar el código

  1. Para establecer un punto de interrupción en el código fuente, haga clic en una línea de código y presione F9:

    Punto de interrupción establecido en Visual Studio Code

  2. En la pestaña Ejecutar , selecciona la configuración de inicio en el menú desplegable.

  3. Haga clic en Iniciar depuración, que es el triángulo verde situado junto a la lista desplegable de configuración de inicio:

    La pestaña Ejecutar en Visual Studio Code

  4. Para ver el resultado de la depuración y los errores, abra la consola de depuración:

    La consola de depuración en Visual Studio Code

Depuración de WebView2 dirigida

En algunas aplicaciones WebView2, puede usar más de un control WebView2. Para elegir qué control WebView2 depurar en esta situación, puede usar la depuración de WebView2 de destino.

Abra launch.json y complete las siguientes acciones para usar la depuración WebView2 de destino.

  1. Confirme que el useWebview parámetro está establecido en true.

  2. Agregue el urlFilter parámetro. Cuando el control WebView2 navega a una dirección URL, el valor del urlFilter parámetro se usa para comparar las cadenas que aparecen en la dirección 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",

Al depurar la aplicación, es posible que deba recorrer el código paso a paso desde el principio del proceso de representación. Si está representando páginas web en sitios y no tiene acceso al código fuente, puede usar la ?=value opción, ya que las páginas web omiten parámetros no reconocidos.

No se pueden depurar dos controles WebView2 al mismo tiempo

Después de encontrar la primera coincidencia en la dirección URL, el depurador se detiene. No se pueden depurar dos controles WebView2 al mismo tiempo, porque el puerto CDP es compartido por todos los controles WebView2 y usa un único número de puerto.

Depurar procesos en ejecución

Es posible que tenga que adjuntar el depurador a los procesos WebView2 en ejecución. Para ello, en launch.json, actualiza el request parámetro, cambiando su valor a 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; "
}

El control WebView2 debe abrir el puerto del Protocolo de desarrollador de Chrome (CDP) para permitir la depuración del control WebView2. El código debe generarse para asegurarse de que solo un control WebView2 tenga abierto un puerto CDP, antes de iniciar el depurador.

También debe agregar una nueva clave REGKEY <myApp.exe> = --remote-debugging-port=9222 en Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments, para que el depurador pueda encontrar el puerto adecuado. Para agregar esta clave del Registro:

  1. Presione la tecla del logotipo de Windows y, a continuación, busque el editor del Registro. Abra la aplicación Editor del Registro y, a continuación, haga clic en Sí para permitir la edición.

  2. En el árbol de carpetas de la izquierda, intente expandir HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments.

  3. Si la \Edge\WebView2\AdditionalBrowserArguments parte de esa ruta de acceso no existe, cree esas tres subcarpetas anidadas, como se indica a continuación:

    1. Para crear la \Edge subcarpeta: En el árbol de carpetas, haga clic con el botón derecho en laHKEY_CURRENT_USER\Software\Policies\Microsoft carpeta, mueva el puntero sobre Nuevo y, a continuación, seleccione Clave. Una carpeta se agrega como elemento secundario de la Microsoft carpeta, inicialmente denominada New Key #1. Haga clic con el botón derecho en la New Key #1 carpeta y seleccione Cambiar nombre. Escriba Edge el nombre de la nueva clave.

    2. Cree la \WebView2 subcarpeta, como en el paso anterior.

    3. Cree la \AdditionalBrowserArguments subcarpeta, como en el paso anterior.

      El árbol ahora se expande a HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments.

  4. Haga clic con el botón derecho en la AdditionalBrowserArguments carpeta, mueva el puntero sobre Nuevo y seleccione Valor de cadena. En la columna Nombre , haga clic con el botón derecho en New Value #1, seleccione Cambiar nombre y, a continuación, escriba el nombre de archivo del ejecutable de la aplicación, como myApp.exe.

  5. En la columna Nombre , haz clic con el botón derecho en el nombre del archivo ejecutable, como myApp.exe, y, a continuación, selecciona Modificar. Se abre el cuadro de diálogo Editar cadena .

  6. En el cuadro de texto Datos del valor , escriba --remote-debugging-port=9222:

    El cuadro de diálogo

  7. Haga clic en el botón Aceptar y, a continuación, compruebe que la clave del Registro coincide con la siguiente (con el nombre del .exe archivo en la columna Nombre ):

    La clave del Registro resultante en el Editor del Registro

Uso de una variable de entorno

En lugar de agregar la clave del Registro anterior, puede establecer la WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS variable de entorno en --remote-debugging-port=9222. Asegúrese de que la aplicación se inicie después de establecer la variable de entorno y de que herede la variable de entorno. Para obtener más información, vea Marcas del explorador WebView2.

Opciones de seguimiento de depuración

Para habilitar el seguimiento de depuración, agregue el trace parámetro a launch.json , de la siguiente manera:

  1. Agregue el trace parámetro:
"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.

Guardar los resultados de depuración en un archivo de registro:

Guarde los resultados de depuración en un archivo de registro 

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

Resultado de Visual Studio Code en el panel CONSOLA DE DEPURACIÓN, con el seguimiento detallado activado:

Salida de depuración de Visual Studio Code con seguimiento detallado activado

Depurar complementos de Office

Si está depurando complementos de Office, abra el código fuente del complemento en una instancia independiente de Visual Studio Code. Abrir launch.json en la aplicación WebView2. Agregue el código siguiente en launch.json, para adjuntar el depurador al complemento de Office:

,"debugServer": 4711

Depurar aplicaciones WebView2 y WinUI 2 (UWP)

  1. Instalar una versión del entorno de ejecución de WebView2 anterior 106.0.1370.34

  2. Abra el Editor del Registro pulsando la tecla del logotipo de Windows y buscando Editor del Registro. Abra la aplicación Editor del Registro y seleccione Sí para permitir la edición.

  3. Establezca la clave HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments del Registro en el valor de --remote-debugging-pipe. Para ello, siga los pasos descritos en la sección Depurar procesos en ejecución anterior.

  4. Compruebe que la clave del Registro está establecida en el editor y coincide con lo siguiente:

    Establecer la clave del Registro AdditionalBrowserArguments en --remote-debugging-pipe

  5. Agregue una nueva configuración al launch.json archivo. Abra launch.json y agregue el código siguiente:

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

  6. Inicie la aplicación.

  7. Haga clic en el botón Iniciar depuración para adjuntarlo al proceso y comenzar la depuración.

    Ejecutar y depurar

Mapas de origen con la asignación de nombre de WebResourceRequested host virtual o evento

Los mapas de origen son necesarios para depurar el código fuente del contenido compilado, incluidos:

  • JavaScript transpilado, como TypeScript o JavaScript minimizado.
  • CSS compilado, como SASS o SCSS.

WebView2 no carga mapas de origen a los que hace referencia el contenido que se cargó mediante cualquiera de los dos métodos:

Solucionar problemas del depurador

Es posible que se produzcan estos escenarios al usar el depurador.

No se detiene en el punto de interrupción

Si el depurador no se detiene en el punto de interrupción y tiene salida de depuración:

Para solucionar el problema, confirme que el archivo con el punto de interrupción es el mismo archivo que usa el control WebView2. El depurador no realiza la asignación de rutas de origen.

No se puede adjuntar al proceso en ejecución

Si no puede adjuntar a un proceso en ejecución y recibe un error de tiempo de espera:

Para solucionar el problema, confirme que el control WebView2 abrió el puerto CDP. Asegúrese de que additionalBrowserArguments el valor del Registro sea correcto o de que las opciones sean correctas. Consulte additionalBrowserArguments para dotnet y additionalBrowserArguments para Win32.

Vea también

  • Se actualizó por última vez el