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.

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.

  1. Ö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.
  1. 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

  1. 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:

  1. 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".

  2. Geben Sie im Dialogfeld " Neues Projekt erstellen " im Feld "Nach Vorlagen suchen " WinUI 3 in Desktop ein:

    Suchen nach "WinUI 3 in Desktop" zum Erstellen eines neuen Projekts

  3. 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.

  4. Geben Sie im Textfeld " Projektname " einen Projektnamen ein, z . B. "MyWebView2WinUI3":

    Das Dialogfeld "Neues Projekt konfigurieren"

  5. Geben Sie im Textfeld "Speicherort " einen Speicherort ein, oder navigieren Sie zu einem Speicherort, z C:\Users\username\Documents\WebView2. B. .

  6. Klicken Sie auf die Schaltfläche " Erstellen ".

    Das neue WinUI 3-Projekt wird in Projektmappen-Explorer in Visual Studio geöffnet:

    Das neue WinUI 3-Projekt in Projektmappen-Explorer

    • 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.

  7. Wählen Sie in der Dropdownliste " Lösungskonfigurationen " die Option "Debuggen" aus.

  8. Wählen Sie in der Dropdownliste " Lösungsplattformen " eine Plattform aus, z. B. x64.

  9. Wählen Sie "Alle > speichern" (Ctrl++Shift``S) aus, um das Projekt zu speichern.

  10. 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:

    Die neue leere WinUI 3-App

  11. 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.

  1. Wählen Sie MainWindow.xaml in Visual Studio in Projektmappen-Explorer aus, um es im Code-Editor zu öffnen.

  2. 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>
    
  3. 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>
    
  4. Erweitern MainWindow.xaml Und öffnen MainWindow.xaml.csSie dann in Projektmappen-Explorer .

  5. Kommentieren MainWindow.xaml.csSie in die folgende Zeile aus, wie gezeigt:

        // myButton.Content = "Clicked";
    
  6. Wählen Sie "Alle > speichern" (Ctrl++Shift``S) aus, um das Projekt zu speichern.

  7. Drücken Sie F5, um das Projekt zu erstellen und auszuführen.

  8. Die Beispielanwendung ist eine WebView2-Host-App, die das WebView2-Steuerelement enthält. Das WebView2-Steuerelement zeigt die Website https://www.microsoft.coman:

    Das WebView2-Steuerelement, das die microsoft.com Webseite anzeigt

  9. 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:

  1. 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>
    
  2. 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.
        }
    }
    
  3. Wählen Sie "Alle > speichern" (Ctrl++Shift``S) aus, um das Projekt zu speichern.

  4. Drücken Sie F5 , um das Projekt zu erstellen und auszuführen.

  5. 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.:

    Die Beispiel-App zeigt die Bing-Website an.

  6. 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.

  7. Schließen Sie die Beispiel-App. Möglicherweise werden die folgenden Dialogfelder angezeigt:

    Debugger nicht konfiguriert

  8. 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.

  1. 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:

  2. Ändern MainWindow.xaml.csSie in den Konstruktor, um die EnsureHttps Methode zu registrieren:

    public MainWindow()
    {
        this.InitializeComponent();
        MyWebView.NavigationStarting += EnsureHttps;
    }
    
  3. 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;
        }
    }
    
  4. Wählen Sie "Alle > speichern" (Ctrl++Shift``S) aus, um das Projekt zu speichern.

  5. Drücken Sie F5 , um das Projekt zu erstellen und auszuführen.

  6. Geben Sie eine HTTP-URL ein, z http://bing.com. B. .

    Die Navigation wird für HTTP-Websites blockiert.

  7. Geben Sie eine HTTPS-URL ein, z https://bing.com. B. .

    Die Navigation ist für HTTPS-Websites zulässig.

  8. Schließen Sie die Beispiel-App. Möglicherweise werden die folgenden Dialogfelder angezeigt:

    Debugger nicht konfiguriert

  9. 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:

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.

  1. Ä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;
        }
    }
    
  2. Wählen Sie "Alle > speichern" (Ctrl++Shift``S) aus, um das Projekt zu speichern.

  3. Drücken Sie F5 , um das Projekt zu erstellen und auszuführen.

  4. 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:

    WebView2-Beispielsteuerelement für Apps zeigt ein Warnungsdialogfeld für Nicht-HTTPS-Websites an

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):

Alle Plattformen/Sprachen:

Weitere Informationen

developer.microsoft.com:

Lokale Seiten:

Github: