Erste Schritte mit WebView2 in WinUI 2 (UWP)-Apps

In diesem Lernprogramm gehen Sie wie folgt vor:

  • Richten Sie Ihre Entwicklungstools zum Erstellen von UWP-Apps ein, die Webview2 zum Anzeigen von Webinhalten verwenden.
  • Erstellen Sie eine erste WinUI 2 (UWP)-App.
  • Installieren Sie das Microsoft.UI.Xaml-Paket (WinUI 2) für das Projekt.
  • Fügen Sie ein WebView2-Steuerelement hinzu, das Webseiteninhalte anzeigt.
  • Erfahren Sie unterwegs mehr über WebView2-Konzepte.

Sie verwenden die Projektvorlage C# Blank App (Universelle Windows-App) und installieren dann das Microsoft.UI.Xaml-Paket (WinUI 2) für dieses Projekt. Durch das Installieren dieses Pakets wird das Microsoft.Web.WebView2-Paket (webView2 SDK) als Abhängigkeit installiert.

Das Microsoft.UI.Xaml (WinUI 2)-Paket ist Teil der Windows-UI-Bibliothek. Dieses Paket bietet Windows-Ui-Features, einschließlich:

  • UWP-XAML-Steuerelemente.
  • Dichte Steuerelementformatvorlagen.
  • Fluent-Stile und -Materialien.

WinUI 2 unterstützt nur UWP. Diese Steuerelemente sind abwärtskompatibel.

Abgeschlossenes Projekt

Im Gegensatz zu einigen der anderen Lernprogramme gibt es im WebView2Samples-Repository keine abgeschlossene Version dieses Erste Schritte Lernprogramms.

Folgen Sie den wichtigsten Schrittabschnitten nacheinander unten.

Schritt 1 : Installieren von Visual Studio

Visual Studio 2019, Version 16.9 oder höher, ist für dieses Lernprogramm erforderlich. Visual Studio 2022 wird unterstützt. Visual Studio 2017 wird nicht unterstützt.

  1. Wenn eine geeignete Version von Microsoft Visual Studio in einem neuen Fenster oder einer neuen Registerkarte noch nicht installiert ist, lesen Sie "Installieren von Visual Studio " in "Einrichten Ihrer Dev-Umgebung für WebView2". Führen Sie die Schritte auf dieser Seite aus, um eine einfache Standardinstallation von Visual Studio durchzuführen.

    Kehren Sie dann zu dieser Seite zurück, und fahren Sie unten fort.

  2. Relevant für Visual Studio 2019: Wenn Visual Studio im Code-Editor keine Zeilennummern anzeigt, aktivieren Sie Zeilennummern. Wählen Sie dazu "Extras > Optionen > Text-Editor > Alle Sprachen > Zeilennummern" aus. Klicken Sie dann auf "OK".

Schritt 2: Installieren von Workloads für .NET-Desktop, C++-Desktop und UWP-Entwicklungstools

  1. Öffnen Sie Microsoft Visual Studio. Das Fenster mit den öffnenden Optionen wird angezeigt:

    Öffnen des Optionsfensters in Visual Studio 2022

  2. Klicken Sie unten rechts ohne Code auf "Weiter". Visual Studio wird geöffnet, leer:

    Visual Studio 2022 leer

  3. Wählen Sie Tools > zum Abrufen von Tools und Features aus. Das Fenster Visual Studio-Installer wird geöffnet, und dann wird das Fenster "Ändern – Visual Studio" darüber geöffnet:

    Das Fenster "Visual Studio ändern", Anfangszustand

Wenn das Fenster "Visual Studio ändern" nicht geöffnet ist, klicken Sie im fenster Visual Studio-Installer auf die Schaltfläche "Ändern".

  1. Scrollen Sie auf der Registerkarte "Workloads " zu den folgenden Karten, und klicken Sie darauf, um sie auszuwählen. Stellen Sie sicher, dass auf jeder dieser Karten ein Häkchen angezeigt wird:

    • .NET-Desktopentwicklung
    • Desktopentwicklung mit C++
    • Universelle Windows-Plattform Entwicklung
  2. Erweitern Sie auf der rechten Seite im Abschnitt "Installationsdetails" Universelle Windows-Plattform Entwicklung, und wählen Sie dann C++ (v143) Universelle Windows-Plattform Tools oder C++ (v142) Universelle Windows-Plattform Tools aus:

    Im Dialogfeld "Visual Studio 2019 ändern" werden Karten und Installationsdetails angezeigt.

    Wenn alle diese Komponenten bereits installiert wurden, können Sie auf die Schaltfläche "Schließen" klicken, das fenster Visual Studio-Installer schließen und zum nächsten Hauptabschnitt der nachstehenden Schritte wechseln.

  3. Klicken Sie auf die Schaltfläche "Ändern ".

    Ein Fenster " Benutzerkontensteuerung " wird angezeigt, in dem Sie gefragt werden: "Möchten Sie zulassen, dass diese App Änderungen an Ihrem Gerät vorsieht? Visual Studio-Installer. Bestätigter Herausgeber: Microsoft Corporation. Dateiursprung: Festplatte auf diesem Computer. Weitere Details anzeigen (Schaltfläche)".

  4. Klicken Sie auf die Schaltfläche " Ja ".

  5. Es wird ein Dialogfeld angezeigt: "Bevor wir beginnen, Visual Studio schließen":

    Dialogfeld: Schließen Sie Visual Studio, bevor wir beginnen.

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

    Visual Studio lädt die ausgewählten Pakete herunter, überprüft und installiert sie:

    Visual Studio-Installer funktioniert

    Dieser Vorgang kann einige Minuten dauern. In einem neuen Fenster oder einer neuen Registerkarte können Sie sich eine Übersicht auf oberster Ebene in Microsoft Edge WebView2 ansehen – eine erste Einführung in WebView2-Features bei developer.microsoft.com.

    Wenn Visual Studio-Installer abgeschlossen ist, kehren Sie zu dieser Seite zurück, und fahren Sie mit den folgenden Schritten fort. Visual Studio wird mit einem leeren Projektmappen-Explorer angezeigt.

  7. Drücken SieAlt+Tab, um zum fenster Visual Studio-Installer zu wechseln, und schließen Sie dann das fenster Visual Studio-Installer.

Schritt 3: Erstellen einer UWP-App

  1. Wenn Visual Studio geöffnet ist, wählen Sie "Neues > Projekt speichern" > aus. Das Dialogfeld " Neues Projekt erstellen " wird geöffnet.

    Wenn Visual Studio geschlossen ist, öffnen Sie es, und klicken Sie dann auf dem Startbildschirm von Visual Studio auf die Neue Projektkarte erstellen :

    Der Startbildschirm von Visual Studio: Klicken Sie auf die Karte "Neues Projekt erstellen".

  2. Geben Sie oben im Textfeld "Nach Vorlagen suchen " die leere C#-App (Universelle Windows-App) ein, und wählen Sie dann die C#-Karte "Leere App (Universelle Windows-App)" aus:

    Im Dialogfeld "Neues Projekt erstellen" wird die leere App-Karte (Universelle Windows-Karte) angezeigt.

  3. Klicken Sie auf die Schaltfläche Weiter.

    Das Dialogfeld " Neues Projekt konfigurieren " wird für eine leere App (Universelle Windows-App) angezeigt:

    Im Dialogfeld "Neues Projekt konfigurieren" werden Textfelder für eine leere App (Universelle Windows-App) angezeigt.

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

  5. Geben Sie im Textfeld "Speicherort " einen Pfad ein, z C:\Users\myusername\Documents\MyWebView2Projects. B. .

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

Das Dialogfeld "Neues Windows-Projekt " wird angezeigt:

Das Dialogfeld "Neues Windows-Projekt"

  1. Übernehmen Sie die Standardwerte, und klicken Sie auf die Schaltfläche " OK ".

  2. Wenn der Abschnitt " Entwicklermodus " angezeigt wird, klicken Sie in diesem Abschnitt auf "Ein". Wenn Sie Ihren Computer noch nicht auf den Entwicklermodus festgelegt haben, wird das Dialogfeld " Entwicklerfeatures verwenden " geöffnet, um das Aktivieren des Entwicklermodus zu bestätigen.

    • Klicken Sie auf "Ja ", um den Entwicklermodus für Ihren Computer zu aktivieren, und schließen Sie dann das Fenster "Einstellungen" .

    Visual Studio zeigt die neu erstellte Lösung und das Projekt an:

    Visual Studio mit dem neu erstellten WinUI 2 (UWP)-Projekt

Schritt 4 : Erstellen und Ausführen des leeren Projekts

Vergewissern Sie sich vor dem Hinzufügen von WebView2-Code, dass das Projekt funktioniert, und sehen Sie, wie die leere App aussieht:

  1. Erstellen Sie das leere Projekt, und führen Sie es aus. Wählen Sie dazu Debuggen > Starten Debuggen (F5) aus.

    Das leere Projekt vor dem Hinzufügen von WebView2-Code

  2. Schließen Sie die App.

Als Nächstes richten Sie dieses neue WinUI 2 (UWP)-Projekt ein, um das WebView2-Steuerelement zu hosten und die WebView2-API zu verwenden.

Schritt 5 : Installieren des WinUI 2 SDK (Microsoft.UI.Xaml)

Als Nächstes installieren Sie das Microsoft.UI.Xaml-Paket für dieses Projekt. Microsoft.UI.Xaml ist WinUI 2.

  1. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf das Projekt (nicht auf den Lösungsknoten darüber), und wählen Sie dann "NuGet-Pakete verwalten" aus.

    Der Bereich "NuGet-Paket-Manager " wird in Visual Studio geöffnet.

  2. Klicken Sie im NuGet-Paket-Manager auf die Registerkarte "Durchsuchen ".

  3. Deaktivieren Sie das Kontrollkästchen Vorabversion einschließen .

  4. Geben Sie im Suchfeld "Microsoft.UI.Xaml" ein, und wählen Sie dann die Karte "Microsoft.UI.Xaml" unter dem Suchfeld aus:

    Der NuGet-Paket-Manager zum Installieren von Microsoft.UI.Xaml

    Die obige Abbildung zeigt 2.7.1, aber diese Anweisungen sind tatsächlich für 2.8 oder höher für die allgemeine Verfügbarkeit von WebView2 im Microsoft.UI.Xaml NuGet-Paket geschrieben.

    Für Version 2.8.0 oder höher im Abschnitt "Abhängigkeiten " ist "Microsoft.Web.WebView2 " möglicherweise Aufgeführt.

  5. Stellen Sie auf der rechten Seite sicher, dass die Version 2.8.0 oder höher stabil ist.

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

    Das Dialogfeld "Änderungen in der Vorschau " wird angezeigt:

    Das Dialogfeld "Änderungen in der Vorschau anzeigen" zum Installieren des Microsoft.UI.Xaml-Pakets

    Die obige Abbildung zeigt 2.7.1, aber diese Anweisungen sind tatsächlich für 2.8.0 oder höher für die allgemeine Verfügbarkeit von WebView2 im Microsoft.UI.Xaml NuGet-Paket geschrieben.

  7. Klicken Sie auf die Schaltfläche " OK ".

  8. Das Dialogfeld "Lizenzakzeptanz " wird angezeigt:

    Das Dialogfeld "Lizenzakzeptanz" für die Installation des Microsoft.UI.Xaml-Pakets

  9. Klicken Sie auf die Schaltfläche "Ich stimme zu ". In Visual Studio wird die readme.txt Datei angezeigt, die besagt, dass Sie das WinUI-Paket installiert haben:

    Die readme.txt Datei nach der Installation des Pakets "Microsoft.UI.Xaml" meldet, dass Sie das WinUI NuGet-Paket installiert haben.

    In der Info werden einige Codezeilen aufgelistet, die mit dem, was wir hinzufügen werden, vergleichbar sind.

  10. Wählen Sie "Alle > speichern" (Ctrl++Shift``S) aus.

Sie haben jetzt das Microsoft.UI.Xaml-Paket (WinUI 2) für Ihr Projekt installiert. Das WinUI 2 SDK (Microsoft.UI.Xaml) enthält das WebView2 SDK, sodass Sie das NuGet-Paket für das WebView2 SDK nicht separat installieren müssen.

Schritt 6: Instanziieren des WebView2-Steuerelements im XAML-Code

Jetzt können Sie dem Projekt WebView2-Code hinzufügen. Fügen Sie zunächst wie folgt einen Namespaceverweise für das WebView2-Steuerelement hinzu:

  1. Erweitern Sie in Projektmappen-Explorer Ihr Projekt, und doppelklicken Sie dann auf "MainPage.xaml".

    MainPage.xaml wird in einem Designer mit einem Code-Editor darunter geöffnet:

    MainPage.xaml-Code und Designerfenster

  2. Fügen Sie im Code-Editor im open-Tag <Pagedes <Page> Elements das folgende Attribut unter den anderen xmlns: Attributen hinzu:

    xmlns:controls="using:Microsoft.UI.Xaml.Controls"
    

    Fügen Sie dem XAML-Raster wie folgt ein WebView2-Steuerelement hinzu:

  3. Fügen Sie in der MainPage.xaml Datei im <Grid> Element (das noch keine anderen Elemente enthält) das folgende Element hinzu:

    <controls:WebView2 x:Name="WebView2" Source="https://bing.com"/>
    
  4. Drücken Sie Ctrl+S , um die Datei zu speichern.

    Oberhalb der MainPage.xaml Datei im Code-Editor wird möglicherweise eine Vorschau des WebView2-Inhalts angezeigt, oder es bleibt leer (weiß), bis Sie die App zum ersten Mal erstellen:

    Vorschau des WebView2-Inhalts

    Das obige Bild zeigt "Steuerelement" in zwei Zeilen; Es wird empfohlen, stattdessen das Wort "Steuerelemente" in diesen Zeilen zu verwenden.

Schritt 7: Erstellen und Ausführen des Projekts mit dem WebView2-Steuerelement

  1. Klicken Sie auf Debuggen > starten Debuggen. Das App-Fenster wird geöffnet und zeigt kurz das WebView2 WebUI-Raster an:

    Während des Debuggens wird das WebView2 WebUI-Raster kurz angezeigt.

  2. Nach kurzer Zeit wird im App-Fenster die Bing-Website im WebView2-Steuerelement für WebUI 2 angezeigt:

    Die Beispiel-App zeigt die Bing-Website an.

  3. Klicken Sie in Visual Studio auf Debuggen > beenden , um das App-Fenster zu schließen.

Herzlichen Glückwunsch, Sie haben Ihre erste WebView2-App erstellt!

Jetzt können Sie den Inhalt des WebView2-Steuerelements ändern, um Eigene Inhalte hinzuzufügen.

Informationen zu Navigationsereignissen

Als Nächstes erfahren Sie mehr über Navigationsereignisse, die für WebView2-Apps unerlässlich sind. Die App navigiert zunächst zu https://bing.com.

Status der WebView2-Funktionalität auf WinUI 2 (UWP)

Das WebView2 WinUI 2 (UWP)-Steuerelement befindet sich in der Entwicklung. Die folgenden Features wurden nicht implementiert oder sind aufgrund ausstehender Arbeit deaktiviert:

  • „Downloads“ aus.
    • Das Herunterladen von Dateien ist nur in der Vorschau über den Edge Dev-Kanal bis Edge 104 verfügbar. Darüber hinaus ist es standardmäßig deaktiviert. Verwenden Sie zum Aktivieren die Befehlszeilenoption edge-webview-optional-enable-uwp-regular-downloads. Es gibt eine Reihe bekannter Einschränkungen für das aktuelle Downloadverhalten für WebView2 in UWP:
      • Der Downloads-Hub ist derzeit deaktiviert.
      • Je nach Betriebssystem des Benutzers werden heruntergeladene Dateien in verschiedene Ordner heruntergeladen. Bei Windows 11 werden die heruntergeladenen Dateien in einem Unterordner mit dem Namen des App-Pakets im Ordner "Downloads" angezeigt. Für die unten Windows 11 des Betriebssystems werden die heruntergeladenen Dateien in einem Unterordner namens "WebView2Downloads" im Unterordner dieses App-Pakets im Ordner "Downloads" angezeigt.
      • Darüber hinaus ist das Speichern von Dateien über "Speichern unter" funktionsfähig und für UWP WebView2 aktiviert. Die Dateien werden im jeweiligen Ordner gespeichert, den der Benutzer auswählt.
  • Benutzeroberfläche automatisch ausfüllen.
  • Als PDF drucken.
  • Der Standarddruck ist deaktiviert, entwickler können dies jedoch mithilfe von CapturePreviewAsync umgehen (dies erfasst jedoch nur den aktuellen Viewport).

Paketzusammenfassung:

Besondere Überlegungen zu WinUI 2 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.

Einschränkungen für Xbox, HoloLens und XAML

Diese Version von WebView 2 funktioniert nur auf Geräten der PC-Klasse und bietet die gesamte Bandbreite an Funktionen, die in der WinUI 3-Variante zu finden sind. Die Unterstützung von Xbox, HoloLens und XAML Island erfordert zusätzliche Arbeit, und diese Geräte und Szenarien können zu einem späteren Zeitpunkt in Betracht gezogen werden.

API-Einschränkungen

Auf die folgenden Schnittstellen kann in WinUI 2 nicht zugegriffen werden:

  • ICoreWebView2Environment
  • ICoreWebView2EnvironmentOptions und ICoreWebView2EnvironmentOptions2
  • ICoreWebView2ControllerOptions

API-Referenz

Alle Plattformen/Sprachen:

Weitere Informationen

Lokale Seiten:

Github: