Depurar aplicações WebView2 com Visual Studio Code

Utilize o Microsoft Visual Studio Code para depurar scripts que são executados nos controlos WebView2. 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 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 de 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": {
   // 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"

Utilizar um valor de registo

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

Parâmetro de URL da linha de comandos transmitido em

Visual Studio Code mapeamento do caminho de origem 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:

   

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:

   

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

   

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

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:

   

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 ):

   

Utilizar uma variável de ambiente

Em vez de adicionar a chave de registo acima, pode definir a variável de WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS ambiente como --remote-debugging-port=9222. Certifique-se de que a aplicação é iniciada após a variável de ambiente estar definida e certifique-se de que a aplicação herda a variável de ambiente. Para obter mais informações, veja Sinalizadores do browser WewbView2.

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:

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

Visual Studio Code saída no painel CONSOLA DE DEPURAÇÃO, com o 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:

   

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.

   

Mapas de origem com o mapeamento de nomes de WebResourceRequested anfitrião virtual ou evento

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

• JavaScript transpiado, como TypeScript ou JavaScript minimizado.
• CSS compilado, como SASS ou SCSS.

O WebView2 não carrega mapas de origem referenciados por conteúdo que foi carregado através de qualquer uma das abordagens:

• O WebResourceRequested evento. Confira:

  • Carregar conteúdo local ao processar o WebResourceRequested evento em Utilizar conteúdo local em aplicações WebView2.
  • Mapas de origem com o WebResourceRequested evento em Utilizar conteúdo local em aplicações WebView2.

• Mapeamento de nomes de anfitrião virtual. Confira:

  • Carregar conteúdo local através do mapeamento de nomes de anfitrião virtual em Utilizar conteúdo local em aplicações WebView2.
  • Mapas de origem com mapeamento de nomes de anfitrião virtual em Utilizar conteúdo local em aplicações WebView2.

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

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