Erste Schritte mit WebView2 in WinUI 3-Apps (Windows App SDK)

Artikel
09/21/2022
9 Minuten Lesedauer

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.

Beispiel-App zur Anzeige der Bing-Website

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 eine Application Klasse, die Ihre App-Instanz darstellt.
- Die MainWindow.xaml.cs Datei definiert eine MainWindow Klasse, die das Von Ihrer App-Instanz angezeigte Hauptfenster darstellt. Die Klassen werden von Typen im Microsoft.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. Die Source 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 öffnen MainWindow.xaml.csSie dann in Projektmappen-Explorer .
Kommentieren MainWindow.xaml.csSie 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.coman:
Schließen Sie die Beispiel-App.

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.xamlSie 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 der MainWindow.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.csSie in den folgenden Code in myButton_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 mit http:// oder https://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.

In diesem Abschnitt fügen Sie Code zum Importieren der WebView2 Core-Bibliothek hinzu.

MainWindow.xaml.csFü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.csSie in den Konstruktor, um die EnsureHttps Methode zu registrieren:

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

MainWindow.xaml.csFügen Sie unter dem Konstruktor die folgende EnsureHttps 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 und ICoreWebView2EnvironmentOptions2
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.