Feedback Edit

Get started with WebView2 in WinUI 3 (Windows App SDK) apps

  • Article
  • 7 minutes to read

This article covers how to set up your development tools and create an initial WebView2 app for WinUI 3 (Windows App SDK), and learn about WebView2 concepts along the way.

Step 1 - Install Visual Studio and the Windows App SDK

Even if you have Visual Studio installed, read the following page and possibly update your software.

  1. In a new window or tab, open the page Install tools for the Windows App SDK and then follow the steps on that page, to install Microsoft Visual Studio, such as Visual Studio 2022.
  1. If needed, in a new window or tab, see Install Visual Studio in Set up your Dev environment for WebView2.

Return from that page and continue the steps below.

Turning on Developer Mode:

  1. When Visual Studio opens at some point during the present article's steps, you might be prompted to turn on Developer Mode for your computer. For more information, if needed, see Enable your device for development, at Build desktop apps for Windows.

Step 2 - Install a preview channel of Microsoft Edge

  1. Install the WebView2 Runtime or any Microsoft Edge preview channel (Beta, Dev, or Canary) installed on Windows 10 version 1803 (build 17134) or later.

Return from that page and continue the steps below.

Step 3 - Create the project in Visual Studio

To create a WebView2 app, start by creating a basic desktop project, to create a desktop app that contains a single main window:

  1. Open Visual Studio (not Visual Studio Code).

  2. In Visual Studio, click Create a new project.

  3. In the project filter menus, choose C#. Windows, and WinUI.

    Create a new WinUI project using Visual Studio.

  4. Click Blank App, Packaged (WinUI in Desktop) > Next.

  5. Enter a project name.

  6. Change Location and Solution name default values as needed.

  7. Click Create.

  8. In New Universal Windows Platform Project, select the following values:

    • Target version: Windows 10, version 1903 (build 18362) or later.

    • Minimum version: Windows 10, version 1803 (build 17134).

  9. Click OK.

    The New Universal Windows Platform Project dialog with selected values for Target version and Minimum version:

    The New Universal Windows Platform Project dialog with selected values for Target version and Minimum version.

    Solution Explorer displays the two new projects that were generated:

    • Your project name (Desktop). The Desktop project contains the code for your app. The App.xaml.cs file defines an Application class that represents your app instance. The MainWindow.xaml.cs file defines a MainWindow class that represents the main window displayed by your app instance. The classes derive from types in the Microsoft.UI.Xaml namespace of WinUI.

    • Your project name (Package). The Package project is a Windows Application Packaging Project that is configured to build the app into an MSIX package for deployment. The project contains the package manifest for your app, and is the startup project for your solution by default. For more information, see Set up your desktop application for MSIX packaging in Visual Studio and Package manifest schema reference for Windows 10.

  10. In Solution Explorer, open MainWindow.xaml.

  11. Select File > Save All (Ctrl+Shift+S) to save the project.

  12. Press F5 to build and run the project.

Step 4 - Add a WebView2 control to your project

The WindowsAppSDK includes the WebView2 SDK and control, and you shouldn't need to separately install the WebView2 SDK. Edit the MainWindow.xaml and MainWindow.xaml.cs files to a WebView2 control to the sample app, as follows.

  1. In Visual Studio, in Solution Explorer, select MainWindow.xaml to open it in the code editor.

    Add the WebView2 XAML namespace, as follows:

  2. In the MainWindow.xaml file, insert the following line inside the <Window/> tag:

    xmlns:controls="using:Microsoft.UI.Xaml.Controls"

    Make sure your code in MainWindow.xaml is similar to the following:

    <Window
      x:Class="WinUI_Sample.MainWindow"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:local="using:WinUI_Sample"
      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
      mc:Ignorable="d"
      xmlns:controls="using:Microsoft.UI.Xaml.Controls"
      >

      <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" VerticalAlignment="Center">
      <Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
      </StackPanel>

</Window>

  3. To add the WebView2 control, replace the <StackPanel> tags with the following code. The Source property sets the initial URI that's displayed in the WebView2 control.

    <Grid>

   <Grid.RowDefinitions>
      <RowDefinition Height="Auto"/>
      <RowDefinition Height="*"/>
   </Grid.RowDefinitions>
   <Grid.ColumnDefinitions>
      <ColumnDefinition Width="*"/>
      <ColumnDefinition Width="Auto"/>
   </Grid.ColumnDefinitions>

   <controls:WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
      Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/>

</Grid>

  4. In MainWindow.xaml.cs, comment out the following line:

       // myButton.Content = "Clicked";

  5. Select File > Save All (Ctrl+Shift+S), to save the project.

  6. Press F5, to build and run the project.

  7. Make sure your WebView2 control displays https://www.microsoft.com.

The sample application with WebView2 control displays the Microsoft website, https://www.microsoft.com:

The sample app displays the Microsoft website.

Step 5 - Add navigation controls

To allow users to control the webpage that is displayed in your WebView2 control, add an address bar to the sample app, as follows:

  1. In MainWindow.xaml, paste the following code inside the <Grid> element that contains the WebView2 element:

       <TextBox Name="addressBar" Grid.Column="0"/>
   <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>

    Make sure your <Grid> element in the MainWindow.xaml file matches the following:

    <Grid>

   <Grid.RowDefinitions>
      <RowDefinition Height="Auto"/>
      <RowDefinition Height="*"/>
   </Grid.RowDefinitions>
   <Grid.ColumnDefinitions>
      <ColumnDefinition Width="*"/>
      <ColumnDefinition Width="Auto"/>
   </Grid.ColumnDefinitions>

   <TextBox Name="addressBar" Grid.Column="0"/>
   <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>

   <WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
      Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/>

</Grid>

  2. In MainWindow.xaml.cs, copy the following code into myButton_Click. This code navigates the WebView2 control to the URL entered in the address bar.

    private void myButton_Click(object sender, RoutedEventArgs e)
{
   try
   {
      Uri targetUri = new Uri(addressBar.Text);
      MyWebView.Source = targetUri;
   }
   catch (FormatException ex)
   {
      // Incorrect address entered.
   }
}

  3. Select File > Save All (Ctrl+Shift+S) to save the project.

  4. Press F5 to build and run the project.

  5. Enter a new URL in the address bar, and then choose Go. For example, enter https://www.bing.com.

    The sample app displays the Bing website. The address bar displays the URL https://www.bing.com:

    The sample app displays the Bing website.

  6. Enter an incomplete URL in the address bar, such as bing.com.

    An ArgumentException exception is thrown, because the URL doesn't start with http:// or https://.

  7. Close the app.

Step 6 - Navigation events

In this section, you add code to import the WebView2 Core library.

  1. Add the following line to the top of MainWindow.xaml.cs:

    using Microsoft.Web.WebView2.Core;

    Apps that host WebView2 controls listen for the following events that are raised by WebView2 controls during webpage navigation:

    • NavigationStarting
    • SourceChanged
    • ContentLoading
    • HistoryChanged
    • NavigationCompleted

    Note

    If an HTTP redirect occurs, there are multiple NavigationStarting events in a row.

    For more information, see Navigation events for WebView2 apps.

    When errors occur, the following events are raised, and an error webpage might be displayed:

    • SourceChanged
    • ContentLoading
    • HistoryChanged

    As an example of how to use the events, register a handler for NavigationStarting that cancels any non-HTTPS requests, as follows:

  2. In MainWindow.xaml.cs, modify the constructor to register EnsureHttps, and add the EnsureHttps function so that it matches the following:

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

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

  3. Select File > Save All (Ctrl+Shift+S) to save the project.

  4. Press F5 to build and run the project.

  5. Enter an HTTP URL, such as http://microsoft.com.

    Navigation is blocked to HTTP sites.

  6. Enter an HTTPS URL, such as https://microsoft.com.

    Navigation is allowed for HTTPS sites.

WinRT CoreWebView2 object availability

The WinRT CoreWebView2 object might not be available with the release of the WebView2 API. The WebView2 Spec lists which of the APIs are available for WebView2.

Step 7 - Scripting

You can use host apps to inject JavaScript code into WebView2 controls at runtime. You can task WebView2 to run arbitrary JavaScript or add initialization scripts. The injected JavaScript applies to all new top-level documents and any child frames until the JavaScript is removed. The injected JavaScript is run with specific timing, to either:

  • Run the injected JavaScript after the creation of the global object.

  • Run the injected JavaScript before running any other script that's included in the HTML document.

As an example, next, you add scripts that send an alert when a user tries to open non-HTTPS sites. To do this, you inject a script into the web content that uses ExecuteScriptAsync.

  1. Modify the EnsureHttps function as follows:

    private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args)
{
   String uri = args.Uri;
   if (!uri.StartsWith("https://"))
   {
      MyWebView.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
      args.Cancel = true;
   }
   else
   {
      addressBar.Text = uri;
   }
}

  2. Select File > Save All (Ctrl+Shift+S) to save the project.

  3. Press F5 to build and run the project.

  4. Try to open a non-HTTPS URL, such as http://www.bing.com.

    The app's WebView2 control displays an alert dialog for non-HTTPS websites, saying that the non-HTTPS uri is not safe:

    Sample app WebView2 control displays an alert dialog for non-HTTPS websites.

Congratulations, you built your first WebView2 app!

See also

developer.microsoft.com:

Local pages:

GitHub: