Отладка приложений WebView2 с помощью Visual Studio Code

Используйте Microsoft Visual Studio Code для отладки скриптов, выполняемых в элементах управления WebView2. Visual Studio Code имеет встроенный отладчик для отладки браузера. См . статью Отладка браузера в VS Code.

Создание файла launch.json

Для отладки кода проект должен иметь launch.json файл. Файл launch.json — это файл конфигурации отладчика для настройки и настройки отладчика Visual Studio Code. Одним из свойств, необходимых для настройки отладчика, является request свойство . Существует два request типа: launch и attach.

Следующий код демонстрирует запуск приложения из Visual Studio Code (а не присоединение отладчика к работающему экземпляру приложения). Для этого приложение должно быть создано ранее. Если в проекте нет launch.json файла, создайте новый launch.json файл во .vscode вложенной папке текущего проекта и вставьте в него следующий код:

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

Использование значения реестра

Вместо задания переменной WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS среды можно добавить новое значение реестра с именем <myApp.exe> с данными --remote-debugging-port=9222 в реестр в разделе Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArgumentsреестра , чтобы отладчик смог найти нужный порт. Дополнительные сведения см. в разделе Флаги браузера WewbView2.

Параметр URL-адреса командной строки передается

Visual Studio Code сопоставлению исходного пути теперь требуется URL-адрес, поэтому приложение теперь получает параметр командной url строки при запуске. При необходимости параметр можно игнорировать url .

Отладка кода

Чтобы задать точку останова в исходном коде, щелкните строку кода и нажмите клавишу F9:
На вкладке Выполнить выберите конфигурацию запуска в раскрывающемся меню.
Нажмите кнопку Начать отладку, которая является зеленым треугольником рядом с раскрывающимся списком конфигурации запуска:
Чтобы просмотреть выходные данные и ошибки отладки, откройте консоль отладки:

Целевая отладка WebView2

В некоторых приложениях WebView2 можно использовать несколько элементов управления WebView2. Чтобы выбрать элемент управления WebView2 для отладки в этой ситуации, можно использовать целевую отладку WebView2.

Откройте launch.json и выполните следующие действия, чтобы использовать целевую отладку WebView2.

Убедитесь, что useWebview параметр имеет значение true.
urlFilter Добавьте параметр . Когда элемент управления WebView2 переходит по URL-адресу, urlFilter значение параметра используется для сравнения строк, отображаемых в 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",

При отладке приложения может потребоваться выполнить пошаговое выполнение кода с начала процесса отрисовки. Если веб-страницы отрисовываются на сайтах и у вас нет доступа к исходному коду, можно использовать ?=value параметр , так как веб-страницы игнорируют нераспознанные параметры.

Не удается выполнить отладку двух элементов управления WebView2 одновременно

После обнаружения первого совпадения в URL-адресе отладчик останавливается. Невозможно одновременно выполнить отладку двух элементов управления WebView2, так как порт CDP является общим для всех элементов управления WebView2 и использует один номер порта.

Отладка запущенных процессов

Возможно, потребуется подключить отладчик к запущенным процессам WebView2. Для этого в обновите launch.jsonrequest параметр, изменив его значение на 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; "
}

Элемент управления WebView2 должен открыть порт протокола разработчика Chrome (CDP), чтобы разрешить отладку элемента управления WebView2. Код должен быть создан, чтобы только один элемент управления WebView2 был открыт через порт CDP перед запуском отладчика.

Кроме того, необходимо добавить новый REGKEY <myApp.exe> = --remote-debugging-port=9222 в Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments, чтобы отладчик смог найти нужный порт. Чтобы добавить этот раздел реестра, выполните следующие действия:

Нажмите клавишу с логотипом Windows и найдите редактор реестра. Откройте приложение Редактор реестра и нажмите кнопку Да , чтобы разрешить редактирование.
В дереве папок слева попробуйте развернуть HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments.
\Edge\WebView2\AdditionalBrowserArguments Если часть этого пути не существует, создайте эти три вложенные папки следующим образом:
1. Чтобы создать вложенную \Edge папку: в дереве папок щелкните папку HKEY_CURRENT_USER\Software\Policies\Microsoft правой кнопкой мыши, наведите указатель мыши на кнопку Создать и выберите пункт Ключ. Папка добавляется в качестве дочерней Microsoft папки с именем New Key #1. Щелкните папку правой кнопкой New Key #1 мыши и выберите команду Переименовать. Введите Edge имя нового ключа.
2. Создайте вложенную \WebView2 папку, как на предыдущем шаге.
3. Создайте вложенную \AdditionalBrowserArguments папку, как на предыдущем шаге.
  
  Дерево теперь развернуто до HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments.
Щелкните папку правой AdditionalBrowserArguments кнопкой мыши, наведите указатель мыши на кнопку Создать и выберите Строковое значение. В столбце Имя щелкните правой кнопкой мыши New Value #1, выберите Переименовать, а затем введите имя файла исполняемого файла приложения, например myApp.exe.
В столбце Имя щелкните правой кнопкой мыши имя исполняемого файла, например myApp.exe, и выберите команду Изменить. Откроется диалоговое окно Изменение строки .
В текстовом поле Данные значения введите --remote-debugging-port=9222:
Нажмите кнопку ОК и убедитесь, что раздел реестра соответствует следующему (с именем .exe файла в столбце Имя ):

Использование переменной среды

Вместо добавления указанного выше раздела реестра можно задать для переменной WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS среды значение --remote-debugging-port=9222. Убедитесь, что приложение запущено после задания переменной среды, и убедитесь, что приложение наследует переменную среды. Дополнительные сведения см. в разделе Флаги браузера WewbView2.

Параметры трассировки отладки

Чтобы включить трассировку отладки trace , добавьте параметр в launch.json , как показано ниже.

trace Добавьте параметр :

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

Сохранение выходных данных отладки в файл журнала:

Сохранение выходных данных отладки в файл журнала

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

Visual Studio Code выходные данные в области DEBUG CONSOLE с включенной подробной трассировкой:

Visual Studio Code выходные данные отладки с включенной подробной трассировкой

Отладка надстроек Office

При отладке надстроек Office откройте исходный код надстройки в отдельном экземпляре Visual Studio Code. Откройте launch.json приложение WebView2. Добавьте следующий код в launch.json, чтобы присоединить отладчик к надстройке Office:

,"debugServer": 4711

Отладка приложений WebView2 WinUI 2 (UWP)

Установите версию среды выполнения WebView2 после 106.0.1370.34.
Откройте редактор реестра, нажав клавишу с логотипом Windows и найдите редактор реестра. Откройте приложение Редактор реестра и выберите Да , чтобы разрешить редактирование.
Задайте для раздела HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments реестра значение --remote-debugging-pipe. Для этого выполните действия, описанные в разделе Отладка выполняемых процессов выше.
Убедитесь, что раздел реестра задан в редакторе и соответствует следующему:
Добавьте новую конфигурацию в launch.json файл. Откройте launch.json и добавьте следующий код:
```
"name": "Attach to UWP App",
"useWebView":{
   "pipeName":"JSDebugPipe"
}
"request": "attach",
"type": "msedge",
"webRoot":"${workspaceFolder}"
```
Запустите приложение.
Нажмите кнопку Начать отладку , чтобы присоединиться к процессу и начать отладку.

Исходные сопоставления с событием `WebResourceRequested` или сопоставлением имени виртуального узла

Исходные карты необходимы для отладки исходного кода скомпилированного содержимого, в том числе:

Преобразованный Код JavaScript, например TypeScript или minified JavaScript.
Скомпилированный CSS, например SASS или SCSS.

WebView2 не загружает карты источников, на которые ссылается содержимое, которое было загружено с помощью любого из подходов:

Событие WebResourceRequested . См. следующие статьи:
- Загрузка локального содержимого путем обработки WebResourceRequested события в разделе Использование локального содержимого в приложениях WebView2.
- Источник сопоставляется с событием WebResourceRequested в разделе Использование локального содержимого в приложениях WebView2.
Сопоставление имен виртуальных узлов. См. следующие статьи:
- Загрузка локального содержимого с помощью сопоставления имен виртуальных узлов в разделе Использование локального содержимого в приложениях WebView2.
- Исходные сопоставления с сопоставлением имен виртуальных узлов в разделе Использование локального содержимого в приложениях WebView2.

Устранение неполадок с отладчиком

Эти сценарии могут возникнуть при использовании отладчика.

Не останавливается в точке останова

Если отладчик не останавливается в точке останова и у вас есть выходные данные отладки:

Чтобы устранить эту проблему, убедитесь, что файл с точкой останова является тем же файлом, который используется элементом управления WebView2. Отладчик не выполняет сопоставление пути к источнику.

Не удается подключиться к запущенным процессам

Если не удается подключиться к выполняющийся процессу и возникает ошибка времени ожидания:

Чтобы устранить эту проблему, убедитесь, что элемент управления WebView2 открыл порт CDP. Убедитесь, что additionalBrowserArguments в реестре указано правильное значение или правильность параметров. См. раздел additionalBrowserArguments для dotnet и additionalBrowserArguments для Win32.

См. также

Начало работы с WebView2
Репозиторий WebView2Samples — исчерпывающий пример возможностей WebView2.
Справочник по API WebView2

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-03-25