Erste Schritte mit WebView2 in WinUI 3-Apps (Windows App SDK)
In diesem Artikel wird beschrieben, wie Sie Ihre Entwicklungstools einrichten und eine erste WebView2-App für WinUI 3 (Windows App SDK) erstellen und dabei mehr über WebView2-Konzepte erfahren.
In diesem Tutorial 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 vollständige Version dieses Tutorialprojekts (stand 2020) ist im WebView2Samples-Repository verfügbar:
- Beispielname: WinUI3_GettingStarted
- Repositoryverzeichnis: WinUI3_GettingStarted
- Lösungsdatei: WinUI_Sample.sln
Das vorliegende Tutorial wird aktualisiert und erstellt nur ein einzelnes Projekt, kein zweites (Paket)-Projekt wie in 2020.
Schritt 1: Installieren von Visual Studio und dem 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 Tools für das Windows App SDK installieren , und führen Sie dann die Schritte auf dieser Seite aus, um Microsoft Visual Studio zu installieren, z. B. Visual Studio 2022.
- Weitere Informationen finden Sie bei Bedarf in einem neuen Fenster oder einer neuen Registerkarte unter Installieren von Visual Studio unter Einrichten Ihrer Entwicklungsumgebung für WebView2.
Kehren Sie von dieser Seite zurück, und fahren Sie mit den folgenden Schritten fort.
Für dieses Beispiel müssen Sie das WebView2 SDK nicht separat installieren. Im Folgenden wählen Sie die Projektvorlage Leere App, Verpackt (WinUI in Desktop) aus, die das WindowsAppSDK verwendet, das das WebView2 SDK enthält.
Schritt 2: 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 Karte Neues Projekt erstellen . Das Fenster Neues Projekt erstellen wird geöffnet.
Wenn Visual Studio ausgeführt wird, wählen Sie Datei>Neues>Projekt aus. Das Dialogfeld Neues Projekt erstellen wird geöffnet.
Aktivieren des Entwicklermodus: Wenn Visual Studio während der Schritte dieses Artikels zu einem bestimmten Zeitpunkt geöffnet wird, werden Sie möglicherweise aufgefordert, den Entwicklermodus für Ihren Computer zu aktivieren. Weitere Informationen finden Sie 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 suchendie Zeichenfolge 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 installieren, wie oben erwähnt unter Installieren von Tools für das Windows App SDK. Weitere Tipps zum Anzeigen der Vorlage:
Klicken Sie nach der Installation der Standardoptionen für Visual Studio 2022 Community Edition im Visual Studio-Installer auf die .NET-Karte , und aktivieren Sie dann auf der rechten Seite das Kontrollkästchen Windows App SDK C#-Vorlagen.
Wenn die richtige Projektvorlage immer noch nicht angezeigt wird: Klicken Sie im Visual Studio-Installer auf die UWP-Karte , um sie auszuwählen, aktivieren Sie das Kontrollkästchen v143 C++-Tools auf der rechten Seite, und klicken Sie dann auf die Schaltfläche Ändern .
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 im 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 Hauptfenster darstellt, das von Ihrer App-Instanz angezeigt wird. Die Klassen werden von Typen imMicrosoft.UI.Xaml
WinUI-Namespace abgeleitet.
Wählen Sie in der Dropdownliste Projektmappenkonfigurationen (in der Mitte des oberen Fensters) die Option Debuggen aus.
Wählen Sie in der Dropdownliste Lösungsplattformen eine Plattform aus, z. B. x64.
Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus, um das Projekt zu speichern.
Drücken Sie die F5-TASTE, um das Projekt zu erstellen und auszuführen. Die leere WinUI Desktop-App wird geöffnet, ohne dass noch ein WebView2-Steuerelement hinzugefügt wurde:
Schließen Sie die App.
Aktualisieren von Zielversionsnummern
Für den obigen Buildschritt: Wenn Sie ein vorheriges Projekt aktualisieren, müssen Sie möglicherweise die Versionsnummern für Zielversion und Mindestversion aktualisieren. Klicken Sie hierzu 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, 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 3: Hinzufügen eines WebView2-Steuerelements
Dieses Tutorialprojekt basiert auf der Projektvorlage Leere App, Verpackt (WinUI in Desktop). Diese Projektvorlage verwendet das WindowsAppSDK, das das WebView2 SDK enthält.
Bearbeiten Sie die MainWindow.xaml
Dateien und MainWindow.xaml.cs
wie folgt, um dem leeren WinUI 3-App-Projekt ein WebView2-Steuerelement hinzuzufügen:
Doppelklicken Sie
MainWindow.xaml
in Visual Studio im Projektmappen-Explorer, 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
dem folgenden Code ähnelt:<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"> <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 das gesamte
<StackPanel>
Element durch den folgenden<Grid>
Code. DieSource
-Eigenschaft im unteren Bereich legt den anfänglichen URI fest, der im WebView2-Steuerelementhttps://www.microsoft.com
() angezeigt wird:<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 Sie im Projektmappen-Explorer
MainWindow.xaml
, und öffnen SieMainWindow.xaml.cs
dann .Kommentieren
MainWindow.xaml.cs
Sie in die folgende Zeile aus, wie gezeigt:// myButton.Content = "Clicked";
Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus, um das Projekt zu speichern.
Drücken Sie F5, um das Projekt zu erstellen und auszuführen.
Die App 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 App.
WinAppSDK unterstützt benutzerdefinierte WebView2-Umgebungen.
WinAppSDK unterstützt benutzerdefinierte WebView2-Umgebungen ab WinAppSDK 1.5 (1.5.0-experimental2). Weitere Informationen finden Sie unter WinUI3 WebView2 mit einer benutzerdefinierten CoreWebView2Environment.For more information, see WinUI3 WebView2 with a custom CoreWebView2Environment.
Um eine benutzerdefinierte WebView2-Umgebung zu instanziieren, initialisieren Sie WebView2 mit einer der Außerkraftsetzungen von WebView2.EnsureCoreWebView2Async
(unten aufgeführt), und übergeben Sie Ihren benutzerdefinierten CoreWebView2Environment
(und optional benutzerdefinierten CoreWebView2ControllerOptions
):
public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment)
public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment, CoreWebView2ControllerOptions controllerOptions)
Sehen Sie sich auch den Beispielcode unter Deaktivieren der SmartScreen-Navigation unten an.
API-Referenz:
- WebView2.EnsureCoreWebView2Async
- CoreWebView2ControllerOptions
- CoreWebView2Environment
- CoreWebView2EnvironmentOptions
Schritt 4: Hinzufügen von Navigationssteuerelementen
Damit Benutzer steuern können, welche Webseite im WebView2-Steuerelement angezeigt wird, fügen Sie der App wie folgt eine Adressleiste hinzu:
Fügen
MainWindow.xaml
Sie in den folgenden Code in das<Grid>
-Element ein, das das<controls:WebView2>
-Element enthält:<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 mit Folgendem ü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>
Fügen
MainWindow.xaml.cs
Sie in den folgenden Code inmyButton_Click
ein, und überschreiben Sie die vorhandenemyButton_Click
Methode (die fast leer ist). Dieser Code navigiert das WebView2-Steuerelement zu der url, die in der Adressleiste eingegeben wurde.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 Datei>Alle speichern (STRG+UMSCHALT+S) aus, um das Projekt zu speichern.
Drücken Sie die F5-TASTE, 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 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 Los .Es wird eine
ArgumentException
Ausnahme ausgelöst, die nach dem Schließen der App angezeigt wird, da die URL nicht mithttp://
oderhttps://
beginnt.Schließen Sie die App.
Schritt 5: Navigationsereignisse
In diesem Abschnitt fügen Sie Code zum Importieren der WebView2 Core-Bibliothek hinzu.
MainWindow.xaml.cs
Fügen Sie in oben über den anderenusing
Anweisungen die folgende Zeile hinzu: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 auftritt, gibt es 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 eine Fehlerwebseite wird möglicherweise angezeigt:
SourceChanged
ContentLoading
HistoryChanged
Registrieren Sie als Beispiel für die Verwendung der -Ereignisse einen Handler für
NavigationStarting
, der alle Nicht-HTTPS-Anforderungen wie folgt abbricht:MainWindow.xaml.cs
Fügen Sie in im Konstruktor die folgendeNavigationStarting
Zeile hinzu, um dieEnsureHttps
-Methode zu registrieren:public MainWindow() { this.InitializeComponent(); MyWebView.NavigationStarting += EnsureHttps; }
MainWindow.xaml.cs
Fügen Sie in unterhalb des Konstruktors 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 Datei>Alle speichern (STRG+UMSCHALT+S) aus, um das Projekt zu speichern.
Drücken Sie die F5-TASTE, um das Projekt zu erstellen und auszuführen.
Geben Sie in der App in der Adressleiste eine HTTP-URL ein, z
http://bing.com
. B. , und klicken Sie dann auf die Schaltfläche Gehe zu .Es geschieht nichts, da die Navigation zu HTTP-Websites blockiert ist und wir noch kein Dialogfeld hinzugefügt haben, um Feedback zu geben.
Geben Sie eine HTTPS-URL ein, z
https://bing.com
. B. , und klicken Sie dann auf die Schaltfläche Los .Die App navigiert zur angegebenen Seite, da die Navigation für HTTPS-Websites zulässig ist.
Schließen Sie die App.
Schritt 6: Skripterstellung
Sie können Host-Apps verwenden, um JavaScript-Code zur Laufzeit in WebView2-Steuerelemente einzufügen. Mit WebView2 können Sie beliebiges JavaScript ausführen oder Initialisierungsskripts hinzufügen. Das eingefügte JavaScript gilt für alle neuen Dokumente der obersten Ebene und alle untergeordneten Frames, bis das JavaScript entfernt wird. Der eingefügte JavaScript-Code wird mit einem bestimmten Zeitpunkt ausgeführt, um eine der folgenden Aktionen auszuführen:
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 beispielsweise Skripts hinzu, die eine Warnung senden, wenn ein Benutzer versucht, Websites ohne HTTPS zu öffnen. Dazu müssen Sie ein Skript in den Webinhalt einfügen, der ExecuteScriptAsync verwendet.
Fügen Sie in der
EnsureHttps
-Methode die folgendeExecuteScriptAsync
Zeile hinzu: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 Datei>Alle speichern (STRG+UMSCHALT+S) aus, um das Projekt zu speichern.
Drücken Sie die F5-TASTE, um das Projekt zu erstellen und auszuführen.
Geben Sie in der Adressleiste der App eine NICHT-HTTPS-URL ein, z
http://www.bing.com
. B. , und klicken Sie dann auf die Schaltfläche Gehe zu.Das WebView2-Steuerelement der App zeigt ein Warnungsdialogfeld für Nicht-HTTPS-Websites an, in dem darauf hingewiesen wird, dass das Nicht-HTTPS-Steuerelement
uri
nicht sicher ist:Schließen Sie die App.
Herzlichen Glückwunsch, Sie haben Ihre erste WebView2-App erstellt!
Besondere Überlegungen zu WinUI 3 WebView2
Deaktivieren der SmartScreen-Navigation
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, verwenden Sie ein benutzerdefiniertes CoreWebView2Environment
wie folgt:
CoreWebView2EnvironmentOptions environmentOptions = new CoreWebView2EnvironmentOptions();
environmentOptions.AdditionalBrowserArguments = "--disable-features=msSmartScreenProtection";
string browserFolder = null; // Use null to get default browser folder
string userDataFolder = null; // Use null to get default user data folder
CoreWebView2Environment environment = await CoreWebView2Environment.CreateWithOptionsAsync(
browserFolder, userDataFolder, environmentOptions);
// ...
this.WebView2.EnsureCoreWebView2Async(environment);
Deaktivieren von SmartScreen mithilfe einer Umgebungsvariablen
Es wird nicht mehr empfohlen, eine Umgebungsvariable zu verwenden. Verwenden Sie stattdessen den oben genannten API-codebasierten Ansatz.
Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");
Diese Umgebungsvariable muss vor der CoreWebView2
Erstellung festgelegt werden. Dies geschieht, wenn die WebView2.Source-Eigenschaft anfänglich festgelegt oder die WebView2.EnsureCoreWebView2Async-Methode aufgerufen wird.
Festlegen von DefaultBackgroundColor
In WebView2 für WinUI 3 ist die DefaultBackgroundColor
Einstellung für das WebView2-XAML-Objekt vorhanden. Zum Beispiel:
public MainWindow()
{
this.InitializeComponent();
MyWebView.DefaultBackgroundColor = Colors.LightBlue;
}
Transparenz
WinUI 3 unterstützt keine transparenten Hintergründe. Siehe Transparente Hintergrundunterstützung für WebView2? · Problem 2992.
WinAppSDK-Unterstützung für benutzerdefinierte WebView2-Umgebungen
Siehe WinAppSDK unterstützt benutzerdefinierte WebView2-Umgebungen weiter oben.
Siehe auch
- WebView2-API-Referenz
- Einführung in Microsoft Edge WebView2 – Übersicht über Features.
- Verwalten von Benutzerdatenordnern
-
Beispielcode für WebView2 : Eine Anleitung zum
WebView2Samples
Repository. - Bewährte Entwicklungsmethoden für WebView2-AppsEntwicklung bewährte Methoden
developer.microsoft.com:
- Microsoft Edge WebView2 : Erste Einführung in WebView2-Features auf developer.microsoft.com.
GitHub:
- Erste Schritte mit WebView2 in WinUI3
- Spezifikation: Das WebView2-Xaml-Steuerelement – die WinUI 3.0-Version des WebView2-Steuerelements.
- microsoft-ui-xaml-Repository > Probleme : Eingabe winUI-spezifischer Funktionsanforderungen oder -fehler.