Introdução ao WebView2 em aplicativos WPF

  • Artigo

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

Neste tutorial, você usa o modelo de projeto aplicativo WPF ou aplicativo WPF (.NET Framework) para criar um aplicativo WPF e instalar o SDK do WebView2 para o projeto para adicionar o WebView2.

Projeto concluído

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

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

Etapa 1 – Instalar o Visual Studio com suporte ao .NET

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

  1. Instale o Visual Studio. Instale o suporte ao desenvolvimento da área de trabalho do .NET para obter os modelos de projeto necessários da seguinte maneira.

  2. 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 abre.

  3. No Visual Studio, selecione Ferramentas>Obter Ferramentas e Recursos. A janela Instalador do Visual Studio é aberta e a caixa de diálogo Modificação é aberta sobre ela.

  4. Selecione a carga de trabalho de desenvolvimento da área de trabalho do .NET para que haja uma marca de seleção nela.

  5. Na seção Detalhes > da instalação.NET Desenvolvimento> da área de trabalhoIncluído à direita, verifique se as ferramentas de desenvolvimento da área de trabalho do .NET e .NET Framework ferramentas de desenvolvimento 4.7.2 estão listadas, com um indicador de verificação ao lado delas.

  6. Na seção Detalhes da instalação.NET> Desenvolvimento > da área de trabalhoOpcional à direita:

    • Se você estiver usando o Visual Studio 2022, verifique se as ferramentas de desenvolvimento do .NET estão selecionadas:

    Caixa de diálogo 'Modificando' do Visual Studio 2022 para instalar modelos para o desenvolvimento da área de trabalho do '.NET'

    • Se você estiver usando o Visual Studio 2019, verifique se as ferramentas de desenvolvimento do .NET estão selecionadas :

    Caixa de diálogo 'Modificando' do Visual Studio 2019 para instalar modelos para o desenvolvimento da área de trabalho do '.NET'

  7. 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 – Instalar um canal de visualização do Microsoft Edge

  1. Baixe qualquer Canal do Microsoft Edge Insider (versão prévia) (Beta, Desenvolvimento ou Canário) em um sistema operacional (sistema operacional com suporte):

    • Windows 10
    • Windows 11

    Recomendamos usar o canal canário do Microsoft Edge. A versão mínima necessária é 82.0.488.0.

Etapa 3 – Criar um aplicativo WebView2 de janela única

Comece criando um projeto de área de trabalho básico que contém uma única janela de main.

  1. Decida se é necessário criar um projeto do .NET Core/5/6 (mais recente) ou um projeto do WPF App (.NET Framework) (mais antigo). Para saber mais, veja:

  2. Siga a seção aplicável abaixo.

Criando um projeto do .NET Core/5/6

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

  1. Abra o Microsoft Visual Studio, como o Visual Studio 2022.

  2. No painel de abertura, clique em Criar novo projeto. Ou, na janela main Visual Studio, selecione Arquivo>Novo>Projeto. A caixa de diálogo Criar um novo projeto é aberta.

  3. 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 têm suporte para WebView2.

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

    Selecionando o modelo 'Aplicativo WPF: Aplicativo WPF do .NET Core' na caixa de diálogo 'Criar um novo projeto' de 2022

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

    Selecionando o modelo 'Aplicativo WPF: Aplicativo WPF do .NET Core' na caixa de diálogo 'Criar um novo projeto' de 2019

    Se o modelo de projeto acima não estiver listado, consulte Etapa 1 – Instalar o Visual Studio com suporte ao .NET acima para instalar ferramentas de desenvolvimento da área de trabalho do .NET.

  5. Clique no botão Avançar .

    A caixa de diálogo Configurar seu novo projeto: aplicativo WPF é aberta:

    A caixa de diálogo 'Configurar seu novo projeto: Aplicativo WPF' para um projeto do .NET Core/5/6

  6. Na caixa de texto Nome do projeto , insira um nome de projeto, como MyWpfDotnetCoreWv2App.

  7. Na caixa de texto Local , selecione um caminho em sua 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 do Target Framework :

    A caixa de diálogo 'Informações adicionais' com uma lista suspensa 'Target Framework'

  8. 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 inicial do Aplicativo WPF do .NET Core é aberto no Visual Studio:

    Projeto inicial no Visual Studio 2022 usando o modelo de aplicativo WPF do .NET Core

Ignorar para a Etapa 4 – Compilar e executar o projeto inicial sem WebView2 abaixo.

Criando um projeto de aplicativo WPF (.NET Framework)

Se você estiver criando um projeto do Aplicativo WPF (.NET Framework), siga as etapas a seguir. Caso contrário, pule para a Etapa 4 – Compilar e execute o projeto inicial sem WebView2.

  1. Abra o Microsoft Visual Studio, como o Visual Studio 2022.

  2. No painel de abertura, clique em Criar novo projeto. Ou, na janela main Visual Studio, selecione Arquivo>Novo>Projeto. A caixa de diálogo Criar um novo projeto é aberta.

  3. 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 têm suporte para WebView2.

  4. Clique em um modelo de projeto que tenha o título WPF App (.NET Framework) e o texto de descrição Windows Presentation Foundation aplicativo cliente:

    Selecionando o modelo 'Aplicativo WPF' na caixa de diálogo 'Criar um novo projeto' de 2022

    Se o modelo de projeto acima não estiver listado, consulte Etapa 1 – Instalar o Visual Studio com suporte ao .NET acima para instalar ferramentas de desenvolvimento da área de trabalho do .NET.

  5. Clique no botão Avançar .

    A caixa de diálogo Configurar seu novo projeto: aplicativo WPF (.NET Framework) é aberta:

    A caixa de diálogo 'Configurar seu novo projeto: Aplicativo WPF (.NET Framework)'

  6. Na caixa de texto Nome do projeto , insira um nome de projeto, como MyWpfDotnetFwkWv2App.

  7. Na caixa de texto Local , selecione um caminho em sua unidade local, como C:\Users\myusername\Documents\MyProjects.

  8. Na lista suspensa Estrutura, selecione .NET Framework 4.6.2 ou posterior.

  9. Clique no botão Criar .

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

    Projeto inicial no Visual Studio 2022 usando o modelo WPF App (.NET Framework)

Etapa 4 – Criar e executar o projeto inicial sem WebView2

  1. Selecione Salvar>Todos para salvar o projeto.

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

    O projeto é executado e exibe uma janela vazia:

    Janela de aplicativo vazia sem WebView2

    Talvez seja necessário instalar a versão .NET Framework selecionada da seguinte maneira.

  3. Se o aplicativo não abrir, selecione Depurar>Iniciar sem Depuração.

    Se você não tiver instalado a versão selecionada do .NET Framework, poderá obter a seguinte caixa de diálogo: "Este aplicativo não pôde ser iniciado. O aplicativo requer uma das seguintes versões do .NET Framework: . NETFramework,Version=v4.8.1 - Deseja instalar essa versão .NET Framework agora?"

  4. Se você receber essa caixa de diálogo, vá para Baixar .NET Framework e baixar e instale a versão necessária do Pacote de Desenvolvedores (não o Runtime). Por exemplo, baixe ndp481-devpack-enu.exe para C:\Users\username\Downloads, e clique duas vezes no arquivo para instalá-lo.

  5. Se solicitado, reinicie seu computador:

    Reiniciar para instalar .NET Framework

  6. Vá para o arquivo baixado, como ndp481-devpack-enu.exe em C:\Users\username\Downloads, e novamente clique duas vezes no arquivo baixado para instalar o .NET Framework Pacote de Desenvolvedores. Uma caixa de diálogo Sucesso é exibida:

    Configuração bem-sucedida para instalar .NET Framework

  7. Se solicitado, reinicie o computador novamente.

  8. Abra o Visual Studio e abra a solução que você criou.

  9. Pressione F5 para executar o aplicativo inicial (mostrado acima), ainda não incluindo o SDK do WebView2.

  10. Feche o aplicativo inicial.

Etapa 5 – 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:

  1. Em 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:

    O comando 'Gerenciar pacotes NuGet' no menu com o botão direito do mouse

  2. No canto superior esquerdo, clique na guia Procurar . Na barra de pesquisa, digite Microsoft.Web.WebView2, em seguida, clique no pacote Microsoft.Web.WebView2 .

    A caixa de diálogo gerenciador de pacotes NuGet exibe resultados de pesquisa, incluindo um pacote Microsoft.Web.WebView2 . A caixa de diálogo tem um número de versão e o botão Instalar .

    A caixa de diálogo gerenciador de pacotes NuGet exibe o pacote Microsoft.Web.WebView2

  3. Aceite a versão padrão e clique no botão Instalar .

  4. Na caixa de diálogo Alterações de Visualização , clique no botão OK .

  5. Selecione Salvar>Todos para salvar o projeto.

  6. 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 a ser exibido:

    Janela de aplicativo vazia com o SDK do WebView2

  7. Feche o aplicativo.

Etapa 6 – Criar um único controle WebView2

Adicione um controle WebView2 ao seu aplicativo.

  1. MainWindow.xaml No arquivo, para adicionar o namespace XAML do WebView2, insira a seguinte linha dentro da <Window/> marca:

    xmlns:wv2="clr-namespace:Microsoft.Web.WebView2.Wpf;assembly=Microsoft.Web.WebView2.Wpf"

  2. Verifique se o código em MainWindow.xaml se parece com o seguinte código:

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

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

  4. Selecione Salvar>Todos para salvar o projeto.

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

  6. Verifique se o controle Do WebView2 exibe https://www.microsoft.com:

    O controle WebView2, exibindo o conteúdo da página da Web de microsoft.com

Etapa 7 – Navegação

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

  1. 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 snippet.

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

  2. Verifique se a <DockPanel> seção do MainWindow.xaml 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>

  3. Em MainWindow.xaml.cs, para adicionar o CoreWebView2 namespace, insira o seguinte código na parte superior do arquivo:

    using Microsoft.Web.WebView2.Core;

  4. 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);
    }
}

  5. Cole o código diretamente 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);
            }
      }
   }
}

  6. Selecione Salvar>Todos para salvar o projeto.

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

  8. Digite uma nova URL na barra de endereços e escolha Ir. Por exemplo, digite https://www.bing.com.

  9. Verifique se o controle WebView2 abre a URL inserida.

    Insira uma URL completa na barra de endereços. O aplicativo gera um ArgumentException 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:

    O aplicativo exibe o site do Bing

Etapa 8 – Eventos de navegação

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

  • NavigationStarting
  • SourceChanged
  • ContentLoading
  • HistoryChanged
  • NavigationCompleted

Eventos de navegação, do novo documento até o início da navegação, por meio 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 do sucesso

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

  1. Navegação começando.
  2. A origem foi alterada, com a possível entrada do mesmo documento.
  3. Carregamento de conteúdo.
  4. O histórico muda.
  5. Navegação concluída.

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

Caminho da falha

Se houver uma falha, o caminho de falha seguirá diretamente da navegação inicial, até a navegação concluída, ignorando os eventos interveniente.

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

  • SourceChanged
  • ContentLoading
  • HistoryChanged

Redirecionamento

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

Exemplo que demonstra eventos de navegação

Para demonstrar como usar os eventos, registre um manipulador para NavigationStarting o qual cancela quaisquer solicitações que não sejam HTTPS, da seguinte maneira.

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

  2. Selecione Salvar>Todos para salvar o projeto.

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

  4. Tente abrir um site HTTP. Verifique se o controle WebView2 permanece inalterado.

  5. Tente abrir um site HTTPS. O controle WebView2 permite que você abra sites HTTPS.

Etapa 9 – 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:

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

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

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

  2. Selecione Salvar>Todos para salvar o projeto.

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

  4. Verifique se o aplicativo exibe um alerta quando você navega até um site que não usa HTTPS.

    Mensagem mostrando que um http: URL não é seguro e recomendando experimentar um https: URL em vez disso

Etapa 10 – 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 registro 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 até uma URL, ele exibe a URL na barra de endereços e alerta o usuário da URL exibida no controle WebView2.

  1. No MainWindow.xaml.cs, atualize o 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);
}

  2. Depois que o CoreWebView2 for inicializado, registre um manipulador de eventos para responder a 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);
}

  3. 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 mensagem do host.
    2. Injeta um script no conteúdo da Web que posta a URL no host.

  4. 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));");
}

  5. Selecione Salvar>Todos para salvar o projeto.

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

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

    O aplicativo de exemplo exibe o URI na barra de endereços e no site da Microsoft

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

Confira também

developer.microsoft.com:

Páginas locais:

Github: