Compartilhar via

Pré-lançamento e SDKs de Versão para WebView2

  • Artigo

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

Pré-lançamento Os pacotes SDK são utilizados durante o desenvolvimento se quiser testar as APIs WebView2 mais recentes, incluindo as APIs Experimentais, antes de o suporte para essas APIs ser adicionado ao Runtime. O canal Canary é recomendado porque tem as implementações das APIs mais recentes. Quando quiser testar e utilizar APIs WebView2 Experimentais, utilize a seguinte combinação:

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

Versão Os pacotes SDK contêm apenas APIs Estáveis e não APIs Experimentais. Quando estiver a trabalhar numa versão de produção da sua aplicação WebView2, utilize a seguinte combinação:

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

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

Fases de introdução de APIs

As novas APIs são introduzidas por fases da seguinte forma:

Estado da API Descrição
Experimental 1. Primeiro, uma API é Experimental num SDK de Pré-lançamento. Pode testar estas APIs e fornecer feedback. A API ainda não está num SDK de Versão.
Estável num 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á num SDK de Versão.
Estável num SDK de Versão 3. Em seguida, a API Estável é promovida para ser incluída no SDK de Versão. Normalmente, isto ocorre 1 mês após a API ser promovida para Estável num SDK de Pré-lançamento. A API também permanece no SDK de Pré-lançamento.

Diagrama de fases de introdução de novas APIs

Selecionar o tipo de SDK a utilizar

Para selecionar a versão do Pacote NuGet do SDK WebView2 que um projeto do Visual Studio utiliza, no Visual Studio, clique com o botão direito do rato num projeto, selecione Gerir Pacotes NuGet, selecione ou desmarque a caixa de verificação Incluir pré-lançamento , selecione o pacote Microsoft.Web.WebView2 e, em seguida, na lista pendente Versão , selecione uma versão do pacote NuGet Microsoft.Web.WebView2 .

Para obter detalhes, consulte Instalar ou atualizar o SDK WebView2 em Configurar o ambiente Dev para WebView2. Também pode ver a lista de pacotes SDK Microsoft.Web.WebView2 no site NuGet.

Utilizar uma versão de Pré-lançamento do SDK juntamente com um canal de pré-visualização do Microsoft Edge

Ao desenvolver uma aplicação Evergreen WebView2, teste regularmente a aplicação relativamente ao canal de pré-visualização mais recente do Microsoft Edge, além de testar no Runtime WebView2. Uma vez que a plataforma Web está em constante evolução, os testes regulares são a melhor forma de garantir que a sua aplicação continuará a funcionar conforme pretendido.

Quando utiliza um pacote SDK WebView2 Pré-lançamento , utilize um canal de pré-visualização do Microsoft Edge no seu cliente de desenvolvimento. Os canais de pré-visualização também são denominados canais insiders . O canal de pré-visualização Canary é recomendado em vez de Beta ou Dev, porque 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 já não são Experimentais, mas ainda não foram incluídas num SDK de Versão.
  • APIs estáveis que foram adicionadas aos SDKs de Versão.

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

Para obter informações sobre como apontar temporariamente a sua aplicação para um canal de pré-visualização em vez de predefinir o Runtime do WebView2, veja Testar as próximas APIs e funcionalidades.

Veja também:

Utilizar uma versão de versão do SDK juntamente com o Runtime

Quando utiliza um pacote do SDK de Versão webView2, utilize o Runtime Do Evergreen WebView2 no seu cliente de desenvolvimento, em vez de um canal de pré-visualização do Microsoft Edge. Por predefinição, uma aplicação WebView2 destina-se ao Runtime em vez do Microsoft Edge. Por predefinição, o canal Microsoft Edge Stable não suporta WebView2.

O pacote do 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 num pacote do SDK de Versão são totalmente suportadas, num número de compilação igual ou superior do Runtime webView2.

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

Para obter mais informações sobre a atualização automática do Evergreen Runtime, consulte Distribuir a sua aplicação e o WebView2 Runtime.

Cadência de lançamento

As novas versões do SDK WebView2 são enviadas com a mesma cadência geral do browser Microsoft Edge, que é aproximadamente de quatro em quatro semanas.

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

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

Num computador de desenvolvimento, o cliente tem de ter a versão 86.0.616.0 ou superior do canal de pré-visualização do Microsoft Edge ou a versão 86.0.616.0 ou superior do WebView2 Runtime.

Reencaminhar compatibilidade de APIs

O SDK de versão webView2 tem sido compatível com o futuro desde a versão 1 (SDK de Versão 1.0.622.22 em Notas de Versão Arquivadas para o SDK WebView2). Pode atualizar a sua aplicação WebView2 para utilizar as APIs mais recentes da versão de Versão mais recente do SDK. A sua aplicação continuará a funcionar nos clientes porque os clientes têm automaticamente o Runtime WebView2 mais recente do Evergreen.

As APIs WebView2 num pacote do SDK de Versão são estáveis e compatíveis com o reencaminhamento. Uma API WebView2 funciona ao utilizar um WebView2 Runtime que tem um número de compilação igual ou superior como o 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 da versão de quatro partes para o SDK Webview2 e o número da versão de quatro partes para o Microsoft Edge e o WebView2 Runtime.

  • Quando utiliza um SDK WebView2 que tem um número de compilação igual ou inferior ao Runtime webView2, cada API a que tem acesso nesse SDK funciona com essa versão do Runtime.

  • Quando utiliza um SDK WebView2 com um número de compilação superior ao Runtime do WebView2, 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.

Tem de coordenar a versão do SDK WebView2 que utiliza para desenvolvimento e a versão do WebView2 Runtime instalada em computadores cliente. O cliente deve ter uma versão do Runtime que suporte todas as APIs mais recentes que estão na versão do SDK que utiliza para desenvolver a aplicação. Para obter suporte total para as APIs mais recentes numa versão de versão do SDK, o Runtime no cliente tem de ter um número de compilação maior ou igual ao número de compilação do SDK.

APIs experimentais

Para experimentar as novas funcionalidades futuras que estão em desenvolvimento, utilize as APIs Experimentais . As APIs experimentais estão contidas em SDKs de Pré-lançamento, mas não em SDKs de Versão.

Programar com APIs Experimentais e fornecer comentários

As APIs Experimentais num pacote SDK WebView2 Pré-lançamento não têm a garantia de serem compatíveis com o futuro e poderão ser removidas em futuras atualizações do Runtime.

Para obter suporte total das APIs Experimentais, utilize um canal de pré-visualização do Microsoft Edge e não o Evergreen WebView2 Runtime. Quando uma versão de Pré-lançamento do SDK WebView2 é inicialmente disponibilizada, esse SDK só funciona com o Microsoft Edge Canary. Pouco tempo depois, o SDK de Pré-lançamento também funciona com os canais Beta e Dev.

Utilize um SDK de Pré-lançamento para experimentar as APIs experimentais novas mais cedo e fornecer feedback antes de as APIs Experimentais serem promovidas para se tornarem APIs estáveis e compatíveis com o futuro.

  • As APIs Experimentais (num SDK de Pré-lançamento) não são garantidas como compatíveis com o futuro.
  • As APIs Estáveis que estão num SDK de Pré-lançamento são compatíveis com o reencaminhamento, mesmo que ainda não estejam incluídas num SDK de Versão.
  • As APIs Estáveis que estão num SDK de Versão são compatíveis com o reencaminhamento.

Para obter mais informações, veja Reencaminhar compatibilidade de APIs acima.

A equipa do WebView2 está à procura de comentários sobre APIs WebView2 Experimentais 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 WebView2, como: "Nota: esta é uma API experimental que é enviada com o nosso SDK de pré-lançamento.".

Para o ajudar a avaliar as APIs Experimentais e a partilhar os seus comentários, utilize o repositório WebView2Feedback .

Passar de APIs Experimentais para APIs Estáveis

Assim que uma API tiver sido movida do estado Experimental para Estável, tem de mover o código da sua aplicação para a API Estável. A utilização de APIs Experimentais ou de um SDK de Pré-lançamento não é recomendada para aplicações de produção. Siga estas práticas ao mover a sua aplicação da utilização de APIs Experimentais para utilizar APIs Estáveis:

  • No seu projeto no Visual Studio, atualize a versão do pacote do SDK WebView2 para um SDK de Pré-lançamento ou SDK de Versão mais recente. Consulte Instalar ou atualizar o SDK WebView2 em Configurar o ambiente de Programador para WebView2.

  • Atualize o código da aplicação para utilizar APIs Estáveis em vez de APIs Experimentais (para COM). A API Estável será suportada com correções de erros, mas a API Experimental será preterida e não estará disponível no SDK mais recente (Pré-lançamento ou Versão). Depois de uma API ser promovida para Estável, a versão experimental dessa API é suportada para duas versões do SDK de Pré-lançamento, num estado preterido. Nas versões subsequentes do SDK de Pré-lançamento, as APIs Experimentais podem ser modificadas, removidas ou adicionadas.

  • Utilize sempre a deteção de funcionalidades para garantir que a API Estável é implementada na versão do utilizador do WebView2 Runtime. Veja Deteção de funcionalidades para testar se o Runtime instalado suporta APIs adicionadas recentemente, abaixo.

  • Nota apenas para .NET: num SDK WebView2 de Pré-lançamento, as APIs Estáveis .NET reverterão para as APIs Experimentais correspondentes, se o WebView2 Runtime do utilizador tiver apenas a implementação da API Experimental e não tiver a implementação da API Estável.

Corresponder a versão do Runtime à 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 utilizador 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 a aplicação WebView2 atualizada que utiliza novas APIs de um SDK recente.

Caso a atualização do Runtime webView2 seja impedida no cliente, certifique-se de que sabe o número mínimo de compilação do Runtime WebView2 que é necessário para a sua aplicação. Para ver ou obter as versões mais recentes do WebView2 Runtime, consulte Transferir o WebView2 Runtime na página WebView2 do Microsoft Edge em developer.microsoft.com. A versão mínima necessária do Runtime para suportar a versão de Disponibilidade Geral do SDK (compilação 616) é mais antiga do que para o Runtime mais recente. O Runtime mais recente suporta todas as APIs que estão no SDK de Versão mais recente.

Para verificar a compatibilidade entre os números de compilação específicos do SDK e o canal de pré-visualização do Runtime ou do Microsoft Edge, veja Notas de Versão do SDK WebView2.

Deteção de funcionalidades para testar se o Runtime instalado suporta APIs adicionadas recentemente

Se a sua aplicação utilizar o Evergreen Runtime em vez da Versão Fixa, deve encapsular quaisquer chamadas para APIs WebView2 relativamente novas com QueryInterface ou try-catch. Existem casos extremos em que o Evergreen Runtime de um cliente não é a compilação mais recente e, por conseguinte, fica atrás do número de compilação do SDK, porque o Administrador pode ter desativado a atualização do Runtime do WebView2 ou o cliente pode estar offline.

Quando desenvolve uma aplicação WebView2 com uma versão recente do SDK WebView2, se utilizar uma API adicionada recentemente, deve testar ou "detetar funcionalidades" se essa API está presente no WebView2 Runtime instalado do cliente. A forma como a sua aplicação testa programaticamente o suporte da API depende da plataforma de codificação.

  • Win32 C/C++. Ao pedir a exportação CreateCoreWebView2Environment de DLL e ao executar QueryInterface em qualquer CoreWebView2 objeto, teste para obter um valor devolvido de E_NOINTERFACE. Esse valor devolvido indica provavelmente que o Runtime WebView2 do cliente é uma versão mais antiga que não suporta 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 ficheiro encapsula as chamadas à API WebView2 na CHECK_FAILURE função de macro, definidas em CheckFailure.h.

  • .NET e WinUI. Utilize try/catch e verifique se existe uma No such interface supported exceção ao utilizar métodos, propriedades e eventos que foram adicionados a versões mais recentes do SDK WebView2. Esta exceção indica provavelmente que o WebView2 Runtime do cliente é uma versão mais antiga que não suporta essa API.

Se o código determinar que uma API está indisponível no WebView2 Runtime instalado do cliente, deve fornecer uma contingência correta para a funcionalidade associada ou informar o utilizador de que tem de atualizar o Runtime do WebView2 para utilizar a funcionalidade.