Introdução ao WebView2 em aplicativos WinUI 3 (SDK do Aplicativo Windows)

  • Artigo

Este artigo aborda como configurar suas ferramentas de desenvolvimento e criar um aplicativo WebView2 inicial para WinUI 3 (SDK do Aplicativo Windows) e aprender sobre os conceitos do WebView2 ao longo do caminho.

Neste tutorial, você usa o modelo de projeto do Visual Studio do Aplicativo em Branco, Empacotado (WinUI na Área de Trabalho) para criar um projeto WinUI 3 em branco. Esse modelo de projeto usa o WindowsAppSDK, que inclui o SDK do WebView2. Você adiciona um controle WebView2. Em seguida, você adiciona uma barra de endereços e uma lógica para exibir uma caixa de diálogo de aviso quando o usuário tenta navegar até uma URL com um http:// prefixo.

Aplicativo que exibe o site do Bing

Projeto concluído

Uma versão concluída deste projeto tutorial (a partir de 2020) está disponível no repositório WebView2Samples :

  • Nome da amostra: WinUI3_GettingStarted
  • Diretório de repositório: WinUI3_GettingStarted
  • Arquivo da solução: WinUI_Sample.sln

O tutorial atual é atualizado e só cria um único projeto, não um segundo, projeto "(Pacote)", como em 2020.

Etapa 1 – Instalar o Visual Studio e o SDK do Aplicativo Windows

Mesmo que você tenha o Visual Studio instalado, leia a página a seguir e possivelmente atualize seu software e instale modelos de projeto.

  1. Em uma nova janela ou guia, abra a página Instalar ferramentas para o SDK do Aplicativo Windows e siga as etapas nessa página para instalar o Microsoft Visual Studio, como o Visual Studio 2022.
  1. Se necessário, em uma nova janela ou guia, consulte Instalar o Visual Studio em Configurar seu ambiente de desenvolvimento para WebView2.

Retorne dessa página e continue as etapas abaixo.

Para este exemplo, você não precisa instalar separadamente o SDK do WebView2. Abaixo, você selecionará o modelo de projeto Aplicativo em branco, Empacotado (WinUI na Área de Trabalho), que usa o WindowsAppSDK, que inclui o SDK do WebView2.

Etapa 2 – Instalar um canal de visualização do Microsoft Edge

  1. Instale o WebView2 Runtime em dispositivos que têm Windows 10 versão 1803 (build 17134) ou posterior, instalando de qualquer local:
  • Para baixar diretamente apenas o Runtime, use a seção Baixar o WebView2 Runtime da página WebView2 do Microsoft Edge em developer.microsoft.com.
  • Para baixar e instalar um canal de visualização do Microsoft Edge (Beta, Desenvolvimento ou Canário), acesse Tornar-se um Microsoft Edge Insider. Os canais de visualização também são chamados de canais insider. Os canais de visualização incluem o WebView2 Runtime.

Em seguida, continue com as etapas abaixo.

Etapa 3 – Create um projeto WinUI 3 em branco

Para criar um aplicativo WebView2, comece criando um projeto básico da área de trabalho para criar um aplicativo de área de trabalho que contenha uma única janela main:

  1. Se o Visual Studio não estiver em execução, inicie o Visual Studio (não Visual Studio Code). Na janela de inicialização do Visual Studio, clique no Create um novo projeto cartão. O Create abre uma nova janela de projeto.

    Ou, se o Visual Studio estiver em execução, selecione Arquivo>Novo>Projeto. A caixa de diálogo Create um novo projeto é aberta.

    Ativando o Modo de Desenvolvedor: Quando o Visual Studio for aberto em algum momento durante as etapas do artigo atual, você poderá ser solicitado a ativar o Modo de Desenvolvedor para seu computador. Para obter mais informações, se necessário, consulte Habilitar seu dispositivo para desenvolvimento, em Criar aplicativos de área de trabalho para Windows.

  2. Na caixa de diálogo Create um novo projeto, no campo Pesquisa para modelos, insiraWinUI 3 na Área de Trabalho:

    Pesquisar em

  3. Clique no aplicativo em branco, empacotado (WinUI na Área de Trabalho) cartão para selecioná-lo e clique no botão Avançar.

    Se os modelos WinUI não estiverem listados, você precisará instalar modelos de projeto conforme mencionado acima, em Instalar ferramentas para o SDK do Aplicativo Windows. Dicas adicionais para que o modelo seja exibido:

    Depois de instalar opções "padrão" para a edição community do Visual Studio 2022, em Instalador do Visual Studio, clique no cartão .NET e, à direita, selecione a caixa de seleção SDK do Aplicativo Windows Modelos C#.

    Se o modelo de projeto correto ainda não aparecer: no Instalador do Visual Studio, clique no cartão UWP para selecioná-lo, selecione a caixa de seleção de ferramentas C++ v143 à direita e clique no botão Modificar.

    A caixa de diálogo Configurar seu novo projeto é exibida.

  4. Na caixa de texto Nome do projeto , insira um nome de projeto, como MyWebView2WinUI3:

    A caixa de diálogo 'Configurar seu novo projeto'

  5. Na caixa de texto Local , insira ou navegue até um local, como C:\Users\username\Documents\WebView2.

  6. Clique no botão Create.

    O novo projeto WinUI 3 é aberto em Gerenciador de Soluções no Visual Studio:

    O novo projeto WinUI 3 no Gerenciador de Soluções

    • O App.xaml.cs arquivo define uma Application classe que representa a instância do aplicativo.

    • O MainWindow.xaml.cs arquivo define uma MainWindow classe que representa a janela main exibida pela instância do aplicativo. As classes derivam de tipos no Microsoft.UI.Xaml namespace do WinUI.

  7. Na lista suspensa Configurações da Solução (no meio da parte superior da janela), selecione Depurar.

  8. Na lista suspensa Plataformas de Solução , selecione uma plataforma, como x64.

  9. SelecioneSalvar todos osarquivos> (Ctrl+Shift+S) para salvar o projeto.

  10. Clique em F5 para compilar e executar o projeto. O aplicativo WinUI Desktop em branco é aberto, sem nenhum controle WebView2 adicionado ainda:

    O novo aplicativo WinUI 3 em branco

  11. Feche o aplicativo.

Atualizar números de versão de destino

Para a etapa de build acima: se você estiver atualizando um projeto anterior, talvez seja necessário atualizar os números de versão para a versão Target e a versão Mínima. Para fazer isso, em Solução clique com o botão direito do mouse no projeto e selecione Editar Arquivo de Projeto. Seu .csproj arquivo é aberto. Certifique-se de que os valores sejam atualizados da seguinte maneira e salve as alterações e crie o projeto.

    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>

Os valores acima representam:

  • Versão de destino: Windows 10, versão 2004 (build 19041) ou posterior.
  • Versão mínima: Windows 10, versão 1809 (build 17763).

Etapa 4 – Adicionar um controle WebView2

Este projeto tutorial baseia-se no modelo de projeto Aplicativo em branco, empacotado (WinUI na Área de Trabalho). Este modelo de projeto usa o WindowsAppSDK, que inclui o SDK do WebView2.

Edite os MainWindow.xaml arquivos e MainWindow.xaml.cs para adicionar um controle WebView2 ao projeto de aplicativo WinUI 3 em branco, da seguinte maneira:

  1. No Visual Studio, em Gerenciador de Soluções, clique MainWindow.xaml duas vezes para abri-lo no editor de código.

  2. Adicione o namespace XAML do WebView2 inserindo o seguinte atributo dentro da <Window> marca inicial:

    xmlns:controls="using:Microsoft.UI.Xaml.Controls"

    Verifique se o código em MainWindow.xaml é semelhante ao seguinte:

    <Window
    x:Class="MyWebView2WinUI3.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MyWebView2WinUI3"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">

    <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" VerticalAlignment="Center">
        <Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
    </StackPanel>
</Window>

  3. Para adicionar o controle WebView2, substitua todo <StackPanel> o elemento pelo código a seguir <Grid> . A Source propriedade, próxima à parte inferior, define o URI inicial exibido no controle WebView2 (https://www.microsoft.com):

    <Grid>

    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="Auto"/>
    </Grid.ColumnDefinitions>

    <controls:WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
        Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/>

</Grid>

  4. Em Gerenciador de Soluções, expanda MainWindow.xaml e abra MainWindow.xaml.cs.

  5. Em MainWindow.xaml.cs, comente a seguinte linha, conforme mostrado:

        // myButton.Content = "Clicked";

  6. SelecioneSalvar todos osarquivos> (Ctrl+Shift+S) para salvar o projeto.

  7. Pressione F5, para criar e executar o projeto.

  8. O aplicativo é um aplicativo host WebView2 que inclui o controle WebView2. O controle WebView2 exibe o site https://www.microsoft.com:

    O controle WebView2 que exibe a página da Web microsoft.com

  9. Feche o aplicativo.

O WinAppSDK dá suporte a ambientes WebView2 personalizados

O WinAppSDK dá suporte a ambientes WebView2 personalizados, começando com WinAppSDK 1.5 (1.5.0-experimental2). Para obter mais informações, consulte WinUI3 WebView2 com um CoreWebView2Environment personalizado.

Para instanciar um ambiente WebView2 personalizado, inicialize o WebView2 com uma das substituições de WebView2.EnsureCoreWebView2Async (listado abaixo) e passe seu personalizado CoreWebView2Environment (e, opcionalmente, personalizado CoreWebView2ControllerOptions):

public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment)
public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment, CoreWebView2ControllerOptions controllerOptions)

Veja também o código de exemplo em Desabilitar a navegação smartscreen, abaixo.

Referência de API:

Etapa 5 – Adicionar controles de navegação

Para permitir que os usuários controlem qual página da Web é exibida no controle WebView2, adicione uma barra de endereços ao aplicativo da seguinte maneira:

  1. No MainWindow.xaml, cole o seguinte código dentro do <Grid> elemento que contém o <controls:WebView2> elemento:

       <TextBox Name="addressBar" Grid.Column="0"/>
   <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>

    Verifique se o elemento resultante <Grid> no MainWindow.xaml arquivo corresponde ao seguinte:

    <Grid>

    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="Auto"/>
    </Grid.ColumnDefinitions>

    <TextBox Name="addressBar" Grid.Column="0"/>
    <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>

    <controls:WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
    Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/>

</Grid>

  2. Em MainWindow.xaml.cs, cole o código a seguir em myButton_Click, substituindo o método existente myButton_Click (que está quase vazio). Esse código navega pelo controle WebView2 até a URL inserida na barra de endereços.

    private void myButton_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Uri targetUri = new Uri(addressBar.Text);
        MyWebView.Source = targetUri;
    }
    catch (FormatException ex)
    {
        // Incorrect address entered.
    }
}

  3. SelecioneSalvar todos osarquivos> (Ctrl+Shift+S) para salvar o projeto.

  4. Clique em F5 para compilar e executar o projeto.

  5. Insira uma nova URL completa na barra de endereços, como https://www.bing.com, e clique no botão Ir .

    O controle WebView2 no aplicativo exibe o site do Bing. A barra de endereços exibe a URL, como https://www.bing.com:

    O aplicativo exibe o site do Bing

  6. Insira uma URL incompleta na barra de endereços, como bing.com, e clique no botão Ir .

    Uma ArgumentException exceção é gerada e aparece depois que você fecha o aplicativo, porque a URL não começa com http:// ou https://.

  7. Feche o aplicativo.

Etapa 6 – Eventos de navegação

Nesta seção, você adiciona código para importar a biblioteca Do WebView2 Core.

  1. Em MainWindow.xaml.cs, adicione a seguinte linha na parte superior, acima das outras using instruções:

    using Microsoft.Web.WebView2.Core;

    Os aplicativos que hospedam controles WebView2 escutam os seguintes eventos gerados pelos controles WebView2 durante a navegação na página da Web:

    • NavigationStarting
    • SourceChanged
    • ContentLoading
    • HistoryChanged
    • NavigationCompleted

    Se ocorrer um redirecionamento HTTP, haverá vários NavigationStarting eventos em uma linha.

    Para obter mais informações, confira Eventos de navegação para aplicativos WebView2.

    Quando ocorrem erros, os seguintes eventos são gerados e uma página da Web de erro pode ser exibida:

    • SourceChanged
    • ContentLoading
    • HistoryChanged

    Como exemplo de como usar os eventos, registre um manipulador para NavigationStarting o qual cancela quaisquer solicitações não HTTPS, da seguinte maneira:

  2. No MainWindow.xaml.cs, no construtor, adicione a seguinte NavigationStarting linha para registrar o EnsureHttps método:

    public MainWindow()
{
    this.InitializeComponent();
    MyWebView.NavigationStarting += EnsureHttps;
}

  3. No MainWindow.xaml.cs, abaixo do construtor, adicione o seguinte EnsureHttps método:

    private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args)
{
    String uri = args.Uri;
    if (!uri.StartsWith("https://"))
    {
        args.Cancel = true;
    }
    else
    {
        addressBar.Text = uri;
    }
}

  4. SelecioneSalvar todos osarquivos> (Ctrl+Shift+S) para salvar o projeto.

  5. Clique em F5 para compilar e executar o projeto.

  6. No aplicativo, na barra Endereço, insira uma URL HTTP, como http://bing.com, e clique no botão Ir .

    Nada acontece, porque a navegação está bloqueada para sites HTTP e ainda não adicionamos uma caixa de diálogo para fornecer comentários.

  7. Insira uma URL HTTPS, como https://bing.com, e clique no botão Ir .

    O aplicativo navega até a página especificada, pois a navegação é permitida para sites HTTPS.

  8. Feche o aplicativo.

Etapa 7 – Script

Você pode usar aplicativos host para injetar código JavaScript em controles WebView2 no runtime. Você pode tarefa WebView2 para executar JavaScript arbitrário ou adicionar scripts de inicialização. O JavaScript injetado se aplica a todos os novos documentos de nível superior e a todos os quadros filho até que o JavaScript seja removido. O JavaScript injetado é executado com um tempo específico para:

  • Execute o JavaScript injetado após a criação do objeto global.

  • Execute o JavaScript injetado antes de executar qualquer outro script incluído no documento HTML.

Como exemplo, em seguida, você adiciona scripts que enviam um alerta quando um usuário tenta abrir sites que não são HTTPS. Para fazer isso, você injeta um script no conteúdo da Web que usa ExecuteScriptAsync.

  1. EnsureHttps No método, adicione a seguinte ExecuteScriptAsync linha:

    private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args)
{
    String uri = args.Uri;
    if (!uri.StartsWith("https://"))
    {
        MyWebView.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
        args.Cancel = true;
    }
    else
    {
        addressBar.Text = uri;
    }
}

  2. SelecioneSalvar todos osarquivos> (Ctrl+Shift+S) para salvar o projeto.

  3. Clique em F5 para compilar e executar o projeto.

  4. Na barra de endereços do aplicativo, insira uma URL não HTTPS, como http://www.bing.com, e clique no botão Ir .

    O controle WebView2 do aplicativo exibe uma caixa de diálogo de alerta para sites que não são HTTPS, dizendo que o não HTTPS uri não é seguro:

    O controle WebView2 do aplicativo exibe uma caixa de diálogo de alerta para sites que não são HTTPS

  5. Feche o aplicativo.

Parabéns, você criou seu primeiro aplicativo WebView2!

Considerações especiais do WinUI 3 WebView2

Desabilitar a navegação smartscreen

O WebView2 envia URLs que são navegadas em seu aplicativo para o serviço SmartScreen , para garantir que seus clientes permaneçam seguros. Se você quiser desabilitar essa navegação, use um , personalizado CoreWebView2Environment, da seguinte maneira:

CoreWebView2EnvironmentOptions environmentOptions = new CoreWebView2EnvironmentOptions();
environmentOptions.AdditionalBrowserArguments = "--disable-features=msSmartScreenProtection";

string browserFolder = null; // Use null to get default browser folder
string userDataFolder = null; // Use null to get default user data folder
CoreWebView2Environment environment = await CoreWebView2Environment.CreateWithOptionsAsync(
    browserFolder, userDataFolder, environmentOptions);

// ...

this.WebView2.EnsureCoreWebView2Async(environment);
Desabilitar o SmartScreen usando uma variável de ambiente

Não recomendamos mais usar uma variável de ambiente. Use a abordagem baseada em código da API acima.

  • Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");

Essa variável de ambiente deve ser definida antes da CoreWebView2 criação, que ocorre quando a propriedade WebView2.Source é inicialmente definida ou o método WebView2.EnsureCoreWebView2Async é inicialmente chamado.

Configuração DefaultBackgroundColor

No WebView2 para WinUI 3, a DefaultBackgroundColor configuração existe no objeto XAML do WebView2. Por exemplo:

public MainWindow()
{
    this.InitializeComponent();
    MyWebView.DefaultBackgroundColor = Colors.LightBlue;
}

Transparência

O WinUI 3 não dá suporte a planos de fundo transparentes. Consulte Suporte transparente em segundo plano para WebView2? · Problema nº 2992.

Suporte do WinAppSDK para ambientes personalizados do WebView2

Consulte WinAppSDK dá suporte a ambientes WebView2 personalizados, acima.

Confira também

developer.microsoft.com:

Github: