Get started with WebView2 in WinUI 3 (Windows App SDK) apps
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.
- Corresponding Get Started sample at GitHub: Getting Started with WebView2 in WinUI3 (WinUI3_GettingStarted/WinUI_Sample.sln)
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.
- 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.
- 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:
- 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
- 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:
Open Visual Studio (not Visual Studio Code).
In Visual Studio, click Create a new project.
In the project filter menus, choose C#. Windows, and WinUI.
Click Blank App, Packaged (WinUI in Desktop) > Next.
Enter a project name.
Change Location and Solution name default values as needed.
Click Create.
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).
Click OK.
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 anApplication
class that represents your app instance. TheMainWindow.xaml.cs
file defines aMainWindow
class that represents the main window displayed by your app instance. The classes derive from types in theMicrosoft.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.
In Solution Explorer, open
MainWindow.xaml
.Select File > Save All (
Ctrl
+Shift
+S
) to save the project.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.
In Visual Studio, in Solution Explorer, select
MainWindow.xaml
to open it in the code editor.Add the WebView2 XAML namespace, as follows:
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>
To add the WebView2 control, replace the
<StackPanel>
tags with the following code. TheSource
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>
In
MainWindow.xaml.cs
, comment out the following line:// myButton.Content = "Clicked";
Select File > Save All (Ctrl+Shift+S), to save the project.
Press F5, to build and run the project.
Make sure your WebView2 control displays https://www.microsoft.com.
The sample application with WebView2 control displays the Microsoft website, https://www.microsoft.com:
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:
In
MainWindow.xaml
, paste the following code inside the<Grid>
element that contains theWebView2
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 theMainWindow.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>
In
MainWindow.xaml.cs
, copy the following code intomyButton_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. } }
Select File > Save All (
Ctrl
+Shift
+S
) to save the project.Press F5 to build and run the project.
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:
Enter an incomplete URL in the address bar, such as
bing.com
.An
ArgumentException
exception is thrown, because the URL doesn't start withhttp://
orhttps://
.Close the app.
Step 6 - Navigation events
In this section, you add code to import the WebView2 Core library.
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:In
MainWindow.xaml.cs
, modify the constructor to registerEnsureHttps
, and add theEnsureHttps
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; } }
Select File > Save All (
Ctrl
+Shift
+S
) to save the project.Press F5 to build and run the project.
Enter an HTTP URL, such as
http://microsoft.com
.Navigation is blocked to HTTP sites.
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.
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; } }
Select File > Save All (
Ctrl
+Shift
+S
) to save the project.Press F5 to build and run the project.
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:
Congratulations, you built your first WebView2 app!
See also
developer.microsoft.com:
- Microsoft Edge WebView2 - initial introduction to WebView2 features at developer.microsoft.com.
Local pages:
- Introduction to Microsoft Edge WebView2 - overview of features.
- See also in Introduction to Microsoft Edge WebView2.
- Manage user data folders
- Sample Code for WebView2 - a guide to the
WebView2Samples
repo. - Development best practices for WebView2 appsDevelopment best practices
GitHub:
- Getting Started with WebView2 in WinUI3
- Spec: The WebView2 Xaml control - the WinUI 3.0 version of the WebView2 control.
- microsoft-ui-xaml repo > Issues - to enter WinUI-specific feature requests or bugs.
Feedback
Submit and view feedback for