Aplicativo de exemplo WinUI 3 (SDK do Windows App)

Nome da amostra: WebView2_WinUI3_Sample
Diretório do repositório: WebView2_WinUI3_Sample
Arquivo da solução: WebView2_WinUI3_Sample.sln

Este exemplo demonstra o uso de um controle WebView2 em um aplicativo empacotado WinUI 3 (SDK do Aplicativo do Windows App).

Aplicativo de exemplo

Este exemplo também permite que você envie o aplicativo com um WebView2 Runtime de versão fixa, em vez de usar qualquer versão do WebView2 Runtime instalada e em execução no computador do usuário.

Pacotes NuGet e componentes de carga de trabalho

Antes de criar, faremos o seguinte:

Atualize o pacote NuGet Microsoft.Windows.SDK.BuildTools para o projeto e para o projeto (Pacote).
Atualize o pacote NuGet Microsoft.WindowsAppSDK para o projeto e para o projeto (Pacote).
Instale o componente "SDK do Windows 10" da carga de trabalho "Desenvolvimento de aplicativos do Windows", se ainda não estiver instalado.

Diretórios

Diretório	Conteúdos
WebView2_WinUI3_Sample	Código do projeto
WebView2_WinUI3_Sample (pacote)	Projeto de embalagem e distribuição
WebView2_WinUI3_Sample (Package)\FixedRuntime	(Opcional) WebView2 Runtime Corrigido
WebView2_WinUI3_Sample (Pacote)\FixedRuntime\130.0.2849.39	(Opcional) Exemplo de tempo de execução WebView2 corrigido

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.

Etapa 2: Clonar ou baixar o repositório WebView2Samples

Se ainda não tiver feito isso, clone ou baixe o WebView2Samples repositório para sua unidade local. Em uma janela ou guia separada, consulte Baixar o repositório WebView2Samples em Configurar seu ambiente de desenvolvimento para WebView2. Siga as etapas nesta seção e, em seguida, retorne a esta página e continue abaixo.

Etapa 3: Abrir a solução no Visual Studio

Essas etapas iniciais sobre o repositório e o branch não são necessárias, mas são uma boa prática para evitar alterar o código que está no branch "main" da cópia clonada do repositório WebView2Samples. Isso permite que você altere os arquivos do projeto (para compilar e executar a amostra), mantendo o código que está no branch "main" idêntico ao repositório.

Você pode executar estas etapas em qualquer ferramenta para operações git, como:

GitHub Desktop.
A guia Alterações do Git ao lado da guia Gerenciador de Soluções, no canto inferior direito do Visual Studio.
O prompt de comando do git bash.

Para abrir o arquivo de solução do exemplo em uma ramificação de trabalho:

No GitHub Desktop, na lista Repositório atual no canto superior esquerdo, selecione o repositório WebView2Samples .
Clique em Buscar origem na parte superior central da janela.
No menu branch atual , crie um branch de trabalho, como user/myGithubUsername/winui3-sample , e alterne para ele.

Agora você está seguro em uma ramificação de trabalho em vez da ramificação "principal" e está livre para começar a alterar os arquivos do exemplo.
Na unidade local, abra o .sln arquivo no Visual Studio.

Exemplos de localizações do .sln arquivo: Se você clonou o repositório, o nome do diretório do repositório é /WebView2Samples/:

<your-repos-directory>/WebView2Samples/SampleApps/WebView2_WinUI3_Sample/WebView2_WinUI3_Sample.sln

Se você baixou o repositório, o nome do diretório do repositório será /WebView2Samples-main/, representando o branch "main":

<your-repos-directory>/WebView2Samples-main/SampleApps/WebView2_WinUI3_Sample/WebView2_WinUI3_Sample.sln

Etapa 4: Atualizar os pacotes NuGet

Em Gerenciador de Soluções, clique com o botão direito do mouse no projeto WebView2_WinUI3_Sample e selecione Gerenciar Pacotes NuGet.

No Visual Studio, o Gerenciador de Pacotes NuGet é aberto:

A guia Instalado é selecionada, listando os pacotes NuGet:
- Microsoft.Windows.SDK.BuildTools
- Microsoft.WindowsAppSDK
- Microsoft.Web.WebView2
Selecione a guia Atualizações.
No canto superior esquerdo, marque a caixa de seleção Selecionar todos os pacotes .
À direita dessa caixa de seleção, clique no botão Atualizar .

A caixa de diálogo Visualizar Alterações é aberta.
Clique no botão Aplicar .

A caixa de diálogo Aceitação de licença é aberta.
Clique no botão Aceito .

Os pacotes NuGet são atualizados e o número ao lado da guia Atualizações é removido.

Clique no menu Exibir e, em seguida, clique no item de menu Saída .

Na guia Saída , na lista suspensa Mostrar saída de , o Gerenciador de Pacotes está selecionado. A saída inclui linhas como:

Installing NuGet package Microsoft.Windows.SDK.BuildTools
Installing NuGet package Microsoft.WindowsAppSDK

Successfully uninstalled 'Microsoft.Windows.SDK.BuildTools
Successfully uninstalled 'Microsoft.WindowsAppSDK

Successfully installed 'Microsoft.Web.WebView2
Successfully installed 'Microsoft.Windows.SDK.BuildTools
Successfully installed 'Microsoft.WindowsAppSDK

Atualizar pacotes NuGet no projeto (Pacote)

Em Gerenciador de Soluções, clique com o botão direito do mouse no projeto WebView2_WinUI3_Sample (Pacote) e selecione Gerenciar Pacotes NuGet.
Selecione a guia Atualizações.
No canto superior esquerdo, marque a caixa de seleção Selecionar todos os pacotes .
À direita dessa caixa de seleção, clique no botão Atualizar .

A caixa de diálogo Visualizar Alterações é aberta.
Clique no botão Aplicar .

A caixa de diálogo Aceitação de licença é aberta.
Clique no botão Aceito .

Os pacotes NuGet são atualizados e o número ao lado da guia Atualizações é removido.
Clique no menu Exibir e, em seguida, clique no item de menu Saída .

Na guia Saída , na lista suspensa Mostrar saída de , o Gerenciador de Pacotes está selecionado. A saída inclui linhas como mostrado acima.
Feche a janela do Gerenciador de Pacotes NuGet .

Etapa 5: Instalar o SDK do Windows 10 ou outros componentes da carga de trabalho

Dependendo do que você instalou, talvez seja necessário instalar uma carga de trabalho do Visual Studio ou um componente de uma carga de trabalho, como o seguinte, para criar o exemplo.

Para instalar o componente SDK do Windows 10 da carga de trabalho de desenvolvimento de aplicativos do Windows:

No Visual Studio, clique no menu Ferramentas e, em seguida, clique no item de menu Obter Ferramentas e Recursos .

A janela do Visual Studio Installer é aberta.
Selecione o card de desenvolvimento de aplicativos do Windows, para que uma marca de seleção apareça.
Na árvore de detalhes da instalação à direita, marque a caixa de seleção do componente SDK do Windows 10 SDK 10.0.19041.0.
Clique no botão Modificar .

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

A caixa de diálogo Antes de começarmos (do Visual Studio Installer) é aberta, solicitando que você salve seu trabalho no Visual Studio.
Feche a janela principal do Visual Studio, salvando se necessário.
Na caixa de diálogo Antes de começar , clique no botão Repetir .

Após alguns minutos, o componente de carga de trabalho do SDK do Windows 10 10.0.19041.0 é baixado e instalado. O Visual Studio Installer diz "Todas as instalações estão atualizadas".

Etapa 6: compilar e executar o aplicativo

Abra a solução no Visual Studio 2022. Por exemplo, no Visual Studio Installer, na seção Visual Studio 2022, clique no botão Iniciar.

O inicializador do Visual Studio é aberto, com as seções Abrir recente e Começar.
Na seção Abrir recente , selecione WebView2_WinUI3_Sample.sln.

A solução abre no Visual Studio 2022.
Pressione F5.

No Gerenciador de Soluções, o projeto (Pacote) está em negrito, indicando que é o projeto padrão. O aplicativo é compilado e, em seguida, a janela do aplicativo WebView2_WinUI3_Sample (pacote) é aberta:

A mensagem "Navegação concluída" é exibida na parte inferior.
Na barra de endereços (uma caixa de texto), insira https://bing.com (uma URL HTTPS completa) e pressione Enter (equivalente a clicar no botão Ir ).

O controle WebView2 navega até o Bing e exibe "Navegação concluída" na parte inferior.

No Visual Studio, a janela Saída exibe mensagens como:
```
AddressBar_KeyDown [Enter]: https://bing.com
TryNavigate
TryCreateUri
Navigation complete
```

Etapa 7: confirmar alterações em seu branch de trabalho

Em uma ferramenta git como o GitHub Desktop, neste ponto, você pode confirmar as alterações e, opcionalmente, enviá-las para uma bifurcação do seu branch no GitHub. Esses tipos de operações são relevantes quando você modifica, experimenta e personaliza o exemplo. Isso também mantém seu branch de trabalho limpo e mantém seu clone do repositório organizado, para que você possa alternar para um exemplo diferente.

Para confirmar e enviar por push as alterações feitas no exemplo em seu branch de trabalho:

No Visual Studio, selecione Arquivo>Salvar Tudo (Ctrl+Shift+S).
No GitHub Desktop, insira uma breve mensagem do commit, como "updated, built, ran sample" e, em seguida, clique no botão Commit.
Selecione Repository>Push. Seu branch de trabalho é copiado da unidade local para o branch bifurcado do repositório WebView2Samples no GitHub.

Veja seu branch de trabalho no GitHub
No Microsoft Edge, vá para a bifurcação do repositório, como https://github.com/myGithubUsername/WebView2Samples/.
Clique no link [#] Branches e selecione o novo branch de trabalho, como user/myGithubUsername/winui3-sample.

Etapa 8: Inspecionar o código

Feche o aplicativo WebView2_WinUI3_Sample (Pacote).
No Gerenciador de Soluções, no WebView2_WinUI3_Sample projeto, clique duas vezes em cada .xaml arquivo e em seu .cs arquivo:
- App.xaml - Nenhum código WebView2.
  - App.cs - Código para usar um WebView2 Runtime de versão fixa.
- MainWindow.xaml - Elementos WebView2.
  - MainWindow.cs - Código WebView2.

Versões condensadas desses arquivos estão abaixo.

App.xaml

Não há nenhum código específico do WebView2 neste arquivo.

Listagem condensada

<Application
    x:Class="WebView2_WinUI3_Sample.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:WebView2_WinUI3_Sample">
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

App.cs

O código específico do WebView2 neste arquivo é comentado. Você pode remover o comentário dessas linhas para usar um Runtime de versão fixa; consulte Usando um WebView2 Runtime de versão fixa, abaixo.

Listagem condensada

namespace WebView2_WinUI3_Sample
{
    /// <summary>
    /// Provides application-specific behavior to supplement the default Application class.
    /// </summary>
    public partial class App : Application
    {
        /// <summary>
        /// Initializes the singleton application object.  Equivalent to main() or WinMain().
        /// </summary>
        public App()
        {
            this.InitializeComponent();

            // If you're shipping a fixed-version WebView2 Runtime with your app, un-comment the
            // following lines of code, and change the version number to the version number of the
            // WebView2 Runtime that you're packaging and shipping to users:

            // StorageFolder localFolder = Windows.ApplicationModel.Package.Current.InstalledLocation;
            // String fixedPath = Path.Combine(localFolder.Path, "FixedRuntime\\130.0.2849.39");
            // Debug.WriteLine($"Launch path [{localFolder.Path}]");
            // Debug.WriteLine($"FixedRuntime path [{fixedPath}]");
            // Environment.SetEnvironmentVariable("WEBVIEW2_BROWSER_EXECUTABLE_FOLDER", fixedPath);
        }

        /// <summary>
        /// Invoked when the application is launched normally by the end user.
        /// </summary>
        /// <param name="args">Details about the launch request and process.</param>
        protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
        {
            m_window = new MainWindow();
            m_window.Activate();
        }

        private Window m_window;
    }
}

MainWindow.xaml

A janela principal tem os seguintes elementos XAML como controles:

<TextBox> - A barra de endereços.
<Button> - O botão Ir .
<WebView2> - O controle WebView2.
<TextBlock>- A barra de status.

Listagem condensada

<Window
    xmlns:local="using:WebView2_WinUI3_Sample">
    <Grid>
        <Grid.RowDefinitions>
        </Grid.RowDefinitions>
        <Grid Grid.Row="0" Background="LightGray">
            <TextBox Grid.Column="0"  x:Name="AddressBar" KeyDown="AddressBar_KeyDown" VerticalAlignment="Center" Margin="10,0,0,0"/>
            <Button Grid.Column="1" x:Name="Go" Content="Go" Click="Go_OnClick" VerticalAlignment="Center" HorizontalAlignment="Center"/>
        </Grid>

        <WebView2 x:Name="WebView2" Grid.Row="1"/>

        <Rectangle Grid.Row="2" Fill="LightGray"/>
        <TextBlock x:Name="StatusBar" Text="WebView2" VerticalAlignment="Center" Grid.Row="2" Margin="10,0,10,0"/>
    </Grid>
</Window>

MainWindow.cs

A classe MainWindow tem os seguintes métodos:

Construtor
StatusUpdate
WebView2_CoreWebView2Initialized
WebView2_NavigationCompleted
TryCreateUri
TryNavigate
Go_OnClick
AddressBar_KeyDown
SetTitle
GetWebView2Version

Trechos ou versões condensadas desses métodos estão abaixo.

Classe MainWindow

using Microsoft.Web.WebView2.Core;

namespace WebView2_WinUI3_Sample
{
    /// <summary>
    /// An empty window that can be used on its own or navigated to within a Frame.
    /// </summary>
    public sealed partial class MainWindow : Window
    {

Construtor

public MainWindow()
{
    this.InitializeComponent();

    Closed += (obj, eventArgs) =>
    {
        if (WebView2 != null)
        {
            // Ensure that WebView2 resources are released when
            // the MainWindow is closed. 
            // WebView2 lifecycle in WinUI3 and the Close() method:
            // https://github.com/microsoft/microsoft-ui-xaml/issues/4752#issuecomment-819687363
            WebView2.Close();
        }
    };

    AddressBar.Text = "https://developer.microsoft.com/microsoft-edge/webview2/";

    WebView2.NavigationCompleted += WebView2_NavigationCompleted;
    WebView2.CoreWebView2Initialized += WebView2_CoreWebView2Initialized;

    WebView2.Source = new Uri(AddressBar.Text);
    StatusUpdate("Ready");
    SetTitle();
}

StatusUpdate

private void StatusUpdate(string message)
{
    StatusBar.Text = message;
    Debug.WriteLine(message);
}

WebView2_CoreWebView2Initialized

private void WebView2_CoreWebView2Initialized(WebView2 sender, CoreWebView2InitializedEventArgs args)
{
    if (args.Exception != null)
    {
        StatusUpdate($"Error initializing WebView2: {args.Exception.Message}");
    }
    else
    {
        SetTitle(sender);
    }
}

WebView2_NavigationCompleted

private void WebView2_NavigationCompleted(WebView2 sender, CoreWebView2NavigationCompletedEventArgs args)
{
    StatusUpdate("Navigation complete");

    // Update the Address bar with the full URL that was navigated to.
    AddressBar.Text = sender.Source.ToString();
}

TryCreateUri

private bool TryCreateUri(String potentialUri, out Uri result)
{
    StatusUpdate("TryCreateUri");

    Uri uri;
    if ((Uri.TryCreate(potentialUri, UriKind.Absolute, out uri) || Uri.TryCreate("http://" + potentialUri, UriKind.Absolute, out uri)) &&
        (uri.Scheme == Uri.UriSchemeHttp || uri.Scheme == Uri.UriSchemeHttps))
    {
        result = uri;
        return true;
    }
    else
    {
        StatusUpdate("Unable to configure URI");
        result = null;
        return false;
    }
}

TryNavigate

private void TryNavigate()
{
    StatusUpdate("TryNavigate");

    Uri destinationUri;
    if (TryCreateUri(AddressBar.Text, out destinationUri))
    {
        WebView2.Source = destinationUri;
    }
    else
    {
        StatusUpdate("URI couldn't be figured out use it as a bing search term");

        String bingString = $"https://www.bing.com/search?q={Uri.EscapeDataString(AddressBar.Text)}";
        if (TryCreateUri(bingString, out destinationUri))
        {
            AddressBar.Text = destinationUri.AbsoluteUri;
            WebView2.Source = destinationUri;
        }
        else
        {
            StatusUpdate("URI couldn't be configured as bing search term, giving up");
        }
    }
}

Go_OnClick

private void Go_OnClick(object sender, RoutedEventArgs e)
{
    StatusUpdate("Go_OnClick: " + AddressBar.Text);

    TryNavigate();
}

AddressBar_KeyDown

private void AddressBar_KeyDown(object sender, KeyRoutedEventArgs e)
{
    if (e.Key == Windows.System.VirtualKey.Enter)
    {
        StatusUpdate("AddressBar_KeyDown [Enter]: " + AddressBar.Text);

        e.Handled = true;
        TryNavigate();
    }
}

SetTitle

private void SetTitle(WebView2 webView2 = null)
{
    var packageDisplayName = Windows.ApplicationModel.Package.Current.DisplayName;
    var webView2Version = (webView2 != null) ? " - " + GetWebView2Version(webView2) : string.Empty;
    Title = $"{packageDisplayName}{webView2Version}";
}

GetWebView2Version

private string GetWebView2Version(WebView2 webView2)
{
    var runtimeVersion = webView2.CoreWebView2.Environment.BrowserVersionString;

    CoreWebView2EnvironmentOptions options = new CoreWebView2EnvironmentOptions();
    var targetVersionMajorAndRest = options.TargetCompatibleBrowserVersion;
    var versionList = targetVersionMajorAndRest.Split('.');
    if (versionList.Length != 4)
    {
        return "Invalid SDK build version";
    }
    var sdkVersion = versionList[2] + "." + versionList[3];

    return $"{runtimeVersion}; {sdkVersion}";
}

Usando um WebView2 Runtime de versão fixa

Se você quiser enviar uma versão fixa do WebView2 runtime com seu aplicativo, precisará incluí-la em seu projeto. Consulte Distribuir seu aplicativo e o WebView2 Runtime.

As etapas a seguir mostram o número 130.0.2849.39da versão do Runtime; você alterará esse número para qualquer versão que esteja empacotando e enviando.

Para usar um Runtime de versão fixa:

Inclua o WebView2 Runtime fixo no projeto de pacote:
```
\WebView2_WinUI3_Sample\WebView2_WinUI3_Sample (Package)\FixedRuntime\130.0.2849.39\
```
Acima, use a versão que você está enviando, em vez de 130.0.2849.39.
Atualize o arquivo de projeto wapproj de pacote para a versão que você está usando (use sua versão em vez de 130.0.2849.39):
```
< Content Include="FixedRuntime\130.0.2849.39\\**\*.*" >
```

Em App.xaml.cs, remova o comentário das cinco linhas de código comentadas abaixo do comentário, para habilitar a substituição do Runtime:

public App()
{
   this.InitializeComponent();

   // If you're shipping a fixed-version WebView2 Runtime with your app, un-comment the
   // following lines of code, and change the version number to the version number of the
   // WebView2 Runtime that you're packaging and shipping to users:

   // StorageFolder localFolder = Windows.ApplicationModel.Package.Current.InstalledLocation;
   // String fixedPath = Path.Combine(localFolder.Path, "FixedRuntime\\130.0.2849.39");
   // Debug.WriteLine($"Launch path [{localFolder.Path}]");
   // Debug.WriteLine($"FixedRuntime path [{fixedPath}]");
   // Environment.SetEnvironmentVariable("WEBVIEW2_BROWSER_EXECUTABLE_FOLDER", fixedPath);
}

No código acima, altere o número de 130.0.2849.39 versão para a versão que você está enviando.

Confira também

Comentários

Esta página foi útil?

Last updated on 2026-08-24

Aplicativo de exemplo WinUI 3 (SDK do Windows App)

Pacotes NuGet e componentes de carga de trabalho

Diretórios

Etapa 1: Instalar o Visual Studio 2022 mais recente

Etapa 2: Clonar ou baixar o repositório WebView2Samples

Etapa 3: Abrir a solução no Visual Studio

Etapa 4: Atualizar os pacotes NuGet

Etapa 5: Instalar o SDK do Windows 10 ou outros componentes da carga de trabalho

Etapa 6: compilar e executar o aplicativo

Etapa 7: confirmar alterações em seu branch de trabalho

Etapa 8: Inspecionar o código

App.xaml

Listagem condensada

App.cs

Listagem condensada

MainWindow.xaml

Listagem condensada

MainWindow.cs

Classe MainWindow

Construtor

StatusUpdate

WebView2_CoreWebView2Initialized

WebView2_NavigationCompleted

TryCreateUri

TryNavigate

Go_OnClick

AddressBar_KeyDown

SetTitle

GetWebView2Version

Usando um WebView2 Runtime de versão fixa

Confira também

Comentários

Recursos adicionais