Compartilhar via

Depurar aplicações WebView2 com o Visual Studio Code

  • Artigo

Utilize o Microsoft Visual Studio Code para depurar scripts que são executados em controlos WebView2. O Visual Studio Code tem um depurador incorporado para depuração do browser. Veja Depuração do browser no VS Code.

Criar um ficheiro de launch.json

Para depurar o código, o projeto tem de ter um launch.json ficheiro. Um launch.json ficheiro é um ficheiro de configuração de depurador para configurar e personalizar o depurador do Visual Studio Code. Uma das propriedades necessárias para configurar o depurador é a request propriedade . Existem dois request tipos, launch e attach.

O código seguinte demonstra como iniciar a aplicação a partir do Visual Studio Code (em vez de anexar o depurador a uma instância em execução da aplicação). Para tal, a aplicação tem de ter sido criada anteriormente. Se o projeto não tiver um launch.json ficheiro, crie um novo launch.json ficheiro na .vscode subpasta do projeto atual e cole o seguinte código no mesmo:

"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": {
   // Customize for your app location if needed
   "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 with all your code files.
"url": "file:///${workspaceFolder}/path/to/your/toplevel/foo.html",
"webRoot": "${workspaceFolder}/path/to/your/assets"

Parâmetro de URL da linha de comandos transmitido em

O mapeamento do caminho de origem do Visual Studio Code requer agora um URL, pelo que a sua aplicação recebe agora um url parâmetro de linha de comandos quando é iniciado. Pode ignorar com segurança o url parâmetro, se necessário.

Depurar o código

  1. Para definir um ponto de interrupção no código fonte, clique numa linha de código e, em seguida, prima F9:

    Um ponto de interrupção definido no Visual Studio Code

  2. No separador Executar , selecione a configuração de início no menu pendente.

  3. Clique em Iniciar Depuração, que é o triângulo verde junto à lista pendente iniciar configuração:

    O separador Executar no Visual Studio Code

  4. Para ver a saída de depuração e os erros, abra a Consola de Depuração:

    A Consola de Depuração no Visual Studio Code

Depuração do WebView2 direcionada

Em algumas aplicações WebView2, poderá utilizar mais do que um controlo WebView2. Para escolher o controlo WebView2 a depurar nesta situação, pode utilizar a depuração webView2 direcionada.

Abra launch.json e conclua as seguintes ações para utilizar a depuração webView2 direcionada.

  1. Confirme que o useWebview parâmetro está definido como true.

  2. Adicione o urlFilter parâmetro . Quando o controlo WebView2 navega para um URL, o valor do urlFilter parâmetro é utilizado para comparar cadeias que aparecem no 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",

Ao depurar a sua aplicação, poderá ter de percorrer o código desde o início do processo de composição. Se estiver a compor páginas Web em sites e não tiver acesso ao código fonte, pode utilizar a opção, uma vez que as ?=value páginas Web ignoram parâmetros não reconhecidos.

Não é possível depurar dois controlos WebView2 ao mesmo tempo

Após a primeira correspondência ser encontrada no URL, o depurador para. Não é possível depurar dois controlos WebView2 ao mesmo tempo, porque a porta CDP é partilhada por todos os controlos WebView2 e utiliza um único número de porta.

Depurar processos em execução

Poderá ter de anexar o depurador a processos WebView2 em execução. Para tal, no launch.json, atualize o parâmetro, alterando o request respetivo valor para 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; "
},
"useWebView": true

O controlo WebView2 tem de abrir a porta CDP (Chrome Developer Protocol) para permitir a depuração do controlo WebView2. O código tem de ser criado para garantir que apenas um controlo WebView2 tem uma porta CDP aberta, antes de iniciar o depurador.

Também tem de adicionar uma nova REGKEY <myApp.exe> = --remote-debugging-port=9222Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArgumentsem , para que o depurador possa encontrar a porta adequada. Para adicionar esta chave de registo:

  1. Prima a tecla do logótipo do Windows e, em seguida, procure editor de registo. Abra a aplicação Editor de Registo e, em seguida, clique em Sim para permitir a edição.

  2. Na árvore de pastas à esquerda, tente expandir HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments.

  3. Se a \Edge\WebView2\AdditionalBrowserArguments parte desse caminho não existir, crie essas três subpastas aninhadas, da seguinte forma:

    1. Para criar a \Edge subpasta: na árvore de pastas, clique com o botão direito do rato na pasta, paire o HKEY_CURRENT_USER\Software\Policies\Microsoft cursor sobre Novo e, em seguida, selecione Chave. Uma pasta é adicionada como subordinado da Microsoft pasta, inicialmente denominada New Key #1. Clique com o botão direito do rato na pasta e, em seguida, selecione Mudar oNew Key #1 Nome. Introduza Edge o nome da nova chave.

    2. Crie a \WebView2 subpasta, tal como no passo anterior.

    3. Crie a \AdditionalBrowserArguments subpasta, tal como no passo anterior.

      A árvore está agora expandida para HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments.

  4. Clique com o botão direito do rato na pasta, paire o AdditionalBrowserArguments cursor sobre Novo e, em seguida, selecione Valor da Cadeia. Na coluna Nome , clique com o botão direito do rato em New Value #1, selecione Mudar o Nome e, em seguida, introduza o nome de ficheiro do executável da sua aplicação, como myApp.exe.

  5. Na coluna Nome , clique com o botão direito do rato no nome do ficheiro executável, como myApp.exe, e, em seguida, selecione Modificar. É aberta a caixa de diálogo Editar Cadeia .

  6. Na caixa de texto Dados do valor , introduza --remote-debugging-port=9222:

    A caixa de diálogo

  7. Clique no botão OK e, em seguida, verifique se a chave do registo corresponde ao seguinte (com o nome de ficheiro do ficheiro .exe na coluna Nome ):

    A chave de registo resultante no Editor de Registo

Opções de rastreio de depuração

Para ativar o rastreio de depuração, adicione o trace parâmetro a launch.json , da seguinte forma:

  1. Adicione o 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.

A guardar a saída de depuração num ficheiro de registo:

Guardar a saída de depuração num ficheiro de registo 

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

Saída de Depuração do Visual Studio Code com rastreio verboso ativado:

Saída de Depuração do Visual Studio Code com rastreio verboso ativado

Depurar suplementos do Office

Se estiver a depurar Suplementos do Office, abra o código fonte do suplemento numa instância separada do Visual Studio Code. Abra launch.json na sua aplicação WebView2. Adicione o seguinte código a launch.json, para anexar o depurador ao suplemento do Office:

,"debugServer": 4711

Depurar aplicações WebView2 WinUI 2 (UWP)

  1. Instale uma versão do WebView2 Runtime anterior 106.0.1370.34a .

  2. Abra o Editor de Registo ao premir a tecla do logótipo do Windows e, em seguida, procure o editor de registo. Abra a aplicação Editor de Registo e selecione Sim para permitir a edição.

  3. Defina a chave HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments de registo igual a --remote-debugging-pipe. Para tal, siga os passos descritos na secção Depurar processos de execução acima.

  4. Verifique se a chave de registo está definida no editor e corresponde ao seguinte:

    Definir a chave de registo AdditionalBrowserArguments como --remote-debugging-pipe

  5. Adicione uma nova configuração ao seu launch.json ficheiro. Abra launch.json e adicione o seguinte código:

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

  6. Inicie a sua aplicação.

  7. Clique no botão Iniciar Depuração para anexar ao processo e começar a depurar.

    Executar e Depurar

Resolver problemas do depurador

Poderá encontrar estes cenários ao utilizar o depurador.

Não para no ponto de interrupção

Se o depurador não parar no ponto de interrupção e tiver a saída de depuração:

Para resolver o problema, confirme que o ficheiro com o ponto de interrupção é o mesmo ficheiro utilizado pelo controlo WebView2. O depurador não efetua o mapeamento do caminho de origem.

Não é possível anexar ao processo em execução

Se não conseguir anexar a um processo em execução e receber um erro de tempo limite:

Para resolver o problema, confirme que o controlo WebView2 abriu a porta CDP. Certifique-se de que o valor additionalBrowserArguments no registo está correto ou que as opções estão corretas. Veja additionalBrowserArguments para dotnet e additionalBrowserArguments para Win32.

Confira também