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

Este artigo é para aprender a escrever seu próprio código WebView2. Se você quiser executar um exemplo primeiro, consulte o aplicativo de exemplo Win32 ou outro artigo de aplicativo de exemplo, como o aplicativo de exemplo WinUI 3 (SDK do Windows App).

Este artigo aborda como configurar suas ferramentas de desenvolvimento e criar um aplicativo WebView2 inicial para WinUI 3 (SDK do Windows App) e aprender sobre os conceitos do WebView2 ao longo do caminho. Primeiro, você usa o modelo de projeto Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho), que usa o WindowsAppSDK, que inclui o SDK do WebView2. Em seguida, adicione um controle WebView2, uma barra de endereços e um botão Ir e lógica de URL para permitir apenas a navegação para URLs HTTPS.

Neste tutorial, faça o seguinte:

Configure o ambiente de desenvolvimento.
Use o modelo de projeto do Visual Studio Aplicativo em branco, empacotado (WinUI 3 na área de trabalho) para criar um projeto WinUI 3 em branco, que define um aplicativo que contém um botão.
Adicione um controle WebView2 em vez do botão e, inicialmente, navegue até a página inicial da Microsoft. O WebView2 é suportado porque o modelo de projeto usa o pacote NuGet Microsoft.WindowsAppSDK , que inclui o SDK do WebView2.
Adicione uma barra de endereços como um controle de caixa de texto e use a cadeia de caracteres HTTPS inserida para navegar para uma nova página da Web:
Insira o JavaScript no controle WebView2, para exibir um alerta de aviso (diálogo) quando o usuário tentar navegar para uma URL que tenha apenas um http:// prefixo em vez de https://:

Projeto concluído

Uma versão completa deste projeto de tutorial está disponível no repositório WebView2Samples :

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

Etapa 1: Instalar o Visual Studio 2022 mais recente

Verifique se o Visual Studio 2022 está instalado e atualizado.

Para instalar o Visual Studio 2022 mais recente:

Vá para Visual Studio: IDE e Editor de código para desenvolvedores de software e equipes e, na seção Visual Studio 2022 , clique no botão Baixar e selecione Comunidade 2022 ou outra versão.
No pop-up de downloads no canto superior direito do Microsoft Edge, VisualStudioSetup.exe está listado. Clique em Abrir arquivo.

O Visual Studio Installer é aberto.
Siga as instruções e aceite os padrões. Você instalará ou atualizará uma carga de trabalho e um componente de uma carga de trabalho na próxima etapa.

Etapa 2: Instalar o SDK do Windows App mais recente

Verifique se o SDK do Windows App mais recente está instalado no Visual Studio 2022. O SDK do Windows App inclui modelos de projeto do Visual Studio e inclui o SDK do WebView2. Esses modelos de projeto incluem o modelo de projeto Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho), que usa o WindowsAppSDK, incluindo o SDK do WebView2.

O SDK do Windows App é instalado como o componente Modelos C# do SDK do Aplicativo Windows App da carga de trabalho de Desenvolvimento da Área de Trabalho do .NET para Visual Studio. Antes do Visual Studio 2022 versão 17.1, o SDK do Windows App foi instalado como uma extensão do Visual Studio, conforme explicado em Instalar ferramentas para o SDK do Windows App.

Para instalar o Visual Studio 2022 mais recente, o SDK do Windows App mais recente:

No Windows, pressione a tecla Iniciar e digite Visual Studio 2022.

O aplicativo Visual Studio 2022 está listado.
Clique em Abrir.

A caixa de diálogo do Visual Studio 2022 é aberta, com seções incluindo Abrir recente e Começar.
Clique em Continuar sem código.

O Visual Studio é aberto.
No menu Ferramentas , selecione Obter Ferramentas e Recursos.

A janela do Visual Studio Installer é aberta.
Verifique se a guia Cargas de trabalho está selecionada.
Na seção Desktop & Mobile, selecione o card para a carga de trabalho de desenvolvimento da área de trabalho do .NET, para que seja exibida uma marca de seleção:
Na árvore de detalhes da instalação à direita, no .NET Desktop Development>Opcional, marque a caixa de seleção do componente Modelos C# do SDK do Windows App, próximo à parte inferior da árvore.
Clique no botão Modificar .

