Manipulando eventos relacionados ao processo no WebView2

O WebView2 usa vários processos para oferecer suporte aos controles WebView2 em seu aplicativo. Como esses processos podem sair durante o uso, o WebView2 fornece os CoreWebView2.ProcessFailed eventos and CoreWebView2Environment.BrowserProcessExited . Faça com que seu aplicativo use esses eventos da seguinte maneira para reagir quando esses cenários ocorrerem.

Para melhorar a confiabilidade do aplicativo WebView2, é recomendável que ele manipule pelo menos os seguintes eventos:

Para usar este artigo, recomendamos a primeira leitura do modelo de processo para aplicativos WebView2. Para obter uma lista de APIs relacionadas ao processo abordadas por este artigo, consulte Gerenciamento de processos em Visão geral das APIs do WebView2.

Eventos para processos que foram encerrados ou que falharam

Quando você inicializa um controle WebView2, o WebView2 garante que haja um WebView2 Runtime para alimentar seu controle e se conectar ao seu Grupo de Processos WebView2. Depois que essa conexão for estabelecida, seu controle começará a monitorar esses processos e relatar os seguintes eventos para que seu aplicativo possa reagir de acordo:

  • Qualquer falha no processo. Quando qualquer um dos processos no WebView2 Runtime falhar, o CoreWebView2 gerará o ProcessFailed evento. Isso pode ocorrer devido a uma falha de processo ou a um processo de renderização que não responde. Use este evento para diagnóstico e recuperação de falhas nos processos do WebView2. Consulte Lidar com falhas de processo e Um conteúdo de renderização de processo no controle WebView2 saiu inesperadamente, abaixo.

  • O processo principal do navegador é encerrado. Se o processo principal do navegador sair por qualquer motivo, o CoreWebView2Environment evento será gerado BrowserProcessExited . Use esse evento para sincronizar operações que envolvem os recursos e o tempo de vida do WebView2 Runtime, como atualizações e gerenciamento de pastas de dados do usuário . Consulte Lidar com o processo principal do navegador encerrado, abaixo.

  • O processo principal do navegador falha. Quando o processo principal do navegador falha, ele produz um ProcessFailed evento e um BrowserProcessExited evento, já que o processo principal do navegador foi encerrado devido a uma falha.

Coleta de detalhes de falha do processo

O ProcessFailed evento fornece informações detalhadas sobre a falha do processo que está sendo relatada. Seu aplicativo pode usar e coletar informações dos argumentos de evento para fins de monitoramento e diagnóstico, incluindo descrição do processo (somente para processos de utilidade) e informações de quadros (somente para processos de renderização).

Algumas falhas de processo podem gerar o ProcessFailed evento em diferentes controles WebView2 em seu aplicativo. Você deve decidir com que frequência coletar detalhes e como lidar com duplicatas para esses casos.

Além disso, a maioria das falhas de processo gerará despejos na pasta de dados do usuário, no diretório retornado por FailureReportFolderPath. Você pode usar esses despejos para entender falhas e fornecer informações adicionais ao entrar em contato com a equipe do WebView2.

Lidar com falhas de processo

Quando ocorrer uma falha no WebView2 Runtime, o ProcessFailed evento será gerado para cada controle WebView2 associado ao processo de falha. A falha pode ou não ser recuperável, e algumas falhas são recuperáveis automaticamente.

Você pode usar as seguintes propriedades dos argumentos de evento para identificar a falha:

  • ProcessFailedKind. Uma combinação da finalidade do processo (como navegador, renderizador ou GPU) e falha (saída, falta de resposta). Os processos de renderização são divididos em renderizador de quadro principal (RenderProcessExited, RenderProcessUnresponsive) e renderizador de subquadro (FrameRenderProcessExited).

  • ProcessFailedReason. Indica a categoria do problema que está causando a falha. Alguns desses motivos de falha são aplicáveis apenas a tipos de falha específicos.

O processo principal do navegador foi encerrado inesperadamente

Todos os controles WebView2 em seu aplicativo usando a mesma configuração de ambiente receberão o ProcessFailed evento com:

  • Tipo de falha:BrowserProcessExited.
  • Motivo da falha: qualquer, exceto Unresponsive e LaunchFailed.

Todos os controles WebView2 associados serão fechados e seu aplicativo deverá lidar com a recuperação dessa falha. Os controles WebView2 precisam ser recriados.

Um único BrowserProcessExited evento será gerado a partir do CoreWebview2Environment também, mas a ordem desses eventos não é garantida. Seu aplicativo deve coordenar seus manipuladores de eventos para esses dois eventos quando o processo do navegador falhar. Consulte Lidar com o processo principal do navegador encerrado, abaixo.

Um processo de renderização de conteúdo no controle WebView2 foi encerrado inesperadamente

O conteúdo nos quadros impactados (quadro principal ou secundário) é substituído por uma página de erro. Cada controle WebView2 em que o conteúdo é afetado receberá o ProcessFailed evento com:

  • Tipo de falha:RenderProcessExited ou FrameRenderProcessExited.
  • Motivo da falha: qualquer, exceto Unresponsive e ProfileDeleted.

Seu aplicativo deve lidar com a recuperação dessa falha. Se o quadro principal for afetado (RenderProcessExited), você poderá usar a API para recarregar o Reload conteúdo em seus controles. Como alternativa, você pode Close e recriar os controles WebView2.

Se o quadro principal não for afetado (FrameRenderProcessExited), o aplicativo poderá se comunicar com o quadro principal para recuperar o conteúdo nos quadros afetados. O ProcessFailed evento fornece detalhes para os quadros afetados por meio da FrameInfosForFailedProcess propriedade.

O processo da GPU foi encerrado inesperadamente

O conteúdo em seus controles WebView2 pode piscar à medida que o processo é recriado automaticamente. Cada controle WebView2 no Grupo de Processos WebView2 receberá o ProcessFailed evento com:

  • Tipo de falha:GpuProcessExited.
  • Motivo da falha: qualquer, exceto Unresponsive e ProfileDeleted.

Esta é a falha de processo WebView2 mais comum e é recuperável automaticamente. Seu aplicativo não precisa lidar com a recuperação para esse evento, mas pode coletar informações para entender quaisquer problemas persistentes ou se há uma causa subjacente para saídas repetidas do processo de GPU.

Um processo de utilitário foi encerrado inesperadamente

Pode haver algumas interrupções (por exemplo, se o processo do utilitário estava hospedando o serviço de áudio) os processos necessários são recriados automaticamente. Cada controle WebView2 no Grupo de Processos WebView2 receberá o ProcessFailed evento com:

  • Tipo de falha:UtilityProcessExited.
  • Motivo da falha: qualquer, exceto Unresponsive e ProfileDeleted.

Essa falha de processo não é fatal e é recuperável automaticamente. Seu aplicativo não precisa lidar com a recuperação para esse evento, mas pode coletar informações para entender quaisquer problemas persistentes, incluindo o ProcessDescription fornecido nos argumentos do evento.

Qualquer outro processo foi encerrado inesperadamente

A maioria dos processos no Grupo de Processos WebView2 está associada a todos os controles WebView2 que o utilizam e será gerada ProcessFailed para cada controle com:

  • Tipo de falha:PpapiBrokerProcessExited, PpapiPluginProcessExited, RenderProcessUnresponsiveSandboxHelperProcessExited, ou UnknownProcessExited.
  • Motivo da falha: qualquer, exceto Unresponsive e ProfileDeleted.

Essas falhas de processo não são fatais e seu aplicativo não precisa lidar com a recuperação de nenhuma delas, mas pode coletar informações para entender quaisquer problemas persistentes.

Lidar com renderizadores que não respondem

Quando o processo de renderização para o quadro principal em um controle WebView2 não responde à entrada do usuário, o ProcessFailed evento será gerado com:

  • Tipo de falha:RenderProcessUnresponsive.
  • Motivo da falha:Unresponsive.

O evento continuará a ser gerado enquanto o processo permanecer sem resposta. A falta de resposta do processo de renderização pode ocorrer pelos seguintes motivos:

  • Há um script de execução longa sendo executado. Por exemplo, o conteúdo da Web em seu controle WebView2 pode estar executando um XHR síncrono ou ter entrado em um loop infinito. Recarregar o controle WebView2 (chamando Reload) pode fazer com que o controle responda novamente.

  • O sistema está ocupado.

Esse evento será gerado repetidamente (por exemplo, a cada 15 segundos), portanto, você precisa decidir o limite para seu aplicativo agir sobre ele.

Lidar com o processo do navegador principal encerrado

O BrowserProcessExited evento indica que o processo principal do navegador foi encerrado e seus recursos (incluindo seus processos filho) foram liberados. Isso pode acontecer pelos seguintes motivos:

  • Todos os controles WebView2 do CoreWebView2Environment foram fechados. Os cenários de aplicativo de exemplo incluem:

    • Limpando a pasta de dados do usuário.
    • Atualizando o WebView2 Runtime.
    • Reiniciando com uma configuração de ambiente diferente.
    • Limpando o cache de autenticação.

  • O processo principal do navegador falhou. Veja O processo principal do navegador foi encerrado inesperadamente, acima.

Esse evento destina-se a operações que envolvem recursos do WebView2 Runtime. Seu aplicativo pode usar o tipo de saída e a ID do processo dos argumentos do evento para determinar quando e como lidar com o evento. Por exemplo, talvez você queira coordenar com seus ProcessFailed manipuladores de eventos para evitar condições de corrida que possam surgir da tentativa de recuperação enquanto também tenta remover a pasta de dados do usuário.

Limpar a pasta de dados do usuário

Seu aplicativo precisa aguardar até que o WebView2 Runtime libere a pasta de dados do usuário antes de excluir seu conteúdo. Depois de fechar todos os controles WebView2, o BrowserProcessExited evento indica que isso aconteceu e seu aplicativo pode continuar com a operação.

Veja também:

Atualizando o tempo de execução do WebView2

Para usar o WebView2 Runtime mais recente após uma atualização, seu aplicativo precisa fechar todos os controles do WebView2 e criar um novo CoreWebView2Environment. Para garantir que a nova versão seja usada, seu aplicativo deve aguardar o BrowserProcessExited evento; caso contrário, o processo principal do navegador pode permanecer ativo quando o novo ambiente for criado e a mudança para a nova versão falharia.

Reiniciando com uma configuração de ambiente diferente

A maior parte das configurações usadas para um CoreWebView2Environment está associada ao tempo de vida do processo principal do navegador. Para fazer alterações nessa configuração (por exemplo, no idioma), o aplicativo precisa fechar os controles WebView2 existentes e aguardar antes BrowserProcessExited de recriar os controles; caso contrário, a inicialização dos controles WebView2 do novo CoreWebView2Environment pode falhar com a configuração incompatível.

Limpando o cache de autenticação

O cache de autenticação armazena a seleção de certificados e as credenciais das Solicitações de Certificado do Cliente HTTPS.

O cache de autenticação está vinculado ao tempo de vida do processo principal do navegador. Portanto, para limpar o cache de autenticação, seu aplicativo deve recriar seus controles WebView2 de uma nova instância de processo principal do navegador.

Para garantir que uma nova instância de processo do navegador principal seja usada ao recriar os controles WebView2, seu aplicativo deve aguardar o BrowserProcessExited evento antes de continuar; caso contrário, o processo principal do navegador pode permanecer ativo quando os controles forem recriados, o que preservaria o cache de autenticação em vez de limpá-lo conforme o esperado.

Confira também

  • Last updated on