Introdução ao WebView2 em aplicações WPF

Artigo
08/02/2024

Este artigo aborda como configurar as suas ferramentas de desenvolvimento, criar uma aplicação WebView2 inicial para o Windows Presentation Foundation (WPF) e saber mais sobre os conceitos do WebView2 ao longo do percurso.

Neste tutorial, vai utilizar o modelo de projeto Aplicação WPF ou Aplicação WPF (.NET Framework) para criar uma aplicação WPF e, em seguida, instalar o SDK WebView2 para o projeto para adicionar o WebView2.

Projeto concluído

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

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

Passo 1 – Instalar o Visual Studio com suporte para .NET

Este tutorial requer o Microsoft Visual Studio e não o Microsoft Visual Studio Code. Este artigo descreve principalmente a utilização do Visual Studio 2022.

Instale o Visual Studio. Instale o suporte de desenvolvimento de ambiente de trabalho .NET para obter os modelos de projeto necessários, da seguinte forma.
Se estiver no ecrã de arranque do Visual Studio, desloque-se para a parte inferior da caixa de diálogo Criar um novo projeto e clique na ligação Abrir sem código. O Visual Studio é aberto.
No Visual Studio, selecione Ferramentas>Obter Ferramentas e Funcionalidades. A janela Do Instalador do Visual Studio é aberta e a caixa de diálogo Modificar é aberta sobre a mesma.
Selecione a carga de trabalho de desenvolvimento de ambiente de trabalho .NET para que tenha uma marca de verificação.
Na secção Detalhes > de instalação.NET desenvolvimento> de ambiente de trabalhoIncluído à direita, certifique-se de que as ferramentas de desenvolvimento de ambiente de trabalho .NET e as ferramentas de desenvolvimento do .NET Framework 4.7.2 estão listadas, com uma marca de verificação junto às mesmas.
Na secção Detalhes > de instalação.NET desenvolvimento > de ambiente de trabalhoOpcional à direita:
- Se estiver a utilizar o Visual Studio 2022, certifique-se de que as Ferramentas de desenvolvimento para .NET estão selecionadas:
- Se estiver a utilizar o Visual Studio 2019, certifique-se de que as ferramentas de desenvolvimento .NET estão selecionadas :
Clique no botão Modificar .

Este tutorial também funciona com o Visual Studio 2017. Veja Transferências mais antigas do Visual Studio. Instale o suporte do .NET para obter os modelos de projeto necessários, semelhantes aos passos acima.

Passo 2 – Criar uma aplicação WebView2 de janela única

Comece por criar um projeto de ambiente de trabalho básico que contém uma única janela principal.

Decida se pretende criar um projeto .NET Core/5/6 (mais recente) ou um projeto da Aplicação WPF (.NET Framework) (mais antigo). Para saber mais, confira:
- Histórico do .NET em O que é o .NET? Introdução e descrição geral.
- .NET na Wikipédia.
Siga a secção aplicável abaixo.

Criar um projeto .NET Core/5/6

Se estiver a criar um projeto .NET Core/5/6, siga os seguintes passos. Caso contrário, avance para Criar um projeto da Aplicação WPF (.NET Framework).

Abra o Microsoft Visual Studio, como o Visual Studio 2022.
No painel de abertura, clique em Criar novo projeto. Em alternativa, na janela principal do Visual Studio, selecione Ficheiro>Novo>Projeto. É aberta a caixa de diálogo Criar um novo projeto .
Na caixa de texto Procurar modelos , escreva WPF Application. O painel Criar um novo projeto mostra os modelos de projeto instalados que correspondem ao texto introduzido. Este artigo mostra as caixas de diálogo C# em vez de VB; ambos os idiomas são suportados para WebView2.
Se estiver a utilizar o Visual Studio 2022, clique num modelo de projeto com o título Aplicação WPF e o texto de descrição Um projeto para criar uma Aplicação WPF .NET:

Se estiver a utilizar o Visual Studio 2019, clique num modelo de projeto que tenha o título Aplicação WPF e o texto de descrição Um projeto para criar uma Aplicação WPF .NET Core:

Se o modelo de projeto acima não estiver listado, consulte o Passo 1 – Instalar o Visual Studio com suporte para .NET acima para instalar ferramentas de desenvolvimento de ambiente de trabalho .NET.
Clique no botão Seguinte .

É aberta a caixa de diálogo Configurar o novo projeto: Aplicação WPF :
Na caixa de texto Nome do projeto, introduza um nome de projeto, como MyWpfDotnetCoreWv2App.
Na caixa de texto Localização , selecione um caminho na unidade local, como C:\Users\myusername\Documents\MyProjects, e, em seguida, clique no botão Seguinte .

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

O projeto de Aplicação WPF de .NET Core inicial é aberto no Visual Studio:

Avance para o Passo 3 – Compilar e executar o projeto inicial sem o WebView2 abaixo.

Criar um projeto da Aplicação WPF (.NET Framework)

Se estiver a criar um projeto da Aplicação WPF (.NET Framework), siga os seguintes passos. Caso contrário, avance para o Passo 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. Em alternativa, na janela principal do Visual Studio, selecione Ficheiro>Novo>Projeto. É aberta a caixa de diálogo Criar um novo projeto .
Na caixa de texto Procurar modelos , escreva WPF App. O painel Criar um novo projeto mostra os modelos de projeto instalados que correspondem ao texto introduzido. Este artigo mostra as caixas de diálogo C# em vez de VB; ambos os idiomas são suportados para WebView2.
Clique num modelo de projeto com o título Aplicação WPF (.NET Framework) e o texto de descrição da aplicação cliente Windows Presentation Foundation:

Se o modelo de projeto acima não estiver listado, consulte o Passo 1 – Instalar o Visual Studio com suporte para .NET acima para instalar ferramentas de desenvolvimento de ambiente de trabalho .NET.
Clique no botão Seguinte .

É aberta a caixa de diálogo Configurar o novo projeto: Aplicação WPF (.NET Framework ):
Na caixa de texto Nome do projeto, introduza um nome de projeto, como MyWpfDotnetFwkWv2App.
Na caixa de texto Localização , selecione um caminho na unidade local, como C:\Users\myusername\Documents\MyProjects.
Na lista pendente Framework , selecione .NET Framework 4.6.2 ou posterior.
Clique no botão Criar .

O projeto inicial da Aplicação WPF (.NET Framework) é aberto no Visual Studio:

Passo 3 – Criar e executar o projeto inicial sem o WebView2

Selecione Ficheiro>Guardar Tudo para guardar o projeto.
Clique em F5 para compilar e executar o projeto.

O projeto é executado e apresenta uma janela vazia:

Poderá ter de instalar a versão do .NET Framework selecionada, da seguinte forma.
Se a aplicação não abrir, selecione Depurar>Iniciar Sem Depuração.

Se ainda não instalou a versão selecionada do .NET Framework, poderá obter a seguinte caixa de diálogo: "Não foi possível iniciar esta aplicação. A aplicação requer uma das seguintes versões do .NET Framework: . NETFramework,Version=v4.8.1 - Pretende instalar esta versão do .NET Framework agora?"
Se receber essa caixa de diálogo, aceda a Transferir .NET Framework e transfira e, em seguida, instale a versão necessária do Developer Pack (não o Runtime). Por exemplo, transfira ndp481-devpack-enu.exe para C:\Users\username\Downloadse, em seguida, faça duplo clique no ficheiro para instalá-lo.
Se lhe for pedido, reinicie o computador:
Aceda ao ficheiro transferido, como ndp481-devpack-enu.exe em C:\Users\username\Downloadse, novamente, faça duplo clique no ficheiro transferido para instalar o Pacote de Programadores do .NET Framework. É apresentada uma caixa de diálogo Êxito :
Se lhe for pedido, reinicie novamente o computador.
Abra o Visual Studio e abra a solução que criou.
Prima F5 para executar a aplicação inicial (mostrada acima), sem incluir ainda o SDK WebView2.
Feche a aplicação inicial.

