Erste Schritte mit WebView2 in WinUI 3-Apps (Windows App SDK)
In diesem Artikel wird erläutert, wie Sie Ihre Entwicklungstools einrichten und eine erste WebView2-App für WinUI 3 (Windows App SDK) erstellen und unterwegs mehr über WebView2-Konzepte erfahren.
In diesem Lernprogramm verwenden Sie die Visual Studio-Projektvorlage "Leere App, verpackt (WinUI in Desktop) ", um ein leeres WinUI 3-Projekt zu erstellen. Diese Projektvorlage verwendet das WindowsAppSDK, das das WebView2 SDK enthält. Sie fügen ein WebView2-Steuerelement hinzu. Anschließend fügen Sie eine Adressleiste und Logik hinzu, um ein Warndialogfeld anzuzeigen, wenn der Benutzer versucht, zu einer URL mit einem http://
Präfix zu navigieren.
Abgeschlossenes Projekt
Eine abgeschlossene Version dieses Lernprogrammprojekts (ab 2020) ist im WebView2Samples-Repository verfügbar:
- Beispielname: WinUI3_GettingStarted
- Repositoryverzeichnis: WinUI3_GettingStarted
- Lösungsdatei: WinUI_Sample.sln
Das vorliegende Lernprogramm wird aktualisiert und erstellt nur ein einzelnes Projekt, nicht ein zweites ,(Paket)"-Projekt wie 2020.
Schritt 1: Installieren von Visual Studio und der Windows App SDK
Auch wenn Sie Visual Studio installiert haben, lesen Sie die folgende Seite, und aktualisieren Sie möglicherweise Ihre Software, und installieren Sie Projektvorlagen.
- Öffnen Sie in einem neuen Fenster oder einer neuen Registerkarte die Seite "Installationstools für die Windows App SDK" und führen Sie dann die Schritte auf dieser Seite aus, um Microsoft Visual Studio, z. B. Visual Studio 2022, zu installieren.
- Wenn erforderlich, lesen Sie in einem neuen Fenster oder einer neuen Registerkarte die Informationen unter "Installieren von Visual Studio " in "Einrichten Ihrer Dev-Umgebung für WebView2".
Kehren Sie von dieser Seite zurück, und fahren Sie mit den nachstehenden Schritten fort.
Für dieses Beispiel müssen Sie das WebView2 SDK nicht separat installieren. Im Folgenden wählen Sie die Projektvorlage Blank App, Packaged (WinUI in Desktop) aus, die das WindowsAppSDK verwendet, das das WebView2 SDK enthält.
Schritt 2 : Installieren eines Vorschaukanals von Microsoft Edge
- Installieren Sie die WebView2-Runtime oder einen beliebigen Microsoft Edge Preview-Kanal (Beta, Dev oder Canary), der auf Windows 10 Version 1803 (Build 17134) oder höher installiert ist.
Kehren Sie von dieser Seite zurück, und fahren Sie mit den nachstehenden Schritten fort.
Schritt 3 : Erstellen eines leeren WinUI 3-Projekts
Um eine WebView2-App zu erstellen, erstellen Sie zunächst ein einfaches Desktopprojekt, um eine Desktop-App zu erstellen, die ein einzelnes Hauptfenster enthält:
Wenn Visual Studio nicht ausgeführt wird, starten Sie Visual Studio (nicht Visual Studio Code). Klicken Sie im Visual Studio-Startfenster auf die Registerkarte "Neue Projektkarte erstellen ". Das Fenster "Neues Projekt erstellen " wird geöffnet.
Wenn Visual Studio ausgeführt wird, wählen Sie "Neues > Projekt speichern" > aus. Das Dialogfeld " Neues Projekt erstellen " wird geöffnet.
Aktivieren des Entwicklermodus: Wenn Visual Studio zu einem bestimmten Zeitpunkt während der Schritte dieses Artikels geöffnet wird, werden Sie möglicherweise aufgefordert, den Entwicklermodus für Ihren Computer zu aktivieren. Weitere Informationen finden Sie bei Bedarf unter "Aktivieren Ihres Geräts für die Entwicklung" unter "Erstellen von Desktop-Apps für Windows".
Geben Sie im Dialogfeld " Neues Projekt erstellen " im Feld "Nach Vorlagen suchen " WinUI 3 in Desktop ein:
Klicken Sie auf die Karte " Leere App", "Verpackt" (WinUI in Desktop), um sie auszuwählen, und klicken Sie dann auf die Schaltfläche " Weiter ".
Wenn WinUI-Vorlagen nicht aufgeführt sind, müssen Sie Projektvorlagen wie oben erwähnt aus den Installationstools für die Windows App SDK installieren.
Das Dialogfeld "Neues Projekt konfigurieren " wird angezeigt.
Geben Sie im Textfeld " Projektname " einen Projektnamen ein, z . B. "MyWebView2WinUI3":
Geben Sie im Textfeld "Speicherort " einen Speicherort ein, oder navigieren Sie zu einem Speicherort, z
C:\Users\username\Documents\WebView2
. B. .Klicken Sie auf die Schaltfläche " Erstellen ".
Das neue WinUI 3-Projekt wird in Projektmappen-Explorer in Visual Studio geöffnet:
Die
App.xaml.cs
Datei definiert eineApplication
Klasse, die Ihre App-Instanz darstellt.Die
MainWindow.xaml.cs
Datei definiert eineMainWindow
Klasse, die das Von Ihrer App-Instanz angezeigte Hauptfenster darstellt. Die Klassen werden von Typen imMicrosoft.UI.Xaml
Namespace von WinUI abgeleitet.
Wählen Sie in der Dropdownliste " Lösungskonfigurationen " die Option "Debuggen" aus.
Wählen Sie in der Dropdownliste " Lösungsplattformen " eine Plattform aus, z. B. x64.
Wählen Sie "Alle > speichern" (
Ctrl
++Shift``S
) aus, um das Projekt zu speichern.Drücken Sie F5 , um das Projekt zu erstellen und auszuführen. Die leere WinUI Desktop-App wird geöffnet, und es wurde noch kein WebView2-Steuerelement hinzugefügt:
Schließen Sie die Beispiel-App.
Aktualisieren von Zielversionsnummern
Für den obigen Buildschritt: Wenn Sie ein vorheriges Projekt aktualisieren, müssen Sie möglicherweise die Versionsnummern für die Zielversion und die Mindestversion aktualisieren. Klicken Sie dazu in "Projektmappe" mit der rechten Maustaste auf das Projekt, und wählen Sie dann " Projektdatei bearbeiten" aus. Ihre .csproj
Datei wird geöffnet. Stellen Sie sicher, dass die Werte wie folgt aktualisiert werden, und speichern Sie dann alle Änderungen, und erstellen Sie das Projekt.
<TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
<TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
Die oben genannten Werte stellen Folgendes dar:
- Zielversion: Windows 10, Version 2004 (Build 19041) oder höher.
- Mindestversion: Windows 10, Version 1809 (Build 17763).
Schritt 4 : Hinzufügen eines WebView2-Steuerelements
Dieses Lernprogrammprojekt basiert auf der Projektvorlage Blank App, Packaged (WinUI in Desktop). Diese Projektvorlage verwendet den WindowsAppSDK, der das WebView2 SDK enthält.
Bearbeiten Sie das und MainWindow.xaml.cs
die MainWindow.xaml
Dateien wie folgt in einem WebView2-Steuerelement im leeren WinUI 3-Beispiel-App-Projekt.
Wählen Sie
MainWindow.xaml
in Visual Studio in Projektmappen-Explorer aus, um es im Code-Editor zu öffnen.Fügen Sie den WebView2-XAML-Namespace hinzu, indem Sie das folgende Attribut in das
<Window>
Starttag einfügen:xmlns:controls="using:Microsoft.UI.Xaml.Controls"
Stellen Sie sicher, dass Ihr Code in
MainWindow.xaml
folgendem Format vorliegt:<Window x:Class="MyWebView2WinUI3.MainWindow" xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:local="using:MyWebView2WinUI3" 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>
Um das WebView2-Steuerelement hinzuzufügen, ersetzen Sie die
<StackPanel>
Tags durch den folgenden<Grid>
Code. DieSource
Eigenschaft im unteren Bereich legt den anfänglichen URI fest, der im WebView2-Steuerelement angezeigt wird (https://www.microsoft.com
):<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>
Erweitern
MainWindow.xaml
Und öffnenMainWindow.xaml.cs
Sie dann in Projektmappen-Explorer .Kommentieren
MainWindow.xaml.cs
Sie in die folgende Zeile aus, wie gezeigt:// myButton.Content = "Clicked";
Wählen Sie "Alle > speichern" (
Ctrl
++Shift``S
) aus, um das Projekt zu speichern.Drücken Sie F5, um das Projekt zu erstellen und auszuführen.
Die Beispielanwendung ist eine WebView2-Host-App, die das WebView2-Steuerelement enthält. Das WebView2-Steuerelement zeigt die Website
https://www.microsoft.com
an:Schließen Sie die Beispiel-App.
Schritt 5 – Hinzufügen von Navigationssteuerelementen
Damit Benutzer steuern können, welche Webseite im WebView2-Steuerelement angezeigt wird, fügen Sie der Beispiel-App wie folgt eine Adressleiste hinzu:
Fügen
MainWindow.xaml
Sie in das Element, das das Element enthält<controls.WebView2>
, den<Grid>
folgenden Code ein:<TextBox Name="addressBar" Grid.Column="0"/> <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>
Stellen Sie sicher, dass das resultierende
<Grid>
Element in derMainWindow.xaml
Datei wie folgt übereinstimmt:<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> <controls:WebView2 x:Name="MyWebView" Grid.Row="1" Grid.ColumnSpan="2" Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/> </Grid>
Kopieren
MainWindow.xaml.cs
Sie in den folgenden Code inmyButton_Click
. Dieser Code navigiert das WebView2-Steuerelement zu der in der Adressleiste eingegebenen URL.private void myButton_Click(object sender, RoutedEventArgs e) { try { Uri targetUri = new Uri(addressBar.Text); MyWebView.Source = targetUri; } catch (FormatException ex) { // Incorrect address entered. } }
Wählen Sie "Alle > speichern" (
Ctrl
++Shift``S
) aus, um das Projekt zu speichern.Drücken Sie F5 , um das Projekt zu erstellen und auszuführen.
Geben Sie eine neue vollständige URL in die Adressleiste ein, z https://www.bing.com. B. und klicken Sie dann auf die Schaltfläche " Los ".
Das WebView2-Steuerelement in der Beispiel-App zeigt die Bing-Website an. In der Adressleiste wird die URL angezeigt, z
https://www.bing.com
. B.:Geben Sie eine unvollständige URL in die Adressleiste ein, z
bing.com
. B. , und klicken Sie dann auf die Schaltfläche " Gehe zu".Eine
ArgumentException
Ausnahme wird ausgelöst, da die URL nicht mithttp://
oderhttps://
beginnt.Schließen Sie die Beispiel-App. Möglicherweise werden die folgenden Dialogfelder angezeigt:
Bei diesen Debuggerdialogfeldern handelt es sich um einen bekannten Fehler. Klicken Sie auf die Schaltfläche "OK ", und klicken Sie dann auf die Schaltfläche "Abbrechen ", um die Dialogfelder zu schließen.
Schritt 6 – Navigationsereignisse
In diesem Abschnitt fügen Sie Code zum Importieren der WebView2 Core-Bibliothek hinzu.
MainWindow.xaml.cs
Fügen Sie oben in die folgende Zeile ein:using Microsoft.Web.WebView2.Core;
Apps, die WebView2-Steuerelemente hosten, lauschen auf die folgenden Ereignisse, die von WebView2-Steuerelementen während der Webseitennavigation ausgelöst werden:
NavigationStarting
SourceChanged
ContentLoading
HistoryChanged
NavigationCompleted
Wenn eine HTTP-Umleitung erfolgt, befinden sich mehrere
NavigationStarting
Ereignisse in einer Zeile.Weitere Informationen finden Sie unter Navigationsereignisse für WebView2-Apps.
Wenn Fehler auftreten, werden die folgenden Ereignisse ausgelöst, und möglicherweise wird eine Fehlerwebseite angezeigt:
SourceChanged
ContentLoading
HistoryChanged
Als Beispiel für die Verwendung der Ereignisse registrieren Sie einen Handler dafür
NavigationStarting
, der alle Nicht-HTTPS-Anforderungen wie folgt abbricht:Ändern
MainWindow.xaml.cs
Sie in den Konstruktor, um dieEnsureHttps
Methode zu registrieren:public MainWindow() { this.InitializeComponent(); MyWebView.NavigationStarting += EnsureHttps; }
MainWindow.xaml.cs
Fügen Sie unter dem Konstruktor die folgendeEnsureHttps
Methode hinzu:private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args) { String uri = args.Uri; if (!uri.StartsWith("https://")) { args.Cancel = true; } else { addressBar.Text = uri; } }
Wählen Sie "Alle > speichern" (
Ctrl
++Shift``S
) aus, um das Projekt zu speichern.Drücken Sie F5 , um das Projekt zu erstellen und auszuführen.
Geben Sie eine HTTP-URL ein, z
http://bing.com
. B. .Die Navigation wird für HTTP-Websites blockiert.
Geben Sie eine HTTPS-URL ein, z
https://bing.com
. B. .Die Navigation ist für HTTPS-Websites zulässig.
Schließen Sie die Beispiel-App. Möglicherweise werden die folgenden Dialogfelder angezeigt:
Bei diesen Debuggerdialogfeldern handelt es sich um einen bekannten Fehler. Klicken Sie auf die Schaltfläche "OK ", und klicken Sie dann auf die Schaltfläche "Abbrechen ", um die Dialogfelder zu schließen.
Verfügbarkeit des WinRT CoreWebView2-Objekts
Das WinRT-Objekt CoreWebView2
ist möglicherweise mit der Veröffentlichung der WebView2-API nicht verfügbar. Eine Liste der verfügbaren APIs finden Sie unter:
- WinUI 3-API-Referenz (Windows App SDK) – Microsoft.UI.Xaml.Controls.WebView2-Klasse – in der API-Referenz für Windows-Desktop-Apps > WinRT-APIs.
- WebView2-Spezifikation
Schritt 7 – Skripterstellung
Sie können Host-Apps verwenden, um JavaScript-Code zur Laufzeit in WebView2-Steuerelemente einzufügen. Sie können WebView2 mit der Ausführung von beliebigem JavaScript oder dem Hinzufügen von Initialisierungsskripts versehen. Das eingefügte JavaScript gilt für alle neuen Dokumente auf oberster Ebene und alle untergeordneten Frames, bis das JavaScript entfernt wird. Der eingefügte JavaScript-Code wird mit einer bestimmten Zeitdauer ausgeführt:
Führen Sie das eingefügte JavaScript nach der Erstellung des globalen Objekts aus.
Führen Sie das eingefügte JavaScript aus, bevor Sie ein anderes Skript ausführen, das im HTML-Dokument enthalten ist.
Als Nächstes fügen Sie Skripts hinzu, die eine Benachrichtigung senden, wenn ein Benutzer versucht, Nicht-HTTPS-Websites zu öffnen. Dazu wird ein Skript in den Webinhalt eingefügt, der ExecuteScriptAsync verwendet.
Ändern Sie die
EnsureHttps
Funktion wie folgt: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; } }
Wählen Sie "Alle > speichern" (
Ctrl
++Shift``S
) aus, um das Projekt zu speichern.Drücken Sie F5 , um das Projekt zu erstellen und auszuführen.
Versuchen Sie, eine Nicht-HTTPS-URL zu öffnen, z
http://www.bing.com
. B. .Das WebView2-Steuerelement der App zeigt ein Warnungsdialogfeld für Nicht-HTTPS-Websites an, das besagt, dass das Nicht-HTTPS
uri
nicht sicher ist:
Herzlichen Glückwunsch, Sie haben Ihre erste WebView2-App erstellt!
Besondere Überlegungen zu WinUI 3 WebView2
SmartScreen
WebView2 sendet URLs, zu denen in Ihrer Anwendung navigiert wird, an den SmartScreen-Dienst , um sicherzustellen, dass Ihre Kunden sicher bleiben. Wenn Sie diese Navigation deaktivieren möchten, können Sie dies über eine Umgebungsvariable tun:
Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");
Diese Umgebungsvariable muss vor der CoreWebView2
Erstellung festgelegt werden, die auftritt, wenn die WebView2.Source-Eigenschaft anfänglich festgelegt oder die WebView2.EnsureCoreWebView2Async-Methode anfänglich aufgerufen wird.
API-Einschränkungen
Auf die folgenden Schnittstellen kann in WinUI 3 nicht zugegriffen werden:
ICoreWebView2Environment
ICoreWebView2EnvironmentOptions
undICoreWebView2EnvironmentOptions2
ICoreWebView2ControllerOptions
API-Referenz
WinUI 3-API-Referenz (Windows App SDK):
- Microsoft.UI.Xaml.Controls.WebView2-Klasse – in DER API-Referenz für Windows-Desktop-Apps > WinRT-APIs.
Alle Plattformen/Sprachen:
- WebView2-API-Referenz – API-Referenz für jede Plattform.
Weitere Informationen
developer.microsoft.com:
- Microsoft Edge WebView2 – erste Einführung in WebView2-Features bei developer.microsoft.com.
Lokale Seiten:
- Einführung in Microsoft Edge WebView2 – Übersicht über die Features.
- Siehe auch in Einführung in Microsoft Edge WebView2.
- Verwalten von Benutzerdatenordnern
- Beispielcode für WebView2 – eine Anleitung zum
WebView2Samples
Repository. - Bewährte Methoden für die Entwicklung von WebView2-AppsEntwicklung bewährter Methoden
Github:
- Erste Schritte mit WebView2 in WinUI3
- Spezifikation: Das WebView2 Xaml-Steuerelement – die WinUI 3.0-Version des WebView2-Steuerelements.
- microsoft-ui-xaml repo > Issues - to enter WinUI-specific feature requests or bugs.