Entender as diferentes versões do SDK do WebView2

O SDK do WebView2 é fornecido como uma versão de Pré-lançamento ou Versão do pacote NuGet Microsoft.Web.WebView2 . Use um SDK pré-lançamento com um canal de visualização do Microsoft Edge ou use um SDK de lançamento com o WebView2 Runtime.

Pré-lançamento Os pacotes de SDK serão usados durante o desenvolvimento se você quiser testar as APIs WebView2 mais recentes, incluindo as APIs Experimentais, antes que o suporte para essas APIs seja adicionado ao Runtime. O canal canário é recomendado, pois tem as implementações das APIs mais recentes. Quando você quiser testar e usar APIs Experimentais do WebView2, use a seguinte combinação:

• Uma versão pré-lançamento do SDK do WebView2.
• Um canal de visualização do Microsoft Edge em seu cliente de desenvolvimento.

Lançamento Os pacotes SDK contêm apenas APIs estáveis, não APIs experimentais. Quando estiver trabalhando em uma versão de produção do aplicativo WebView2, use a seguinte combinação:

• Uma versão de versão do SDK do WebView2.
• O Runtime do WebView2 em seu cliente de desenvolvimento.

Mais detalhes sobre os pacotes de SDK de pré-lançamento e lançamento são fornecidos abaixo.

Fases da introdução de APIs

Novas APIs são introduzidas em fases da seguinte maneira:

status de API	Descrição
Experimental	1. Primeiro, uma API é Experimental em um SDK de pré-lançamento. Você pode testar essas APIs e fornecer comentários. A API ainda não está em um SDK de lançamento.
Estável em um SDK de pré-lançamento	2. Em seguida, a API é promovida a Estável no SDK de Pré-lançamento. A API ainda não está em um SDK de lançamento.
Estável em um SDK de versão	3. Em seguida, a API Estável é promovida para ser incluída no SDK de versão. Normalmente, isso acontece 1 mês depois que a API é promovida a Estável em um SDK pré-lançamento. A API também permanece no SDK de Pré-lançamento.

Selecionando qual tipo de SDK usar

Para selecionar qual versão do pacote NuGet do SDK do WebView2 um projeto do Visual Studio usa, no Visual Studio, clique com o botão direito do mouse em um projeto, selecione Gerenciar Pacotes NuGet, selecione ou desmarque a caixa de seleção Incluir pré-lançamento, selecione o pacote Microsoft.Web.WebView2 e, em seguida, na lista suspensa Versão , selecione uma versão do pacote NuGet Microsoft.Web.WebView2 .

Para obter detalhes, consulte Instalar ou atualizar o SDK do WebView2 em Configurar seu ambiente de desenvolvimento para WebView2. Você também pode exibir a lista de pacotes de SDK do Microsoft.Web.WebView2 no site do NuGet.

Usar uma versão pré-lançamento do SDK junto com um canal de visualização do Microsoft Edge

Ao desenvolver um aplicativo Evergreen WebView2, teste regularmente o aplicativo em relação ao canal de visualização mais recente do Microsoft Edge, além de testar no WebView2 Runtime. Como a plataforma Web está em constante evolução, o teste regular é a melhor maneira de garantir que seu aplicativo continue funcionando conforme o planejado.

Ao usar um pacote de SDK de pré-lançamento do WebView2, use um canal de visualização do Microsoft Edge em seu cliente de desenvolvimento. Os canais de visualização também são chamados de canais insiders . O canal de visualização canário é recomendado em vez de Beta ou Dev, pois o Canary é mais recente e tem implementações das APIs Experimentais mais recentes.

O pacote SDK de pré-lançamento é um superconjunto do pacote SDK de versão. Um SDK de pré-lançamento contém assinaturas de método para:

• APIs experimentais.
• APIs estáveis que não são mais experimentais, mas ainda não foram incluídas em um SDK de lançamento.
• APIs estáveis que foram adicionadas aos SDKs de versão.

Os canais de visualização do Microsoft Edge fornecem as implementações de APIs Experimentais do WebView2 e de APIs Estáveis. As APIs experimentais estão sujeitas a alterações com base em comentários. Evite usar um pacote de SDK pré-lançamento para criar aplicativos de produção.

Para obter informações sobre como apontar temporariamente seu aplicativo para um canal de visualização em vez de padrão para o WebView2 Runtime, consulte Testar as próximas APIs e recursos.

Veja também:

• Pré-lançamento de teste usando canais de visualização
• Auto-host implantando canais de visualização

Usar uma versão de versão do SDK junto com o Runtime

Ao usar um pacote de SDK de versão do WebView2, use o Runtime Do Evergreen WebView2 em seu cliente de desenvolvimento, em vez de um canal de visualização do Microsoft Edge. Por padrão, um aplicativo WebView2 tem como destino o Runtime e não o Microsoft Edge. Por design, o canal Do Microsoft Edge Stable não dá suporte ao WebView2.

O pacote SDK de versão contém todas as APIs Stable Win32 C/C++ e .NET que estão em versão de produção e não inclui assinaturas de método para APIs Experimentais. Todas as APIs que estão em um pacote SDK de versão têm suporte total, em um número de build igual ou maior do WebView2 Runtime.

O pacote SDK de versão contém os seguintes componentes:

• APIs Win32 C/C++.
• APIs do .NET: WPF, WinForms e Core.

Para obter mais informações sobre a atualização automática do Evergreen Runtime, confira Distribuir seu aplicativo e o WebView2 Runtime.

Cadência de liberação

Novas versões do SDK do WebView2 são enviadas com a mesma cadência geral que o navegador Microsoft Edge, que é aproximadamente a cada quatro semanas.

Versão mínima e número de build para instanciar o WebView2

Para que o cliente possa criar uma instância do WebView2 e usar o conjunto de APIs na versão de Disponibilidade Geral do WebView2 (build 616 do SDK), o cliente deve ter o WebView2 Runtime versão 86.0.616.0 ou superior. O Runtime 86.0.616.0 é uma versão especial, pois é a versão de Disponibilidade Geral.

Em um computador de desenvolvimento, o cliente deve ter o canal de visualização do Microsoft Edge versão 86.0.616.0 ou superior, ou o WebView2 Runtime versão 86.0.616.0 ou superior.

Encaminhar compatibilidade de APIs

O SDK de versão do WebView2 tem sido compatível com a versão 1 (Versão SDK 1.0.622.22 em Notas de Versão Arquivadas para o SDK do WebView2). Você pode atualizar seu aplicativo WebView2 para usar as APIs mais recentes da versão mais recente do SDK. Seu aplicativo continuará funcionando em clientes porque os clientes têm automaticamente o Último Runtime do Evergreen WebView2.

As APIs do WebView2 em um pacote SDK de versão são estáveis e compatíveis com o encaminhamento. Uma API do WebView2 funciona ao usar um WebView2 Runtime que tem um número de build igual ou superior como o número de build do SDK no qual a API foi introduzida. O número de build é a terceira parte do número de versão de quatro partes para o SDK do Webview2 e do número de versão de quatro partes para o Microsoft Edge e o WebView2 Runtime.

• Quando você usa um SDK do WebView2 que tem um número de build igual ou menor que o WebView2 Runtime, cada API à qual você tem acesso nesse SDK funciona com essa versão do Runtime.

• Quando você usa um SDK do WebView2 que tem um número de build maior que o WebView2 Runtime, as implementações das APIs mais recentes não estão disponíveis no Runtime.

Por exemplo, se uma API for introduzida no SDK 1.0. 900.0, essa API funcionaria com o Runtime 94.0. 900+.0, mas não com o Runtime 90.0. 700.0.

Você deve coordenar a versão do SDK do WebView2 que você usa para desenvolvimento e a versão do Runtime do WebView2 instalada em computadores cliente. O cliente deve ter uma versão do Runtime que dá suporte a todas as APIs mais recentes que estão na versão do SDK que você usa para desenvolver o aplicativo. Para obter suporte completo para as APIs mais recentes em uma versão de versão do SDK, o Runtime no cliente deve ter um número de build maior ou igual ao número de build do SDK.

APIs experimentais

Para experimentar novos recursos futuros que estão em desenvolvimento, use APIs experimentais . AS APIs experimentais estão contidas em SDKs de pré-lançamento, mas não em SDKs de versão.

Desenvolver com APIs experimentais e fornecer comentários

As APIs experimentais em um pacote de SDK de pré-lançamento do WebView2 não têm garantia de serem compatíveis com o encaminhamento e podem ser removidas em atualizações futuras do Runtime.

Para obter suporte completo de APIs experimentais, use um canal de visualização do Microsoft Edge, não o Runtime Do Evergreen WebView2. Quando uma versão pré-lançamento do SDK do WebView2 é inicialmente disponibilizada, esse SDK só funciona com o Microsoft Edge Canary. Logo depois disso, o SDK do Prerelease também funciona com os canais Beta e Dev.

Use um SDK de pré-lançamento para experimentar apis experimentais novas mais cedo e fornecer comentários antes que as APIs experimentais sejam promovidas para se tornarem APIs estáveis e compatíveis com o futuro.

• As APIs experimentais (em um SDK pré-lançamento) não têm garantia de serem compatíveis com o encaminhamento.
• As APIs estáveis que estão em um SDK pré-lançamento são compatíveis com o encaminhamento, mesmo que ainda não estejam incluídas em um SDK de versão.
• As APIs estáveis que estão em um SDK de versão são compatíveis com o encaminhamento.

Para obter mais informações, consulte Encaminhar compatibilidade de APIs, acima.

A equipe do WebView2 está buscando comentários sobre APIs Experimentais do WebView2 que podem ser promovidas a Stable em versões futuras. As APIs experimentais são indicadas como "experimentais" na documentação de referência do SDK do WebView2, como: "Observação: esta é uma API experimental que é enviada com nosso SDK de pré-lançamento".

Para ajudar você a avaliar as APIs experimentais e compartilhar seus comentários, use o repositório WebView2Feedback .

Passando de APIs experimentais para APIs estáveis

Depois que uma API for movida do Experimental para o Stable status, você precisará mover o código do aplicativo para a API Estável. Não é recomendável usar APIs experimentais ou um SDK pré-lançamento para aplicativos de produção. Siga estas práticas ao mover seu aplicativo do uso de APIs experimentais para o uso de APIs estáveis:

• Em seu projeto no Visual Studio, atualize sua versão do pacote do SDK do WebView2 para um SDK de pré-lançamento ou SDK de lançamento mais recente. Consulte Instalar ou atualizar o SDK do WebView2 em Configurar seu ambiente de desenvolvimento para WebView2.

• Atualize o código do aplicativo para usar APIs estáveis em vez de APIs experimentais (para COM). A API Estável terá suporte com correções de bug, mas a API Experimental será preterida e não estará disponível no SDK mais recente (Pré-lançamento ou Versão). Depois que uma API é promovida a Stable, a versão experimental dessa API tem suporte para duas versões do SDK Prerelease, em um estado preterido. Nas versões subsequentes do SDK prerelease, as APIs experimentais podem ser modificadas, removidas ou adicionadas.

• Use sempre a detecção de recursos para garantir que a API Estável seja implementada na versão do usuário do WebView2 Runtime. Confira Detecção de recursos para testar se o Runtime instalado dá suporte a APIs adicionadas recentemente, abaixo.

• Observação somente para .NET: em um SDK do WebView2 prerelease, as APIs Estáveis do .NET retornarão às APIs Experimentais correspondentes, se o WebView2 Runtime do usuário tiver apenas a implementação da API Experimental e não tiver a implementação da API Estável.

Combinando a versão do Runtime com a versão do SDK

Na abordagem de distribuição do Evergreen, o WebView2 Runtime do cliente é atualizado automaticamente para a versão mais recente disponível. No entanto, um usuário ou administrador de TI pode optar por impedir a atualização automática do WebView2 Runtime. O Runtime desatualizado resultante no cliente pode causar problemas de compatibilidade com seu aplicativo WebView2 atualizado que usa novas APIs de um SDK recente.

Caso a atualização do WebView2 Runtime seja impedida no cliente, verifique se você sabe o número mínimo de build do WebView2 Runtime exigido pelo seu aplicativo. Para exibir ou obter as versões mais recentes do WebView2 Runtime, consulte Baixar o WebView2 Runtime na página WebView2 do Microsoft Edge em developer.microsoft.com. A versão mínima do Runtime necessária para dar suporte à versão de Disponibilidade Geral do SDK (build 616) é mais antiga do que para o Runtime mais recente. O Runtime mais recente dá suporte a todas as APIs que estão no SDK de versão mais recente.

Para marcar a compatibilidade entre números de build específicos do SDK e do canal de versão prévia do Runtime ou do Microsoft Edge, consulte Notas de Versão para o SDK do WebView2.

Detecção de recursos para testar se o Runtime instalado dá suporte a APIs adicionadas recentemente

Se seu aplicativo usar o Evergreen Runtime em vez de Versão Fixa, você deverá encerrar todas as chamadas para APIs relativamente novas do WebView2 usando QueryInterface ou try-catch. Há casos de borda em que o Evergreen Runtime de um cliente não é o build mais recente e, portanto, fica atrás do número de build do SDK, porque o Administração pode ter desativado a atualização do WebView2 Runtime ou o cliente pode estar offline.

Ao desenvolver um aplicativo WebView2 usando uma versão recente do SDK do WebView2, se você usar uma API adicionada recentemente, deverá testar ou "detectar recursos" se essa API está presente no WebView2 Runtime instalado do cliente. A forma como o aplicativo testa programaticamente o suporte à API depende da plataforma de codificação.

• Win32 C/C++. Ao solicitar a exportação CreateCoreWebView2Environment de DLL e ao executar QueryInterface em qualquer CoreWebView2 objeto, teste um valor retornado de E_NOINTERFACE. Esse valor retornado provavelmente indica que o WebView2 Runtime do cliente é uma versão mais antiga que não dá suporte a essa interface.

  Para obter um exemplo de verificação da existência de APIs WebView2 específicas no Runtime, localize try_query em AppWindow.cpp. Este arquivo encapsula chamadas de API do WebView2 na CHECK_FAILURE função macro, definida em CheckFailure.h.

• .NET e WinUI. Use try/catch e marcar para uma No such interface supported exceção ao usar métodos, propriedades e eventos que foram adicionados a versões mais recentes do SDK do WebView2. Essa exceção provavelmente indica que o WebView2 Runtime do cliente é uma versão mais antiga que não dá suporte a essa API.

Se o código determinar que uma API não está disponível no WebView2 Runtime instalado do cliente, você deverá fornecer um fallback gracioso para o recurso associado ou informar ao usuário que ele deve atualizar o WebView2 Runtime para usar o recurso.

Essa técnica é listada como uma prática recomendada de desenvolvimento do WebView2, em Testar se as APIs têm suporte pelo WebView2 Runtime instalado.