Passo 4 – Instalar o SDK WebView2

No Visual Studio, utilize o Gestor de Pacotes NuGet para adicionar o SDK WebView2 ao projeto, da seguinte forma:

No Explorador de Soluções, clique com o botão direito do rato no nome do projeto (com base no modelo de projeto .NET (Core) ou .NET Framework) e, em seguida, selecione Gerir Pacotes NuGet:
No canto superior esquerdo, clique no separador Procurar . Na barra de pesquisa, escreva Microsoft.Web.WebView2e, em seguida, clique no pacote Microsoft.Web.WebView2 .

A caixa de diálogo Gestor de pacotes NuGet apresenta 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 predefinida e, em seguida, clique no botão Instalar .
Na caixa de diálogo Pré-visualizar Alterações , clique no botão OK .
Selecione Ficheiro>Guardar Tudo para guardar o projeto.
Clique em F5 para compilar e executar o projeto.

O projeto é executado e apresenta uma janela vazia. Isto verifica se o WebView2 está instalado e a funcionar, embora o WebView2 ainda não tenha conteúdos para apresentar:
Feche a aplicação.

Passo 5 – Criar um único controlo WebView2

Adicione um controlo WebView2 à sua aplicação.

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

Certifique-se de que o código em MainWindow.xaml tem o seguinte aspeto:

<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 controlo WebView2, substitua as <Grid> etiquetas pelo seguinte código. A Source propriedade define o URI inicial apresentado no controlo WebView2.
```
<DockPanel>
   <wv2:WebView2 Name="webView"
                  Source="https://www.microsoft.com"
   />
</DockPanel>
```
Selecione Ficheiro>Guardar Tudo para guardar o projeto.
Clique em F5 para compilar e executar o projeto.
Certifique-se de que o controlo WebView2 é apresentado https://www.microsoft.com:

Permita que os utilizadores alterem o URL apresentado pelo controlo WebView2 ao adicionar uma barra de endereço à aplicação.

MainWindow.xaml No ficheiro, adicione uma barra de endereço ao copiar e colar o seguinte código dentro do <DockPanel> que contém o controlo WebView2. Mantenha o código existente abaixo do novo fragmento.

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

Certifique-se de que a <DockPanel> secção do MainWindow.xaml ficheiro 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 espaço de nomes, insira o seguinte código na parte superior do ficheiro:
```
using Microsoft.Web.WebView2.Core;
```

MainWindow.xaml.csNo ficheiro, copie o seguinte código para criar o ButtonGo_Click método . Este código navega no controlo WebView2 para o URL introduzido na barra de endereço.

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

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

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 Ficheiro>Guardar Tudo para guardar o projeto.
Clique em F5 para compilar e executar o projeto.
Escreva um novo URL na barra de endereço e selecione Ir. Por exemplo, digite https://www.bing.com.
Certifique-se de que o controlo WebView2 abre o URL que introduziu.

Certifique-se de que introduz um URL completo na barra de endereço. A aplicação gera um ArgumentException se o URL não começar com http:// ou https://.

A aplicação de exemplo apresenta o site do Bing com o URL https://www.bing.com na barra de endereço:

Durante a navegação na página Web, o controlo WebView2 gera eventos. A aplicação que aloja controlos WebView2 escuta os seguintes eventos:

NavigationStarting
SourceChanged
ContentLoading
HistoryChanged
NavigationCompleted

Eventos de navegação, desde o novo documento até ao início da navegação, através da 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 êxito

Um caminho com êxito inclui a sequência completa de eventos:

Navegação a iniciar.
A origem foi alterada, com uma possível entrada do mesmo documento.
Carregamento de conteúdos.
Alterações ao histórico.
Navegação concluída.

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

Caminho da falha

Se ocorrer uma falha, o caminho da falha continua diretamente desde o início da navegação até à navegação concluída, ignorando os eventos intervenientes.

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

SourceChanged
ContentLoading
HistoryChanged

Redirecionamento

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

Para demonstrar como utilizar os eventos, registe um processador para NavigationStarting o que cancele quaisquer pedidos não HTTPS, da seguinte forma.

MainWindow.xaml.cs No ficheiro, modifique o construtor para corresponder à parte superior do seguinte código. Por baixo 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 é registado como o processador de eventos no NavigationStarting evento no controlo WebView2.

Selecione Ficheiro>Guardar Tudo para guardar o projeto.
Clique em F5 para compilar e executar o projeto.
Tente abrir um site HTTP. Certifique-se de que o controlo WebView2 permanece inalterado.
Tente abrir um site HTTPS. O controlo WebView2 permite-lhe abrir sites HTTPS.

Passo 8 – Scripting

Pode utilizar aplicações anfitriãs para injetar código JavaScript em controlos WebView2 no runtime. Pode fazer uma tarefa do WebView2 para executar JavaScript arbitrário ou adicionar scripts de inicialização. O JavaScript injetado aplica-se a todos os novos documentos de nível superior e a quaisquer frames subordinados até que o JavaScript seja removido.

O JavaScript injetado é executado com temporização específica:

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

Por exemplo, adicione scripts que enviam um alerta quando um utilizador navega para sites não HTTPS, da seguinte forma:

Modifique a EnsureHttps função para injetar um script no conteúdo Web que utiliza 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 Ficheiro>Guardar Tudo para guardar o projeto.
Clique em F5 para compilar e executar o projeto.
Certifique-se de que a aplicação apresenta um alerta quando navega para um site que não utiliza HTTPS.

Passo 9 – Comunicação entre o anfitrião e o conteúdo Web

O anfitrião e o conteúdo Web podem comunicar das seguintes formas com postMessage:

Os conteúdos Web num controlo WebView2 podem publicar uma mensagem no anfitrião com window.chrome.webview.postMessage. O anfitrião processa a mensagem utilizando qualquer registado WebMessageReceived no anfitrião.
Os anfitriões publicam mensagens em conteúdo Web num controlo WebView2 com CoreWebView2.PostWebMessageAsString ou CoreWebView2.PostWebMessageAsJSON. As mensagens são capturadas por processadores adicionados a window.chrome.webview.addEventListener.

O mecanismo de comunicação transmite mensagens de conteúdo Web para o anfitrião através de capacidades nativas.

No seu projeto, quando o controlo WebView2 navega para um URL, apresenta o URL na barra de endereço e alerta o utilizador do URL apresentado no controlo WebView2.

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

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

Depois de o CoreWebView2 ser inicializado, registe um processador de eventos para responder a WebMessageReceived. No MainWindow.xaml.cs, atualize InitializeAsync e adicione UpdateAddressBar com 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 controlo WebView2 envie e responda à mensagem Web, depois CoreWebView2 de inicializado, o anfitrião faz o seguinte:
1. Injeta um script no conteúdo Web que regista um processador para imprimir uma mensagem do anfitrião.
2. Injeta um script no conteúdo Web que publica o URL no anfitrião.

No 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 Ficheiro>Guardar Tudo para guardar o projeto.
Clique em F5 para compilar e executar o projeto.
Quando abre um novo URI, o controlo WebView2 apresenta o URI na barra de endereço.

A aplicação de exemplo apresenta o URI na barra de endereço e no site da Microsoft: https://www.microsoft.com

Parabéns, criou a sua primeira aplicação WebView2!

Confira também

Referência da API webView2
- WPF

developer.microsoft.com:

Microsoft Edge WebView2 – introdução inicial às funcionalidades do WebView2 no developer.microsoft.com.

Páginas locais:

Aplicação de exemplo WPF
Gerir pastas de dados do utilizador
Código de Exemplo para WebView2 - um guia para o WebView2Samples repositório.
Melhores práticas de desenvolvimento para aplicações WebView2

GitHub:

WebView2Samples repo > WebView2WpfBrowser

Partilhar via