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

  • Artikel

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.

App, die die Bing-Website anzeigt

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 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 Tools für die 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.
  1. 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: Installieren eines Vorschaukanals von Microsoft Edge

  1. Installieren Sie die WebView2-Runtime oder einen beliebigen Microsoft Edge-Vorschaukanal (Beta, Dev oder Canary), Windows 10 Version 1803 (Build 17134) oder höher installiert ist.

Kehren Sie von dieser Seite zurück, und fahren Sie mit den folgenden 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 Standard Fenster 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 das 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.

  2. Geben Sie im Dialogfeld Neues Projekt erstellen im Feld Search für VorlagenwinUI 3 in Desktop ein:

    Suchen nach

  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 unter Installieren von Tools für die Windows App SDK installieren. Weitere Tipps zum Anzeigen der Vorlage:

    Klicken Sie nach der Installation der Standardoptionen für Visual Studio 2022 Community Edition in 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.

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

    Dialogfeld

  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 instance darstellt.

    • Die MainWindow.xaml.cs Datei definiert eine MainWindow Klasse, die das Standard Fenster darstellt, das von Ihrer App-instance angezeigt wird. Die Klassen werden von Typen im Microsoft.UI.Xaml WinUI-Namespace abgeleitet.

  7. Wählen Sie in der Dropdownliste Projektmappenkonfigurationen (in der Mitte des oberen Fensters) die Option Debuggen aus.

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

  9. Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus, um das Projekt zu speichern.

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

    Die neue leere WinUI 3-App

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

  1. Doppelklicken Sie MainWindow.xaml in Visual Studio in Projektmappen-Explorer, 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 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>

  3. Um das WebView2-Steuerelement hinzuzufügen, ersetzen Sie das gesamte <StackPanel> Element durch den folgenden <Grid> Code. Die Source -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>

  4. Erweitern MainWindow.xaml Sie Projektmappen-Explorer, und öffnen Sie MainWindow.xaml.csdann .

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

        // myButton.Content = "Clicked";

  6. Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus, um das Projekt zu speichern.

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

  8. Die App 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 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:

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

  1. Fügen MainWindow.xamlSie 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 der MainWindow.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>

  2. Fügen MainWindow.xaml.csSie in den folgenden Code in myButton_Clickein, und überschreiben Sie die vorhandene myButton_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.
    }
}

  3. Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus, um das Projekt zu speichern.

  4. Drücken Sie die F5-TASTE, 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 App zeigt die Bing-Website an. In der Adressleiste wird die URL angezeigt, z https://www.bing.com. B. :

    Die 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 Los .

    Es wird eine ArgumentException Ausnahme ausgelöst, die nach dem Schließen der App angezeigt wird, da die URL nicht mit http:// oder https://beginnt.

  7. Schließen Sie die App.

Schritt 6: Navigationsereignisse

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

  1. MainWindow.xaml.csFügen Sie in oben über den anderen using 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:

  2. MainWindow.xaml.csFügen Sie in im Konstruktor die folgende NavigationStarting Zeile hinzu, um die EnsureHttps -Methode zu registrieren:

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

  3. MainWindow.xaml.csFügen Sie in unterhalb des Konstruktors 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 Datei>Alle speichern (STRG+UMSCHALT+S) aus, um das Projekt zu speichern.

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

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

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

  8. Schließen Sie die App.

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

  1. Fügen Sie in der EnsureHttps -Methode die folgende ExecuteScriptAsync 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;
    }
}

  2. Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus, um das Projekt zu speichern.

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

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

    Das WebView2-Steuerelement der App zeigt ein Warnungsdialogfeld für Nicht-HTTPS-Websites an.

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

developer.microsoft.com:

Github: