Depurar aplicações WebView2 com o Visual Studio

O Microsoft Visual Studio fornece várias ferramentas de depuração para códigos Web e nativos em aplicações WebView2, para depurar código web e nativo em aplicações Win32 ou Suplementos do Office. Este artigo centra-se na depuração de controlos WebView2. Também estão disponíveis os outros métodos de depuração no Visual Studio.

Resumo dos passos de alto nível

Para depurar código JavaScript num controlo WebView2:

1. Instale o componente javaScript diagnóstico no desenvolvimento do Ambiente de Trabalho com a carga de trabalho C++ do Visual Studio ou na carga de trabalho de outra plataforma.

2. Defina um ponto de interrupção numa linha de código JavaScript.

3. Na páginaDepuração de Propriedades> do projeto, defina Tipo de Depurador como JavaScript (WebView2) (em vez de Automático ou Nativo).

4. Inicie o depurador, como habitualmente. Por exemplo, na barra de menus, selecione Depurar>Iniciar Depuração (F5).

5. Na aplicação WebView2 em execução, interaja com uma página Web que executa o código JavaScript. O depurador é colocado em pausa na linha de código JavaScript que tem o ponto de interrupção.

6. Utilize os painéis de depurador no Visual Studio.

Estes passos são detalhados abaixo, com o exemplo main, Win32/C++ (WebView2APISample).

Requisitos

• Clone o repositório WebView2Samples, se quiser seguir os passos de exemplo específicos abaixo (com o exemplo main, Win32/C++, WebView2APISample). Um passo abaixo mostra como fazê-lo.

• Instale o Visual Studio 2022. Pode utilizar o Visual Studio 2022 para trabalhar com as aplicações de exemplo WebView2 e a sua própria aplicação WebView2. (O Visual Studio 2019 também funciona.) Um passo abaixo mostra como fazê-lo.

• Instale e configure as ferramentas de depurador de scripts no Visual Studio. Ou seja, instale o desenvolvimento do Ambiente de Trabalho com a carga de trabalho C++ do Visual Studio (ou a carga de trabalho equivalente para uma linguagem diferente), incluindo o componente javaScript diagnóstico. Um passo abaixo mostra como fazê-lo.

• Crie e execute o exemplo main, Win32/C++, para que a aplicação WebView2APISample seja compilada e executada (se quiser seguir os passos de exemplo específicos abaixo). Um passo abaixo mostra como fazê-lo.

• Para depurar scripts, a aplicação tem de ser iniciada a partir do Visual Studio.

• Não pode anexar um depurador a um processo WebView2 em execução.

Instalar o componente javaScript diagnóstico

Utilize o Visual Studio Installer para instalar o desenvolvimento do Ambiente de Trabalho com a carga de trabalho C++ do Visual Studio, incluindo o componente javaScript diagnóstico, da seguinte forma. Em alternativa, se estiver a utilizar uma carga de trabalho de linguagem diferente de C++, selecione o componente de diagnóstico JavaScript dessa carga de trabalho, semelhante aos passos abaixo.

1. Se ainda não o tiver feito, clone o repositório WebView2Samples, conforme descrito em Clonar o repositório WebView2Samples em Configurar o ambiente Dev para WebView2.

2. Se ainda não o tiver feito, instale o Visual Studio 2022, conforme descrito em Instalar o Visual Studio em Configurar o ambiente de Programador para WebView2.

3. No Visual Studio 2022, instale o Desenvolvimento do ambiente de trabalho com a carga de trabalho C++ , da seguinte forma:

4. Na barra de Explorer do Windows, escreva Visual Studio Installer.

5. Selecione Visual Studio Installer para abri-la.

6. Na Visual Studio Installer, na versão instalada, clique no botão Mais e, em seguida, selecione Modificar.

7. No Visual Studio, em Cargas de trabalho, selecione a carga de trabalho Desenvolvimento do Ambiente de Trabalho com C++ , para que seja apresentada uma marca de verificação:

   

8. Selecione Componentes individuais, na parte superior.

9. Na caixa de pesquisa, introduza JavaScript diagnostics.

10. Selecione a caixa de verificação diagnóstico JavaScript:

    

11. Clique no botão Modificar .

Continue com a secção seguinte, abaixo.

Selecione o depurador JavaScript (WebView2)

Em seguida, ative a depuração de scripts para aplicações WebView2, da seguinte forma.

1. Se ainda não tiver terminado, siga os passos na aplicação de exemplo Win32 para que a aplicação WebView2APISample seja compilada e executada. A solução WebView2Samples deve estar aberta no Visual Studio e a aplicação de exemplo não deve estar em execução. Em alternativa, abra o seu próprio projeto de aplicação WebView2 no Visual Studio.

2. No Visual Studio, no Gerenciador de Soluções, clique com o botão direito do rato no projeto WebView2APISample (ou no seu próprio projeto) e, em seguida, selecione Propriedades.

   A caixa de diálogo Páginas de Propriedades é aberta.

3. À esquerda, expanda Propriedades de Configuração e, em seguida, selecione Depuração.

4. À direita de Tipo de Depurador, selecione JavaScript (WebView2) e, em seguida, clique no botão OK :

   

Depurar a aplicação WebView2

Depois de efetuar a configuração acima, depure a aplicação WebView2 da seguinte forma.

1. Para definir um ponto de interrupção no código fonte, paire o rato à esquerda do número de linha e clique para definir um ponto de interrupção. Por exemplo, abra WebView2Samples\SampleApps\WebView2APISample\assets\ScenarioJavaScriptDebugIndex.jse defina um ponto de interrupção na linha 2: console.log("onAddClick+");, no corpo da onAddClick função:

   

   Ao definir um ponto de interrupção, tem de abrir o ficheiro que está exatamente no mesmo caminho associado ao controlo WebView2, porque o adaptador de depuração JS/TS não executa o mapeamento do caminho de origem.

   O ponto de interrupção será acionado quando esta secção do código for executada. Este ponto de interrupção é acionado ao clicar no botão Adicionar um novo item na aplicação de exemplo, num passo posterior abaixo.

2. Selecione o tamanho do bit da plataforma, como x64.

3. Para executar o depurador, efetue um dos seguintes procedimentos:

   • Na barra de menus, selecione Depurar>Iniciar Depuração (F5).
   • No Gerenciador de Soluções, clique com o botão direito do rato no projeto >Depurar>Iniciar Nova Instância ou Avançar para Nova Instância.
   • Clique no botão verde Reproduzir à esquerda de Local Windows Debugger.

   A aplicação WebView2APISample (ou a sua própria aplicação) é executada e aberta e o depurador liga-se ao primeiro processo WebView2 criado. EmDepuração de Propriedades> para o projeto, o Depurador Do Windows Local foi definido como JavaScript (WebView2).

4. No Visual Studio, clique no separador Saída , no canto inferior direito.

   O separador contém apenas a seguinte mensagem, que menciona o depurador JS: "Os registos verbosos são escritos em: C:\Users\myUsername\AppData\Local\Temp\visualstudio-js-debugger.txt".

5. Na janela da aplicação WebView2APISample, selecione Script de Cenário>Depurar>Ficheiro Local javaScript.

   O ficheiro WebView2APISample/Debug/x64/assets/ScenarioJavaScriptDebugIndex.html é composto:

   

6. No Visual Studio, examine o painel Saída . Foi adicionado o seguinte resultado:

   This is the very first line of code that executes.
   Second
   Third
   inside
   onAddClick+
   onAddClick-
   onAddClick+
   onAddClick-
   End
   

7. Na página Web da aplicação, clique no botão de pop-up Adicionar um novo item .

   O ponto de interrupção na onAddClick função é atingido e a aplicação é colocada em pausa no depurador.

8. Mude para a janela do Visual Studio e examine os painéis do depurador.

9. Clique no separador Saída para apresentar a saída da aplicação:

   

   A saída da aplicação mostra "Esta é a primeira linha de código que é executada", devido à linha console.log("This is the very first line of code that executes."); no ficheiro WebView2Samples\SampleApps\WebView2APISample\assets\ScenarioJavaScriptDebugIndex.html.

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.

Solução de problemas

Abra As DevTools com uma abordagem diferente de F12

Quando depura a sua aplicação no Visual Studio com o depurador nativo anexado, ao visualizar a aplicação em execução, premir F12 poderá iniciar o depurador nativo em vez de iniciar as Ferramentas de Programação.

Para abrir o DevTools, prima Ctrl+Shift+I. Em alternativa, clique com o botão direito do rato na página na aplicação em execução e, em seguida, selecione Inspect.

Mapeamento de caminho de origem virtual não suportado no Visual Studio 2019

Se utilizar o método WebView2 SetVirtualHostNameToFolderMapping , o depurador no Visual Studio 2019 não compreende o mapeamento do caminho de origem virtual, pelo que os pontos de interrupção não funcionam corretamente.

Ao definir um ponto de interrupção, tem de abrir o ficheiro que está exatamente no mesmo caminho associado ao controlo WebView2, porque o adaptador de depuração JS/TS não executa o mapeamento do caminho de origem.

O mapeamento do caminho de origem virtual é suportado pelo depurador no Visual Studio Code.

Confira também

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