Depurar aplicativos WebView2 com o Visual Studio Code

Use o Microsoft Visual Studio Visual Studio Code para depurar scripts que são executados em controles WebView2. O Visual Studio Code tem um depurador interno para depuração do navegador. Consulte Depuração do navegador no VS Code.

Criar um arquivo launch.json

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

O código a seguir demonstra a inicialização do aplicativo do Visual Studio Code (em vez de anexar o depurador a uma instância em execução do aplicativo). Para fazer isso, o aplicativo deve ter sido criado anteriormente. Se o projeto não tiver um launch.json arquivo, crie um novo launch.json arquivo na subpasta do .vscode projeto atual e cole o seguinte código nele:

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

Usando um valor do registro

Em vez de definir a WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS variável de ambiente, você pode adicionar um novo valor de registro nomeado <myApp.exe> com dados --remote-debugging-port=9222 ao registro em chave Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArgumentsde registro , para que o depurador possa encontrar a porta adequada. Para obter mais informações, consulte Sinalizadores do navegador WewbView2.

Parâmetro de URL de linha de comando passado em

O mapeamento do caminho de origem do Visual Studio Code agora requer uma URL, portanto, seu aplicativo agora recebe um url parâmetro de linha de comando quando for iniciado. Você pode ignorar o url parâmetro com segurança, se necessário.

Depurar seu código

1. Para definir um ponto de interrupção no código-fonte, clique em uma linha de código e pressione F9:

   

2. Na guia Executar , selecione a configuração de inicialização no menu suspenso.

3. Clique em Iniciar Depuração, que é o triângulo verde ao lado da lista suspensa de configuração de inicialização:

   

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

   

Depuração WebView2 direcionada

Em alguns aplicativos WebView2, você pode usar mais de um controle WebView2. Para escolher qual controle WebView2 depurar nessa situação, você pode usar a depuração WebView2 direcionada.

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

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

2. Adicione o urlFilter parâmetro. Quando o controle WebView2 navega para uma URL, o valor do urlFilter parâmetro é usado para comparar cadeias de caracteres que aparecem na 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 seu aplicativo, talvez seja necessário percorrer o código desde o início do processo de renderização. Se você estiver renderizando páginas da Web em sites e não tiver acesso ao código-fonte, poderá usar a ?=value opção, pois as páginas da Web ignoram parâmetros não reconhecidos.

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

Depois que a primeira correspondência for encontrada na URL, o depurador será interrompido. Não é possível depurar dois controles WebView2 ao mesmo tempo, porque a porta CDP é compartilhada por todos os controles WebView2 e usa um único número de porta.

Depurar processos em execução

Talvez seja necessário anexar o depurador para executar processos do WebView2. Para fazer isso, em launch.json, atualize o request parâmetro, alterando seu 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; "
}

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

Você também precisa adicionar uma nova REGKEY <myApp.exe> = --remote-debugging-port=9222 em Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments, para que o depurador possa encontrar a porta apropriada. Para adicionar esta chave do Registro:

1. Pressione a tecla do logotipo do Windows e procure pelo editor do registro. Abra o aplicativo Editor do Registro e 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 maneira:

   1. Para criar a \Edge subpasta: Na árvore de pastas, clique com o botão direito do mouse na pasta, passe o HKEY_CURRENT_USER\Software\Policies\Microsoft mouse sobre Novo e selecione Chave. Uma pasta é adicionada como um filho da Microsoft pasta, inicialmente chamada New Key #1. Clique com o botão direito do mouse na New Key #1 pasta e selecione Renomear. Digite Edge o nome da nova chave.

   2. Crie a \WebView2 subpasta, como na etapa anterior.

   3. Crie a \AdditionalBrowserArguments subpasta, como na etapa anterior.

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

4. Clique com o botão direito do mouse na pasta, passe o AdditionalBrowserArguments mouse sobre Novo e selecione Valor da Cadeia de Caracteres. Na coluna Nome , clique com o botão direito do mouse em New Value #1, selecione Renomear e insira o nome do arquivo do executável do aplicativo, como myApp.exe.

5. Na coluna Nome , clique com o botão direito do mouse no nome do arquivo executável, como myApp.exe, e selecione Modificar. A caixa de diálogo Editar Cadeia de Caracteres é aberta.

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

   

7. Clique no botão OK e verifique se a chave do Registro corresponde ao seguinte (com o nome do arquivo .exe na coluna Nome ):

   

Usando uma variável de ambiente

Em vez de adicionar a chave do Registro acima, você pode definir a WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS variável de ambiente como --remote-debugging-port=9222. Certifique-se de que seu aplicativo seja iniciado depois que a variável de ambiente for definida e certifique-se de que seu aplicativo herde a variável de ambiente. Para obter mais informações, consulte Sinalizadores do navegador WewbView2.

Opções de rastreamento de depuração

Para habilitar o rastreamento de depuração, adicione o trace parâmetro a , da launch.json seguinte maneira:

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.

Salvando a saída de depuração em um arquivo de log:

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

Saída do Visual Studio Code no painel CONSOLE DE DEPURAÇÃO, com o rastreamento detalhado ativado:

Depurar suplementos do Office

Se você estiver depurando Suplementos do Office, abra o código-fonte do suplemento em uma instância separada do Visual Studio Code. Abra launch.json no aplicativo WebView2. Adicione o seguinte código a launch.json, para anexar o depurador ao suplemento do Office:

,"debugServer": 4711

Depurar aplicativos WebView2 WinUI 2 (UWP)

1. Instale uma versão do WebView2 Runtime passada 106.0.1370.34.

2. Abra o Editor do Registro pressionando a tecla do logotipo do Windows e procurando pelo editor do registro. Abra o aplicativo Editor do Registro e selecione Sim para permitir a edição.

3. Defina a chave HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments do Registro igual a --remote-debugging-pipe. Para fazer isso, siga as etapas descritas na seção Depurar processos em execução acima.

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

   

5. Adicione uma nova configuração ao arquivo launch.json . 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 seu aplicativo.

7. Clique no botão Iniciar Depuração para anexar ao processo e iniciar a depuração.

   

Mapas de origem com o mapeamento de nome de WebResourceRequested evento ou host virtual

Os mapas de origem são necessários para depurar o código-fonte do conteúdo compilado, incluindo:

• JavaScript transpilado, como TypeScript ou JavaScript minificado.
• CSS compilado, como SASS ou SCSS.

O WebView2 não carrega mapas de origem referenciados pelo conteúdo que foi carregado usando qualquer uma das abordagens:

• O WebResourceRequested evento. Confira:

  • Carregamento de conteúdo local manipulando o WebResourceRequested evento em Usando conteúdo local em aplicativos WebView2.
  • Mapas de origem com o evento em Como usar conteúdo WebResourceRequestedlocal em aplicativos WebView2.

• Mapeamento de nome de host virtual. Confira:

  • Carregando conteúdo local usando o mapeamento de nome de host virtual em Usando conteúdo local em aplicativos WebView2.
  • Mapas de origem com mapeamento de nome de host virtual no Usando conteúdo local em aplicativos WebView2.

Solucionar problemas do depurador

Você pode encontrar esses cenários ao usar o depurador.

Não para no ponto de interrupção

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

Para resolver o problema, confirme se o arquivo com o ponto de interrupção é o mesmo arquivo usado pelo controle WebView2. O depurador não executa o mapeamento do caminho de origem.

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

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

Para resolver o problema, confirme se o controle WebView2 abriu a porta CDP. Verifique se additionalBrowserArguments o valor no registro está correto ou se as opções estão corretas. Consulte additionalBrowserArguments para dotnet e additionalBrowserArguments para Win32.

Confira também

• Introdução ao WebView2
• Repositório WebView2Samples - um exemplo abrangente dos recursos do WebView2.
• Referência da API WebView2