A caixa de diálogo Controle de Conta de Usuário é aberta.
Clique no botão Sim .

Você é solicitado a fechar o Visual Studio.
Clique no botão Continuar (supondo que você não tenha nenhum trabalho não salvo).

O Visual Studio baixa e instala o componente de Modelos C# do SDK do Windows App mais recente. Na janela do Visual Studio Installer, uma mensagem diz Todas as instalações estão atualizadas e o Visual Studio 2022 é aberto.

Etapa 3: Criar um projeto WinUI 3 em branco

Em seguida, crie um projeto que seja um aplicativo WebView2 básico para WinUI 3 (SDK do Aplicativo Windows App). Esse aplicativo da área de trabalho conterá uma única janela principal. O projeto ainda não conterá nenhum código WebView2.

Para criar um aplicativo WebView2 para WinUI 3 (SDK do Windows App):

Se o Visual Studio estiver em execução, selecione Arquivo>Novo>Projeto. A caixa de diálogo Criar um novo projeto é aberta.
Se o Visual Studio 2022 não estiver em execução:
1. No Windows, pressione a tecla Iniciar e digite Visual Studio 2022.
  
  O aplicativo Visual Studio 2022 está listado.
2. Clique em Abrir.
  
  A caixa de diálogo de inicialização do Visual Studio 2022 é aberta, com seções incluindo Abrir recente e Começar.
3. Na seção Introdução, clique no card Criar um novo projeto. A janela Criar um novo projeto é aberta.
Na janela Criar um novo projeto , no campo Search for templates , insira WinUI 3 in Desktop:

Os modelos de projeto que foram instalados na etapa principal anterior são listados.
Clique no card Aplicativo em branco, empacotado (WinUI 3 na área de trabalho) para selecioná-lo e clique no botão Avançar.

A caixa de diálogo Configurar seu novo projeto é exibida.
Na caixa de texto Nome do projeto , insira um nome de projeto, como WinUI3GetStarted:
Na caixa de texto Local , digite ou navegue até um diretório, como C:\Users\myUsername\source\.
Clique no botão Criar .

O projeto é criado:

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

Se uma caixa de diálogo aparecer dizendo "Falha ao instalar o pacote Microsoft.WindowsAppSDK", clique no botão OK .

Etapa 4: Atualizar ou instalar o SDK do Windows App

Ao criar um novo projeto no Visual Studio, marcar o status dos pacotes NuGet da solução. Certifique-se de que os pacotes NuGet necessários foram instalados pelo modelo de projeto e certifique-se de que os pacotes foram atualizados, para que o projeto tenha os recursos e as correções mais recentes.

Para atualizar ou instalar o pacote NuGet SDK do Windows App mais recente para seu projeto:

No Visual Studio, no Gerenciador de Soluções, clique com o botão direito do mouse no projeto WinUI3GetStarted e selecione Gerenciar Pacotes NuGet.

No Visual Studio, a guia NuGet: WinUI3GetStarted é aberta. Se o pacote Microsoft.WindowsAppSDK tiver sido instalado durante a criação do projeto usando o modelo de projeto, a guia Instalado será selecionada e esse pacote será listado:

Se o pacote Microsoft.WindowsAppSDK não estiver listado na guia Instalado :
Clique na guia Procurar e, na caixa de texto Pesquisar , digite Microsoft.WindowsAppSDK.
Selecione o card Microsoft.WindowsAppSDK:
Clique no botão Instalar , à direita.

A caixa de diálogo Visualizar Alterações é aberta.
Clique no botão Aplicar e aceite os termos de licença.

O pacote NuGet Microsoft.WindowsAppSDK está instalado.
Na guia NuGet \u2012 Solução, clique na guia Atualizações e, opcionalmente, atualize todos os pacotes listados lá.
Feche a guia NuGet – Solução .

Etapa 5: compilar e executar o projeto

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

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

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

Para compilar e executar o projeto:

Selecione Arquivo>, Salvar Tudo (Ctrl+Shift+S).
Selecione Depurar Início> (F5).

A caixa de diálogo Habilitar Modo de Desenvolvedor para Windows pode ser aberta:
Se essa caixa de diálogo for exibida, clique em configurações para desenvolvedores, ative a alternância do Modo de Desenvolvedor , clique no botão Sim e, em seguida, clique no botão Fechar da caixa de diálogo do Visual Studio. Para obter mais informações sobre o Modo de Desenvolvedor, consulte Habilitar seu dispositivo para desenvolvimento, em Criar aplicativos da área de trabalho para Windows.

O projeto é compilado. O aplicativo da área de trabalho WinUI em branco é aberto, sem nenhum controle WebView2 adicionado ainda:
Clique no botão Clique em Mim .

O rótulo do botão muda para Clicado.
Feche o aplicativo.

Etapa 6: Adicionar um controle WebView2

O projeto é baseado no modelo de projeto Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho), que usa o pacote NuGet Microsoft.WindowsAppSDK , que inclui o SDK do WebView2. Assim, podemos adicionar código WebView2. Você editará os MainWindow.xaml arquivos and MainWindow.xaml.cs para adicionar um controle WebView2 ao projeto em branco do aplicativo WinUI 3, carregando inicialmente a página inicial da Microsoft. No arquivo XAML, o controle WebView será marcado como:

<controls:WebView2 x:Name="MyWebView" Source="https://www.microsoft.com">

Para adicionar um controle WebView2 que navegue inicialmente para a página inicial da Microsoft:

No Visual Studio, no Gerenciador de Soluções, clique duas vezes em MainWindow.xaml.

O arquivo é aberto no editor de código.

Copie e cole o seguinte atributo dentro da <Window> tag start, no final da lista de namespaces XML:

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

Esse código adiciona o namespace XAML WebView2. Verifique se o código MainWindow.xaml é semelhante ao seguinte:

<?xml version="1.0" encoding="utf-8"?>
<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"
    xmlns:controls="using:Microsoft.UI.Xaml.Controls"
    mc:Ignorable="d">

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

Exclua o <StackPanel> elemento (três linhas).

Acima da </Window> tag final, cole o seguinte <Grid> elemento:

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

Esse <Grid> elemento contém um <controls:WebView2> elemento chamado MyWebView, que tem um Source atributo que define o URI inicial exibido no controle WebView2 (https://www.microsoft.com). Quando o aplicativo for aberto, ele exibirá inicialmente a página inicial Microsoft.com, no controle WebView2.

No Gerenciador de Soluções, expanda MainWindow.xaml e clique duas vezes em MainWindow.xaml.cs.
Em MainWindow.xaml.cs, exclua a seguinte linha de código C# no myButton_Click método:
```
myButton.Content = "Clicked";
```
O método está vazio por enquanto. Vamos usá-lo para o botão Ir da barra de endereços mais tarde.
Selecione Arquivo>, Salvar Tudo (Ctrl+Shift+S).
Pressione F5.

O projeto é compilado e o aplicativo é aberto:

O aplicativo é um aplicativo host WebView2 que inclui o controle WebView2. O controle WebView2 exibe inicialmente o site https://www.microsoft.com. Ainda não há barra de endereços, caixa de texto ou botão Ir .
Feche o aplicativo.

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:

Em MainWindow.xaml, cole o seguinte código dentro do <Grid> elemento, acima do <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 arquivo corresponde ao MainWindow.xaml 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>

Em MainWindow.xaml.cs, cole o seguinte try/catch bloco no corpo do myButton_Click método:
```
private void myButton_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Uri targetUri = new Uri(addressBar.Text);
        MyWebView.Source = targetUri;
    }
    catch (FormatException ex)
    {
        // Incorrect address entered.
    }
}
```
Esse código navega pelo controle WebView2 até a URL que o usuário insere na barra de endereços, quando o usuário clica no botão Ir , redefinindo o valor da MyWebView.Source propriedade, que é equivalente ao Source atributo do <controls:WebView2 x:Name="MyWebView"> elemento.
Selecione Arquivo>, Salvar Tudo (Ctrl+Shift+S).
Pressione F5.

O projeto é compilado e o aplicativo é aberto, mostrando inicialmente a página inicial da Microsoft. Agora há uma barra de endereços e um botão Ir .
Insira uma nova URL HTTPS 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.
Digite uma URL incompleta na barra de endereços, como bing.com, e clique no botão Ir .

O controle WebView2 não tenta navegar até essa URL. Uma exceção é lançada, porque a URL não começa com http:// ou https://. Na seção, a tryaddressBar.Text string não começa com http:// ou https://, mas a string não URI é passada para o Uri construtor, que gera uma System.UriFormatException exceção. No Visual Studio, o painel Saída exibe "Exceção lançada: 'System.UriFormatException' no System.Private.Uri.dll". O aplicativo continua em execução.
Feche o aplicativo.

Um aplicativo que hospeda um controle WebView2 escuta os seguintes eventos:

NavigationStarting
SourceChanged
ContentLoading
HistoryChanged
NavigationCompleted

Esses eventos são gerados por um controle WebView2 durante a navegação na página da Web. Se ocorrer um redirecionamento HTTP, haverá vários NavigationStarting eventos seguidos. Para obter mais informações, consulte Eventos de navegação para aplicativos WebView2.

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

SourceChanged
ContentLoading
HistoryChanged

Nesta seção, você adiciona código para importar a biblioteca do WebView2 Core, que manipula eventos de navegação para ir para vários tipos de URLs.

Para lidar com eventos de navegação:

Em MainWindow.xaml.cs, adicione a seguinte linha na parte superior, acima das outras using instruções:
```
using Microsoft.Web.WebView2.Core;
```
Registre um manipulador para NavigationStarting cancelar todas as solicitações não HTTPS:
Em MainWindow.xaml.cs, no construtor, adicione a seguinte NavigationStarting linha:
```
public MainWindow()
{
    this.InitializeComponent();
    MyWebView.NavigationStarting += EnsureHttps;
}
```
Essa linha registra o EnsureHttps método (adicionado abaixo) como um ouvinte do NavigationStarting evento.

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;
    }
}

Selecione Arquivo>, Salvar Tudo (Ctrl+Shift+S).
Pressione F5.

O projeto é compilado e o aplicativo é aberto.
No aplicativo, na barra de endereços, insira uma URL HTTP, como http://bing.com, e clique no botão Ir .

O aplicativo não navega até essa página, pois a navegação é bloqueada para sites HTTP. Ainda não adicionamos uma caixa de diálogo para informar ao usuário por que o site exibido não foi alterado.
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.
No aplicativo, na barra de endereços, insira uma cadeia de caracteres sem prefixo, como bing.com, e clique no botão Ir .

O aplicativo não navega até essa página. Uma UriFormatException exceção é lançada, como antes, e aparece no painel Saída no Visual Studio.
Feche o aplicativo.

Etapa 9: inserir JavaScript para alertar o usuário sobre um endereço não HTTPS

Você pode usar o aplicativo host para injetar código JavaScript no controle WebView2 em tempo de execução. Você pode encarregar o WebView2 de 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.

Abaixo, você adiciona JavaScript que exibe um alerta quando um usuário tenta abrir um site não HTTPS. Para fazer isso, você injeta um script no conteúdo da Web que usa ExecuteScriptAsync.

Para exibir um alerta quando o usuário tentar navegar para um site não HTTPS:

Em MainWindow.xaml.cs, no EnsureHttps 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;
    }
}

Selecione Arquivo>, Salvar Tudo (Ctrl+Shift+S).
Pressione F5.

O projeto é compilado e o aplicativo é aberto.
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 não HTTPS, informando que o não HTTPS uri não é seguro:
Feche o aplicativo.

Parabéns, você criou um aplicativo WebView2 WinUI 3 (SDK do Windows App)!

Confira também

Referência da API WebView2
Introdução ao Microsoft Edge WebView2 - visão geral dos recursos.
Gerenciar pastas de dados do usuário
Aplicativos de exemplo WebView2 : um guia para o WebView2Samples repositório.
Práticas recomendadas de desenvolvimento para aplicativos WebView2 Práticas recomendadas de desenvolvimento

developer.microsoft.com:

Microsoft Edge WebView2 - introdução inicial aos recursos do WebView2.

GitHub:

Introdução ao WebView2 no WinUI3
Especificação: o controle Xaml do WebView2 - a versão WinUI 3.0 do controle WebView2.
Repositório Microsoft-UI-XAML > Problemas - para inserir solicitações de recursos ou bugs específicos do WinUI.

Comentários

Esta página foi útil?

Last updated on 2026-08-24