SDKs de pré-lançamento e lançamento para WebView2

O SDK do WebView2 é fornecido como uma versão de pré-lançamento ou lançamento do pacote NuGet Microsoft.Web.WebView2 . Use um SDK de 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 do SDK devem ser usados durante o desenvolvimento se você quiser testar as APIs mais recentes do WebView2, incluindo as APIs experimentais, antes que o suporte para essas APIs seja adicionado ao Runtime. O canal Canary é recomendado, pois tem as implementações das APIs mais recentes. Quando quiser testar e usar APIs Experimentais do WebView2, use a seguinte combinação:

  • Uma versão de 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 você estiver trabalhando em uma versão de produção do seu aplicativo WebView2, use a seguinte combinação:

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

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

Fases de introdução de APIs

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

Status da API Descrição
Experimental em um SDK de Pré-lançamento 1. Primeiro, uma API é experimental em um SDK de pré-lançamento. (Às vezes, as APIs pulam a fase experimental e são adicionadas diretamente a um Stable no 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 para 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 lançamento 3. Em seguida, a API estável é promovida para ser incluída no SDK de lançamento. (Às vezes, as APIs são promovidas simultaneamente para Estável em um SDK de Pré-lançamento e Estável em um SDK de Lançamento.) Isso normalmente acontece 1 mês depois que a API é promovida para Estável em um SDK de Pré-lançamento. A API também permanece no SDK de Pré-lançamento.

Diagrama das fases de introdução de novas APIs

Veja também:

Selecionando o tipo de SDK a ser usado

Para selecionar qual versão do pacote NuGet do SDK do WebView2 que um projeto do Visual Studio usa, no Visual Studio, clique com o botão direito do mouse em um projeto, selecione Gerenciar Pacotes NuGet, marque ou desmarque a caixa de seleção Incluir pré-lançamento , selecione o pacote Microsoft.Web.WebView2 e, 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 do SDK Microsoft.Web.WebView2 no site do NuGet .

Use uma versão de 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 no canal de visualização mais recente do Microsoft Edge, além de testar no WebView2 Runtime. Como a plataforma da Web está em constante evolução, testes regulares são a melhor maneira de garantir que seu aplicativo continue funcionando conforme o esperado.

Ao usar um pacote 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 de participantes do programa Office Insider . O canal de visualização Canary é recomendado em vez de Beta ou Dev, porque o Canary é o mais recente e tem implementações das APIs experimentais mais recentes.

O pacote SDK de Pré-lançamento é um superconjunto do pacote SDK de lançamento. 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 lançamento.

Os canais de visualização do Microsoft Edge fornecem as implementações de APIs Experimentais WebView2 e de APIs Estáveis. As APIs experimentais estão sujeitas a alterações com base nos comentários. Evite usar um pacote SDK de 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 usar como padrão o WebView2 Runtime, consulte Testar as próximas APIs e recursos.

Veja também:

Use uma versão de lançamento do SDK junto com o Runtime

Ao usar um pacote SDK de lançamento do WebView2, use o Evergreen WebView2 Runtime em seu cliente de desenvolvimento, em vez de um canal de visualização do Microsoft Edge. Por padrão, um aplicativo WebView2 tem como alvo o Runtime em vez do Microsoft Edge. Por padrão, o canal estável do Microsoft Edge não dá suporte ao WebView2.

O pacote SDK de lançamento contém todas as APIs estáveis que estão na 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 lançamento têm suporte total, em um número de compilação igual ou superior do WebView2 Runtime.

Veja também:

Para obter mais informações sobre a atualização automática do Evergreen Runtime, consulte:

Cadência de lançamento

As 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.

Número mínimo de versão e 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.

Compatibilidade direta de APIs

O SDK da versão do WebView2 é compatível com versões futuras desde a versão 1 (SDK da versão 1.0.622.22 para Runtime 86 (19 de outubro de 2020) 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 de lançamento mais recente do SDK. Seu aplicativo continuará a funcionar em clientes porque os clientes têm automaticamente o Evergreen WebView2 Runtime mais recente.

As APIs WebView2 em um pacote de SDK de lançamento são estáveis e compatíveis com versões posteriores. Uma API WebView2 funciona ao usar um WebView2 Runtime que tem um número de compilação igual ou superior ao número de compilação do SDK no qual a API foi introduzida. O número de compilação é 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 compilação igual ou inferior ao WebView2 Runtime, todas as APIs às quais você tem acesso nesse SDK funcionam 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 WebView2 Runtime que está 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 total para as APIs mais recentes em uma versão de lançamento 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 os novos recursos futuros que estão em desenvolvimento, use APIs Experimentais . As APIs experimentais estão contidas nos SDKs de pré-lançamento, mas não nos SDKs de lançamento.

Desenvolver com APIs experimentais e fornecer comentários

Não há garantia de que as APIs experimentais em um pacote de SDK de pré-lançamento do WebView2 sejam compatíveis com versões futuras e possam ser removidas em futuras atualizações do Runtime.

Para obter suporte total a APIs Experimentais, use um canal de visualização do Microsoft Edge, não o Evergreen WebView2 Runtime. Quando uma versão de pré-lançamento do SDK do WebView2 é disponibilizada inicialmente, esse SDK só funcionará com o Microsoft Edge Canary. Logo em seguida, o SDK de Pré-lançamento também funciona com os canais Beta e Dev.

Use um SDK de Pré-lançamento para experimentar novas APIs experimentais antecipadamente e fornecer comentários antes que as APIs experimentais sejam promovidas para se tornarem APIs estáveis e compatíveis com versões futuras.

  • Não há garantia de que as APIs experimentais (em um SDK de pré-lançamento) sejam compatíveis com versões futuras.
  • As APIs estáveis que estão em um SDK de pré-lançamento são compatíveis com versões anteriores, mesmo que ainda não estejam incluídas em um SDK de lançamento.
  • As APIs estáveis que estão em um SDK de lançamento são compatíveis com versões anteriores.

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

A equipe do WebView2 está buscando comentários sobre as APIs Experimentais do WebView2 que podem ser promovidas para Estável 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 é fornecida com nosso SDK de pré-lançamento."

Para ajudá-lo a avaliar as APIs experimentais e compartilhar seus comentários, use o repositório WebView2Feedback .

Veja também:

Mudança de APIs experimentais para APIs estáveis

Depois que uma API tiver sido movida do status Experimental para o Estável, você precisará mover o código do seu aplicativo para a API Estável. O uso de APIs experimentais ou um SDK de pré-lançamento não é recomendado 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 a 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 o WebView2.

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

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

  • Observação somente para o .NET: em um SDK WebView2 de pré-lançamento, 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.

Correspondência da versão do Runtime com a versão do SDK

Na abordagem de distribuição 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, certifique-se de saber o número mínimo de compilação 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 Microsoft Edge WebView2 em developer.microsoft.com. A versão de tempo de execução mínima necessária para dar suporte à versão de disponibilidade geral do SDK (build 616) é mais antiga do que o tempo de execução 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 o Runtime ou o canal de visualização do Microsoft Edge, consulte as notas de versão do SDK do WebView2.

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

Se o aplicativo usar o Evergreen Runtime em vez da Versão Fixa, você deverá encapsular todas as chamadas para APIs WebView2 relativamente novas usando QueryInterface ou try-catch. Há casos extremos em que o Evergreen Runtime de um cliente não é a build mais recente e, portanto, fica atrás do número de build do SDK, porque o Administração pode ter suprimido temporariamente 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 o recurso" se essa API está presente no WebView2 Runtime instalado do cliente. A forma como seu aplicativo testa programaticamente o suporte à API depende da plataforma de codificação:

.NET, WinUI e WinRT

Use try/catch e marque se há uma No such interface supported exceção ao usar métodos, propriedades e eventos que foram adicionados às 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.

Win32 C/C++

Ao solicitar a exportação CreateCoreWebView2Environment da DLL e ao executar QueryInterface em qualquer CoreWebView2 objeto, teste um valor retornado de E_NOINTERFACE. Esse valor de retorno 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, encontre try_queryem AppWindow.cpp. Esse arquivo encapsula as CHECK_FAILURE chamadas de API WebView2 na função macro, definida no CheckFailure.h.

Forneça fallback normal

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

Confira também

Documentação do Microsoft Edge Enterprise:

Downloads:

GitHub:

  • Last updated on