Introdução ao WebView2 em aplicativos WinForms

  • Artigo

Este tutorial ajuda você:

  • Configure suas ferramentas de desenvolvimento.
  • Use o modelo de projeto do Windows Forms App (.NET Framework) do Visual Studio para criar um projeto WinForms.
  • Instale o pacote de SDK Microsoft.Web.WebView2 para o projeto WinForms.
  • Saiba mais sobre os conceitos do WebView2 ao longo do caminho.

Etapa 1 – opcionalmente clonar ou baixar o repositório WebView2Samples

Siga um destes procedimentos:

  • Crie um novo projeto no Visual Studio a partir de um modelo de projeto, usando as etapas nas seções abaixo. Isso lhe dará o código e a estrutura de projeto mais recentes.

  • Clone ou baixe o WebView2Samples repositório, abra o projeto concluído no Visual Studio e siga as etapas deste artigo para entender a criação do projeto WinForms e entender o código WebView2 adicionado. Consulte Baixar o repositório WebView2Samples em Configurar seu ambiente de desenvolvimento para WebView2. Uma versão concluída deste projeto tutorial está disponível no diretório de repositório WebView2Samples WinForms_GettingStarted.

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

O exemplo no repositório pode não ser tão atualizado quanto um projeto que você cria usando os modelos de projeto mais recentes do Visual Studio.

Etapa 2 – Instalar o Visual Studio

O Microsoft Visual Studio é necessário. Não há suporte para o Microsoft Visual Studio Code para este tutorial.

  1. Se o Visual Studio ainda não estiver instalado, abra a página Microsoft Visual Studio em uma nova janela ou guia e instale o Visual Studio 2017 ou posterior, como o Visual Studio 2022 Professional.

    Em seguida, retorne aqui e continue abaixo.

Etapa 3 – Criar um aplicativo de janela única

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

  1. Abra o Visual Studio.

  2. Selecione Arquivo>Novo>Projeto.

    A janela recente do Visual Studio Open é exibida:

    O painel de abertura do Visual Studio exibe o cartão Criar um novo projeto

  3. À direita, clique no cartão Criar um novo projeto. O Visual Studio Criar uma nova janela de projeto é aberto.

  4. Na caixa de texto Pesquisar , cole ou comece a digitar o seguinte:

    C# Windows Forms App (.NET Framework)

    Os resultados da pesquisa aparecem, listando tipos de projeto.

  5. Selecione o cartão C# Windows Forms App (.NET Framework). Verifique se o nome corresponde, com um ícone C# e, em seguida, o nome Windows Forms App (.NET Framework). Em seguida, clique no botão Avançar :

    No painel 'Criar um novo projeto', selecione 'C# > Windows Forms App (.NET Framework)'

  6. Na caixa de texto Nome do projeto , insira um nome de projeto. Este artigo de tutorial usa o nome WinForms_GettingStarted, como o nome do diretório do repositório para o projeto concluído.

  7. Na caixa de texto Local , insira um caminho, como "C:\Users\username\Documents\MyWebView2Projects".

  8. Na lista suspensa Framework, selecione .NET Framework 4.7.2 ou posterior, como .NET Framework 4.8:

    Preenchendo a janela 'Configurar seu novo projeto'

  9. Clique no botão Criar .

    A janela do Visual Studio é aberta, mostrando o projeto WinForms de linha de base no Gerenciador de Soluções e mostrando uma janela Formulário Designer:

    A janela do Visual Studio, mostrando o projeto WinForms da linha de base e um Designer do Forms

  10. SelecioneSalvar todos osarquivos> (Ctrl+Shift+S).

  11. Selecione Depurar>Iniciar Depuração (F5).

    Uma janela vazia do Form1 é aberta, do novo projeto WinForms:

    A janela vazia do Form1 do novo projeto WinForms

  12. Feche a janela Form1 .

Agora você tem um projeto WinForms vazio que é executado. Em seguida, configure o projeto para adicionar conteúdo do WebView2.

Etapa 4 – Instalar o SDK do WebView2

Para cada projeto do WebView2, você usa o gerenciador de pacotes NuGet no Visual Studio para adicionar o SDK do WebView2 ao projeto. Você instala o pacote NuGet do SDK do Microsoft.Web.WebView2 para uso pelo projeto atual.

