Introdução ao WebView2 em aplicativos WPF

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

Este artigo aborda como configurar suas ferramentas de desenvolvimento e criar um aplicativo WebView2 inicial para o Windows Presentation Foundation (WPF) e aprender sobre os conceitos do WebView2 ao longo do caminho.

Neste tutorial, use o modelo de projeto Aplicativo WPF ou Aplicativo WPF (.NET Framework) para criar um aplicativo WPF e, em seguida, instale o SDK do WebView2 para que o projeto adicione o WebView2.

Projeto concluído

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

Nome de exemplo: WPF_GettingStarted
Diretório de repositório: WPF_GettingStarted
Arquivo da solução: WPFSample.sln

Etapa 1 - Instalar o Visual Studio com suporte do .NET

Este tutorial requer o Microsoft Visual Studio, e não o Microsoft Visual Studio Visual Studio Code. Este artigo descreve principalmente o uso do Visual Studio 2022.

Instale o Visual Studio. Instale o suporte de desenvolvimento de área de trabalho do .NET para obter os modelos de projeto necessários, da seguinte maneira.
Se você estiver na tela de inicialização do Visual Studio, role até a parte inferior da caixa de diálogo Criar um novo projeto e clique no link Abrir sem código. O Visual Studio é aberto.
No Visual Studio, selecione Ferramentas>Obter Ferramentas e Recursos. A janela do Visual Studio Installer é aberta e a caixa de diálogo Modificando é aberta sobre ela.
Selecione a carga de trabalho de desenvolvimento da área de trabalho do .NET para que haja uma marca de seleção nela.
Na seção Detalhes da instalação.NET>desktop development>Incluído à direita, verifique se as ferramentas de desenvolvimento de área de trabalho .NET e as ferramentas de desenvolvimento do .NET Framework 4.7.2 estão listadas, com uma marca de seleção ao lado delas.
Na seção Detalhes da instalação.NET>desktop development>Opcional à direita:
- Se você estiver usando o Visual Studio 2022, verifique se Ferramentas de desenvolvimento para .NET está selecionado:
- Se você estiver usando o Visual Studio 2019, verifique se as ferramentas de desenvolvimento do .NET estão selecionadas:
Clique no botão Modificar .

Este tutorial também funciona com o Visual Studio 2017. Consulte Downloads mais antigos do Visual Studio. Instale o suporte ao .NET para obter os modelos de projeto necessários, semelhantes às etapas acima.

Etapa 2 - Criar um aplicativo WebView2 de janela única

Comece criando um projeto básico da área de trabalho que contenha uma única janela principal.

Decida se deseja criar um projeto .NET Core/5/6 (mais recente) ou um projeto de aplicativo WPF (.NET Framework) (mais antigo). Para saber mais, confira:
- História do .NET em O que é .NET? Introdução e visão geral.
- .NET na Wikipedia.
Siga a seção aplicável abaixo.

Criando um projeto .NET Core/5/6

Se você estiver criando um projeto .NET Core/5/6, execute as etapas a seguir. Caso contrário, vá para Criando um projeto de aplicativo WPF (.NET Framework).

Abra o Microsoft Visual Studio, como o Visual Studio 2022.
No painel de abertura, clique em Criar novo projeto. Ou, na janela principal do Visual Studio, selecione Arquivo>Novo>Projeto. A caixa de diálogo Criar um novo projeto é aberta.
Na caixa de texto Pesquisar modelos , digite WPF Application. O painel Criar um novo projeto mostra os modelos de projeto instalados que correspondem ao texto inserido. Este artigo mostra as caixas de diálogo C# em vez de VB; ambos os idiomas são compatíveis com o WebView2.
Se você estiver usando o Visual Studio 2022, clique em um modelo de projeto que tenha o título Aplicativo WPF e o texto de descrição Um projeto para criar um aplicativo .NET WPF:

Se você estiver usando o Visual Studio 2019, clique em um modelo de projeto que tenha o título Aplicativo WPF e o texto de descrição Um projeto para criar um Aplicativo WPF do .NET Core:

Se o modelo de projeto acima não estiver listado, consulte Etapa 1 – Instalar o Visual Studio com suporte do .NET acima para instalar as ferramentas de desenvolvimento da área de trabalho do .NET.
Clique no botão Avançar .

A caixa de diálogo Configurar seu novo projeto: Aplicativo WPF é aberta:
Na caixa de texto Nome do projeto , insira um nome de projeto, como MyWpfDotnetCoreWv2App.
Na caixa de texto Local , selecione um caminho na unidade local, como C:\Users\myusername\Documents\MyProjects, e clique no botão Avançar .

A caixa de diálogo Informações adicionais é exibida, com uma lista suspensa da Estrutura de Destino :
Selecione .NET Core 3.1 ou posterior, como o .NET 6.0. (Não selecione .NET Core 3.0.) Em seguida, clique no botão Criar .

O projeto inicial do aplicativo WPF do .NET Core é aberto no Visual Studio:

Pule para a Etapa 3 – Crie e execute o projeto inicial sem o WebView2 abaixo.

Criando um projeto de Aplicativo WPF (.NET Framework)

Se você estiver criando um projeto de aplicativo WPF (.NET Framework), execute as etapas a seguir. Caso contrário, vá para a Etapa 3 – Compilar e executar o projeto inicial sem o WebView2.

Abra o Microsoft Visual Studio, como o Visual Studio 2022.
No painel de abertura, clique em Criar novo projeto. Ou, na janela principal do Visual Studio, selecione Arquivo>Novo>Projeto. A caixa de diálogo Criar um novo projeto é aberta.
Na caixa de texto Pesquisar modelos , digite WPF App. O painel Criar um novo projeto mostra os modelos de projeto instalados que correspondem ao texto inserido. Este artigo mostra as caixas de diálogo C# em vez de VB; ambos os idiomas são compatíveis com o WebView2.
Clique em um modelo de projeto que tenha o título Aplicativo WPF (.NET Framework) e o texto de descrição Aplicativo cliente do Windows Presentation Foundation:

Se o modelo de projeto acima não estiver listado, consulte Etapa 1 – Instalar o Visual Studio com suporte do .NET acima para instalar as ferramentas de desenvolvimento da área de trabalho do .NET.
Clique no botão Avançar .

A caixa de diálogo Configurar seu novo projeto: aplicativo WPF (.NET Framework) é aberta:
Na caixa de texto Nome do projeto , insira um nome de projeto, como MyWpfDotnetFwkWv2App.
Na caixa de texto Local , selecione um caminho na unidade local, como C:\Users\myusername\Documents\MyProjects.
Na lista suspensa Framework, selecione .NET Framework 4.6.2 ou posterior.
Clique no botão Criar .

O projeto inicial do aplicativo WPF (.NET Framework) é aberto no Visual Studio:

Etapa 3 - Compilar e executar o projeto inicial sem o WebView2

Selecione Arquivo>Salvar Tudo para salvar o projeto.
Clique em F5 para compilar e executar o projeto.

O projeto é executado e exibe uma janela vazia:

Talvez seja necessário instalar a versão selecionada do .NET Framework, da seguinte maneira.
Se o aplicativo não abrir, selecione Depurar>Iniciar Sem Depuração.

Se não tiver instalado a versão selecionada do .NET Framework, você poderá receber a seguinte caixa de diálogo: "Não foi possível iniciar este aplicativo. O aplicativo requer uma das seguintes versões do .NET Framework: . NETFramework,Version=v4.8.1 - Deseja instalar esta versão do .NET Framework agora?"
Se você receber esse diálogo, acesse Baixar o .NET Framework e baixe e instale a versão necessária do Pacote do Desenvolvedor (não o Runtime). Por exemplo, baixe ndp481-devpack-enu.exe para C:\Users\username\Downloadse clique duas vezes no arquivo para instalá-lo.
Se solicitado, reinicie o computador:
Vá para o arquivo baixado, como ndp481-devpack-enu.exe em C:\Users\username\Downloads, e clique duas vezes novamente no arquivo baixado para instalar o .NET Framework Developer Pack. Uma caixa de diálogo Sucesso é exibida:
Se solicitado, reinicie o computador novamente.
Abra o Visual Studio e abra a solução que você criou.
Pressione F5 para executar o aplicativo inicial (mostrado acima), que ainda não está incluindo o SDK do WebView2.
Feche o aplicativo inicial.

Etapa 4 - Instalar o SDK do WebView2

No Visual Studio, use o Gerenciador de Pacotes NuGet para adicionar o SDK do WebView2 ao projeto, da seguinte maneira:

No Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto (com base no modelo de projeto .NET (Core) ou .NET Framework) e selecione Gerenciar Pacotes NuGet:
No canto superior esquerdo, clique na guia Procurar . Na barra de pesquisa, digite Microsoft.Web.WebView2e clique no pacote Microsoft.Web.WebView2 .

A caixa de diálogo do gerenciador de pacotes NuGet exibe os resultados da pesquisa, incluindo um pacote Microsoft.Web.WebView2 . A caixa de diálogo tem um número de versão e o botão Instalar .
Aceite a versão padrão e clique no botão Instalar .
Na caixa de diálogo Visualizar Alterações , clique no botão OK .
Selecione Arquivo>Salvar Tudo para salvar o projeto.
Clique em F5 para compilar e executar o projeto.

O projeto é executado e exibe uma janela vazia. Isso verifica se o WebView2 está instalado e funcionando, embora o WebView2 ainda não tenha conteúdo para exibir:
Feche o aplicativo.

Etapa 5 - Criar um único controle WebView2

Adicione um controle WebView2 ao seu aplicativo.

MainWindow.xaml No arquivo, para adicionar o namespace XAML WebView2, insira a seguinte linha dentro da <Window/> marca:
```
xmlns:wv2="clr-namespace:Microsoft.Web.WebView2.Wpf;assembly=Microsoft.Web.WebView2.Wpf"
```

Verifique se o código MainWindow.xaml é semelhante ao código a seguir:

<Window x:Class="WPF_Getting_Started.MainWindow"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
      xmlns:local="clr-namespace:{YOUR PROJECT NAME}"
      xmlns:wv2="clr-namespace:Microsoft.Web.WebView2.Wpf;assembly=Microsoft.Web.WebView2.Wpf"
      mc:Ignorable="d"
      Title="MainWindow"
      Height="450"
      Width="800"
>
   <Grid>

   </Grid>
</Window>

Para adicionar o controle WebView2, substitua as <Grid> marcas pelo código a seguir. A Source propriedade define o URI inicial exibido no controle WebView2.
```
<DockPanel>
   <wv2:WebView2 Name="webView"
                  Source="https://www.microsoft.com"
   />
</DockPanel>
```
Selecione Arquivo>Salvar Tudo para salvar o projeto.
Clique em F5 para compilar e executar o projeto.
Verifique se o controle do WebView2 exibe https://www.microsoft.com:

Permita que os usuários alterem a URL que o controle WebView2 exibe, adicionando uma barra de endereços ao aplicativo.

MainWindow.xaml No arquivo, adicione uma barra de endereços copiando e colando o código a seguir dentro do <DockPanel> que contém o controle WebView2. Mantenha o código existente abaixo do novo trecho.

<DockPanel DockPanel.Dock="Top">
    <Button x:Name="ButtonGo"
              DockPanel.Dock="Right"
              Click="ButtonGo_Click"
              Content="Go"
    />
    <TextBox Name="addressBar"/>
</DockPanel>

Verifique se a <DockPanel>MainWindow.xaml seção do arquivo corresponde ao seguinte código:

<DockPanel>
    <DockPanel DockPanel.Dock="Top">
        <Button x:Name="ButtonGo" DockPanel.Dock="Right" Click="ButtonGo_Click" Content="Go"/>
        <TextBox Name = "addressBar"/>
    </DockPanel>
    <wv2:WebView2 Name = "webView"
                  Source = "https://www.microsoft.com"
    />
</DockPanel>

Em MainWindow.xaml.cs, para adicionar o CoreWebView2 namespace, insira o seguinte código na parte superior do arquivo:
```
using Microsoft.Web.WebView2.Core;
```

MainWindow.xaml.csNo arquivo, copie o código a seguir para criar o ButtonGo_Click método. Esse código navega pelo controle WebView2 até a URL inserida na barra de endereços.

private void ButtonGo_Click(object sender, RoutedEventArgs e)
{
    if (webView != null && webView.CoreWebView2 != null)
    {
        webView.CoreWebView2.Navigate(addressBar.Text);
    }
}

Cole o código diretamente após a Public MainWIndow declaração, conforme mostrado no código a seguir:

namespace WpfApp1
{
   /// <summary>
   /// Interaction logic for MainWindow.xaml
   /// </summary>
   public partial class MainWindow : Window
   {
      public MainWindow()
      {
            InitializeComponent();
      }
      void ButtonGo_Click(object sender, RoutedEventArgs e)
      {
            if (webView != null && webView.CoreWebView2 != null)
            {
               webView.CoreWebView2.Navigate(addressBar.Text);
            }
      }
   }
}

Selecione Arquivo>Salvar Tudo para salvar o projeto.
Clique em F5 para compilar e executar o projeto.
Digite uma nova URL na barra de endereços e escolha Ir. Por exemplo, digite https://www.bing.com.
Verifique se o controle WebView2 abre a URL inserida.

Certifique-se de inserir uma URL completa na barra de endereços. O aplicativo gera uma caixa de ArgumentException seleção se a URL não começar com http:// ou https://.

O aplicativo de exemplo exibe o site do Bing com a URL https://www.bing.com na barra de endereços:

Durante a navegação na página da Web, o controle WebView2 gera eventos. O aplicativo que hospeda os controles WebView2 escuta os seguintes eventos:

NavigationStarting
SourceChanged
ContentLoading
HistoryChanged
NavigationCompleted

Eventos de navegação, desde o novo documento, até o início da navegação, até a navegação concluída

O diagrama acima mostra a sequência de eventos. Os eventos de navegação começam com um novo documento.

Caminho de sucesso

Um caminho bem-sucedido inclui a sequência completa de eventos:

Início da navegação.
Fonte alterada, com possível entrada do mesmo documento.
Carregamento de conteúdo.
Mudanças na história.
Navegação concluída.

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

Caminho da falha

Se houver uma falha, o caminho da falha prossegue diretamente desde o início da navegação até a conclusão da navegação, ignorando os eventos intermediários.

Quando ocorre um erro, os seguintes eventos são gerados e podem depender da navegação para uma página da Web de erros:

SourceChanged
ContentLoading
HistoryChanged

Redirecionamento

Se ocorrer um redirecionamento HTTP, haverá vários NavigationStarting eventos seguidos.

Para demonstrar como usar os eventos, registre um manipulador que NavigationStarting cancele todas as solicitações não HTTPS, da seguinte maneira.

MainWindow.xaml.cs No arquivo, modifique o construtor para corresponder à parte superior do código a seguir. Abaixo do construtor, adicione a EnsureHttps função:

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

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

No construtor, EnsureHttps é registrado como o manipulador de eventos no NavigationStarting evento no controle WebView2.

Selecione Arquivo>Salvar Tudo para salvar o projeto.
Clique em F5 para compilar e executar o projeto.
Tente abrir um site HTTP. Verifique se o controle WebView2 permanece inalterado.
Tente abrir um site HTTPS. O controle WebView2 permite abrir sites HTTPS.

Etapa 8 - Script

Você pode usar aplicativos host para injetar código JavaScript em controles 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 tempo específico:

Execute-o após a criação do objeto global.
Execute-o antes de executar qualquer outro script incluído no documento HTML.

Por exemplo, adicione scripts que enviam um alerta quando um usuário navega para sites não HTTPS, da seguinte maneira:

Modifique a EnsureHttps função para injetar um script no conteúdo da Web que usa o método ExecuteScriptAsync .

void EnsureHttps(object sender, CoreWebView2NavigationStartingEventArgs args)
{
   String uri = args.Uri;
   if (!uri.StartsWith("https://"))
   {
      webView.CoreWebView2.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
      args.Cancel = true;
   }
}

Selecione Arquivo>Salvar Tudo para salvar o projeto.
Clique em F5 para compilar e executar o projeto.
Verifique se o aplicativo exibe um alerta quando você navega para um site que não usa HTTPS.

Etapa 9 - Comunicação entre o host e o conteúdo da Web

O host e o conteúdo da Web podem se comunicar das seguintes maneiras usando postMessage:

O conteúdo da Web em um controle WebView2 pode postar uma mensagem no host usando window.chrome.webview.postMessage. O host manipula a mensagem usando qualquer um registrado WebMessageReceived no host.
Os hosts postam mensagens no conteúdo da Web em um controle WebView2 usando CoreWebView2.PostWebMessageAsString ou CoreWebView2.PostWebMessageAsJSON. As mensagens são capturadas por manipuladores adicionados a window.chrome.webview.addEventListener.

O mecanismo de comunicação passa mensagens do conteúdo da Web para o host usando recursos nativos.

Em seu projeto, quando o controle WebView2 navega para uma URL, ele exibe a URL na barra de endereços e alerta o usuário sobre a URL exibida no controle WebView2.

Em MainWindow.xaml.cs, atualize seu construtor e crie uma InitializeAsync função para corresponder ao código a seguir. A InitializeAsync função aguarda EnsureCoreWebView2Async, pois a inicialização de CoreWebView2 é assíncrona.
```
public MainWindow()
{
   InitializeComponent();
   webView.NavigationStarting += EnsureHttps;
   InitializeAsync();
}

async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
}
```

Após a inicialização do CoreWebView2 , registre um manipulador de eventos para responder ao WebMessageReceived. Em MainWindow.xaml.cs, atualize InitializeAsync e adicione UpdateAddressBar usando o seguinte código:

async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
   webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;
}

void UpdateAddressBar(object sender, CoreWebView2WebMessageReceivedEventArgs args)
{
   String uri = args.TryGetWebMessageAsString();
   addressBar.Text = uri;
   webView.CoreWebView2.PostWebMessageAsString(uri);
}

Para que o controle WebView2 envie e responda à mensagem da Web, depois CoreWebView2 de inicializado, o host faz o seguinte:
1. Injeta um script no conteúdo da Web que registra um manipulador para imprimir mensagens do host.
2. Injeta um script no conteúdo da Web que posta a URL no host.

Em MainWindow.xaml.cs, atualize InitializeAsync para corresponder ao seguinte código:

async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
   webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;

   await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.postMessage(window.document.URL);");
   await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.addEventListener(\'message\', event => alert(event.data));");
}

Selecione Arquivo>Salvar Tudo para salvar o projeto.
Clique em F5 para compilar e executar o projeto.
Quando você abre um novo URI, o controle WebView2 exibe o URI na barra de endereços.

O aplicativo de exemplo exibe o URI na barra de endereços e no site da Microsoft: https://www.microsoft.com

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

Confira também

Referência da API WebView2
- WPF

developer.microsoft.com:

Microsoft Edge WebView2 - introdução inicial aos recursos do WebView2 em developer.microsoft.com.

Páginas locais:

Aplicativo de exemplo WPF
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

GitHub:

Repositório de > WebView2Samples WebView2WpfBrowser

Comentários

Esta página foi útil?

Last updated on 2026-08-24