Use o 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 (não no nome da solução acima) e selecione Gerenciar Pacotes NuGet:

    Gerenciar pacotes NuGet

    O Gerenciador de Pacotes NuGet é aberto no Visual Studio.

  2. Clique na guia Procurar no canto superior esquerdo.

  3. Desmarque a caixa de seleção Incluir pré-lançamento .

  4. Na barra de pesquisa, digite WebView2 e, em seguida, abaixo da barra de pesquisa, clique em Microsoft.Web.WebView2 para selecioná-lo:

    O Gerenciador de Pacotes NuGet no Visual Studio, instalando o pacote NuGet do SDK do Microsoft.Web.WebView2 para o projeto atual

    Para ampliar, clique com o botão direito do mouse >em Abrir imagem na nova guia.

  5. Clique no botão Instalar (ou Atualizar). A caixa de diálogo Alterações de Visualização é aberta:

    A caixa de diálogo Alterações de Visualização

  6. Clique no botão OK .

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

  8. Feche a janela Gerenciador de Pacotes do NuGet.

  9. Selecione Depurar>Iniciar Depuração (F5) para criar e executar o projeto.

    O projeto em execução exibe a mesma janela vazia de antes:

    A janela vazia do Form1 do novo projeto WinForms

  10. Feche a janela Form1 .

Você adicionou o SDK do WebView2 ao projeto, mas ainda não adicionou nenhum código WebView2 ao projeto.

Etapa 5 – Criar um único controle WebView2

Agora que o SDK do WebView2 está instalado para o projeto WinForms, adicione um controle WebView2 ao aplicativo da seguinte maneira:

O projeto inicial já tem um Form1.cs formulário, mas adicionaremos outro, como Form2.cs, para ver como fazer isso.

  1. SelecioneFormulário de Adição de Projeto> (Windows Forms).

  2. Na janela Adicionar Novo Item, à esquerda, selecione Itens >do Visual C#Windows Forms.

  3. À direita, selecione Formulário (Windows Forms)e clique no botão Adicionar:

    A janela 'Adicionar Novo Item', expandida para 'Visual C# Items' > 'Windows Forms', selecionando 'Formulário (Windows Forms)'

    O projeto agora tem um formulário adicional, com o nome Form2.csdo arquivo , mostrado no Formulário Designer e em Gerenciador de Soluções:

    O formulário adicionado, Form2.cs, no Formulário Designer e em Gerenciador de Soluções

  4. Clique na tela Do Formulário1 . Não usaremos o Form2.

  5. Selecione Exibir>Caixa de Ferramentas.

    Aqui é onde você adiciona conteúdo específico do WebView2 ao aplicativo:

  6. Na caixa de ferramentas, clique em WebView2 Windows Forms Control para expandir as opções.

    No Visual Studio 2017, por padrão, o WebView2 não é exibido na caixa de ferramentas. Para permitir que o WebView2 seja exibido na Caixa de Ferramentas, selecioneOpções> de Ferramentas>Geral> e defina a configuração Caixa de Ferramentas Populada Automaticamente como True.

  7. Na caixa de ferramentas, clique ou arraste o controle WebView2 para a tela Forms Designer do controle adicionado, como Form2.cs:

    Caixa de ferramentas que exibe o WebView2

  8. Arraste os lados do controle WebView2 para fazer com que ele preencha quase toda a tela.

  9. Verifique se o novo controle WebView2 no formulário está selecionado. No painel Propriedades , na seção Design , defina a propriedade (Name) como WebView (minúscula 'w', capital 'V', sem sufixo numérico). O controle pode inicialmente ser nomeado outra coisa, como WebView21. Use os botões de opção de classificação categorizada e alfabética conforme necessário para encontrar propriedades:

    Propriedades do controle WebView2

  10. No painel Propriedades , na seção Misc , defina a propriedade Source como https://www.microsoft.com. A propriedade Source define a URL inicial que será exibida no controle WebView2.

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

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

    O controle WebView2 exibe conteúdo de https://www.microsoft.com, em um controle WebView2 no formulário Windows Forms, com um Link de conteúdo Skip to main se você pressionou Alt+Tab para alternar para a janela:

    Alt+Tab faz com que o aplicativo de exemplo exiba inicialmente um link 'Ignorar para main conteúdo'

  13. Se necessário, clique no link Ignorar para main conteúdo.

    O controle WebView2 exibe conteúdo de https://www.microsoft.com, em um controle WebView2 no formulário Windows Forms:

    O aplicativo de exemplo exibe o site da Microsoft

  14. Feche a janela Form1 .

Se você estiver trabalhando em um monitor de alta resolução, talvez seja necessário configurar seu aplicativo Windows Forms para alto suporte a DPI.

Etapa 6 – Adicionar controles e eventos de redimensionamento da janela de processo

Adicione mais controles ao formulário Windows Forms da caixa de ferramentas e processe eventos de redimensionamento da janela da seguinte maneira.

  1. Selecione Exibir>Caixa de Ferramentas ou clique na guia Caixa de Ferramentas à esquerda.

  2. Na caixa de ferramentas, clique em Controles Comuns.

    Adicione um controle de caixa de texto, da seguinte maneira:

  3. Arraste o controle TextBox para a tela Designer formulário Form1.cs.

  4. Verifique se o controle TextBox tem foco.

  5. No painel Propriedades , na seção Design , altere o (Nome) (provavelmente de textBox1) para addressBar.

    Adicione um controle de botão, da seguinte maneira:

  6. Arraste um controle button para a tela Designer formulário Form1.cs.

  7. Verifique se o controle de botão tem foco.

  1. No painel Propriedades , na seção Aparência em negrito (cerca de 15 propriedades para baixo), altere a propriedade Texto (provavelmente de button1) para Go!

    Alinhe a caixa de texto e o botão existente, da seguinte maneira:

  2. Posicione a caixa de texto no lado esquerdo do formulário, alinhada verticalmente com o botão, conforme mostrado abaixo:

    Designer WinForms

  3. Redimensione a caixa de texto conforme mostrado:

    Caixa de texto e botão do designer winForms

  4. Clique em Exibir>Código para abrir Form1.cs.

    Defina Form_Resize para manter os controles no local quando a janela do aplicativo for redimensionada, da seguinte maneira.

  5. Exclua o seguinte código:

       public Form1()
{
   InitializeComponent();
}

  6. Cole esse código no mesmo local:

    public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);
}

private void Form_Resize(object sender, EventArgs e)
{
   webView.Size = this.ClientSize - new System.Drawing.Size(webView.Location);
   goButton.Left = this.ClientSize.Width - goButton.Width;
   addressBar.Width = goButton.Left - addressBar.Left;
}

    Form_Resize código adicionado

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

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

    Uma janela do Form1 é exibida, exibindo o conteúdo da página da Web de https://www.microsoft.com:

    Uma janela WinForm do Form1 exibindo o conteúdo da página da Web de microsoft.com

    Se você pressionar Alt+Tab para alternar para a janela Form1, talvez seja necessário clicar no link Ignorar para main conteúdo adicionado.

  9. Role a janela para cima e para baixo com a roda do mouse. Os controles de entrada permanecem em vigor.

  10. Arraste o canto da janela para redimensioná-lo. A caixa de texto altera a largura.

  11. Feche a janela Form1 .

Etapa 7 – Navegação

Permitir que os usuários alterem a URL que o controle WebView2 exibe, lendo o texto inserido na caixa de texto, para servir como uma barra de endereços.

  1. Selecione Exibir>Código para que Form1.cs esteja aberto no editor de código.

  2. No Form1.cs, adicione o CoreWebView2 namespace inserindo o seguinte código na parte superior do arquivo como linha 1:

    using Microsoft.Web.WebView2.Core;

  3. Selecione a guia Form1.cs [Design] e clique duas vezes no Go! botão. O goButton_Click método é adicionado no Form1.cs arquivo.

  4. Cole o seguinte código no arquivo para substituir o método vazio goButton_Click , de modo que o corpo do método seja o seguinte:

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

    Agora, a goButton_Click função navegará pelo controle WebView2 até a URL inserida na caixa de texto da barra de endereços.

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

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

  7. Na barra de endereços, insira uma URL que comece com https, como https://www.bing.com, e clique no botão Ir!

    bing.com

    O controle WebView2 mostra o conteúdo da página da Web para a URL.

  8. Na barra de endereços, insira uma cadeia de caracteres que não comece com http, como www.bing.com, e clique no botão Ir!

    Exceção de argumento devido à inserção de uma não URL

    Um ArgumentException será lançado se a URL não começar com http:// ou https://.

  9. Selecione Depurar>Parar Depuração ou clique em Continuar. A janela Form1 fecha.

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

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

Eventos de navegação

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

Observação

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

Para demonstrar como usar os eventos, comece registrando um manipulador para NavigationStarting isso cancela todas as solicitações que não usam HTTPS.

  1. No Form1.cs, atualize o Form1() construtor para corresponder ao código a seguir e adicione a EnsureHttps(sender, args) função abaixo do construtor, da seguinte maneira:

    public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);

   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. 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, insira uma URL que comece com https, como https://www.bing.com, e clique no botão Ir!

    A URL https carrega; o conteúdo da Web muda do padrão, Microsoft.com, para Bing.com.

  5. Na barra de endereços, insira uma URL que comece com http, como http://www.microsoft.com, e clique no botão Ir!

    A URL http não é carregada; a página da Web Bing.com permanece exibida. Por outro lado, a entrada no http://www.microsoft.com Microsoft Edge funciona; ela redireciona para o site https para Microsoft.com.

  6. Na barra de endereços, insira uma URL que comece com https, como https://www.microsoft.com, e clique no botão Ir!

    A URL https carrega; a página da Web Microsoft.com agora é exibida, já que você adicionou os 's' após 'http'.

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 JavaScript injetado após a criação do objeto global.

  • Execute o JavaScript injetado antes que qualquer outro script incluído no documento HTML seja executado.

Por exemplo, adicione um script que envia um alerta quando um usuário navega para um site que não é HTTPS, da seguinte maneira:

  1. Modifique a EnsureHttps função para adicionar a seguinte linha que contém 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;
   }
}

    A linha adicionada injeta um script no conteúdo da Web que usa o método ExecuteScriptAsync . O script adicionado é:

    alert('{uri} is not safe, try an https link')

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

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

  4. Tente ir para http://www.bing.com (com http em vez de https prefixo).

    O aplicativo exibe um alerta:

    Um alerta http, que diz tentar https 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 ser usados postMessage para se comunicar entre si da seguinte maneira:

  • O conteúdo da Web em um controle WebView2 pode ser usado window.chrome.webview.postMessage para postar uma mensagem no host. 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. Essas 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 Form1.cs, atualize o Form1() construtor e crie uma InitializeAsync() função abaixo dele, correspondendo ao seguinte código:

    public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);
   webView.NavigationStarting += EnsureHttps;
   InitializeAsync();
}

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

    A InitializeAsync função aguarda EnsureCoreWebView2Async, pois a inicialização de CoreWebView2 é assíncrona.

    Em seguida, registre um manipulador de eventos para responder a WebMessageReceived. Esse manipulador de eventos será registrado após CoreWebView2 a inicialização.

  2. Em Form1.cs, atualize InitializeAsynce adicione UpdateAddressBar abaixo, da seguinte maneira:

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

    Em seguida, para que o WebView2 envie e responda à mensagem da Web, depois CoreWebView2 de inicializado, o host injetará um script no conteúdo da Web para:

    • Envie a URL para o host usando postMessage.

    • Registre um manipulador de eventos para exibir uma mensagem enviada do host, em uma caixa de alerta, antes de exibir o conteúdo da página da Web.

  3. No Form1.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));");
}

  4. SelecioneSalvar todos osarquivos> (Ctrl+Shift+S) para salvar alterações.

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

  6. Insira uma URL, como https://www.bing.com:

    A URL da barra de endereços atualizada inicialmente é exibida em uma caixa de alerta

    Um alerta é exibido inicialmente, mostrando a URL resultante enviada do site do host.

  7. Clique no botão OK .

    O controle WebView2 agora exibe a nova URL na barra de endereços e o conteúdo da página da Web da URL é exibido no controle WebView2 na janela WinForms:

    O aplicativo exibe a URL na barra de endereços

    • Quando o aplicativo é iniciado, a URL padrão é https://www.microsoft.com, e o endereço exibido resultante mostra a localidade, como https://www.microsoft.com/en-us/.

    • Se você inserir https://www.bing.com, o endereço resultante será uma variante, como https://www4.bing.com/?form=DCDN.

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

Distribuindo um aplicativo WebView2

Se você distribuir o aplicativo que resulta deste tutorial, precisará distribuir o Runtime do WebView2 junto com seu aplicativo. O Runtime do WebView2 seria instalado automaticamente em computadores de usuário. Para obter mais informações, confira Distribuir seu aplicativo e o Runtime do WebView2.

Confira também