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

In diesem Tutorial führen Sie Folgendes aus:

• Richten Sie Ihre Entwicklungstools zum Erstellen von UWP-Apps ein, die WebView2 zum Anzeigen von Webinhalten verwenden.
• Erstellen Sie eine erste WinUI 2-App (UWP).
• 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 mehr über WebView2-Konzepte auf dem Weg.

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

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

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

Plattformen

Dieser Artikel gilt für Windows und Xbox.

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

Siehe auch:

• Medien-App-Beispiele für Xbox

Abgeschlossenes Projekt

Eine vollständige Version dieses Erste Schritte Projekts (Projektmappe) befindet sich im WebView2Samples-Repository. Sie können die fertige Lösung (aus dem Repository oder aus den folgenden Schritten) als Baseline verwenden, um weitere WebView2-Code und andere Features hinzuzufügen.

Eine vollständige Version dieses Tutorialprojekts ist im WebView2Samples-Repository verfügbar:

• Beispielname: WinUI2_Sample
• Repositoryverzeichnis: WinUI2_GettingStarted
• Lösungsdatei: MyUWPGetStartApp.sln

Folgen Sie den hauptschrittenen Abschnitten nacheinander weiter unten.

Informationen zu WinUI und WebView2

In WinUI 2-Apps (UWP) wird WebView2 als XAML-Steuerelement verfügbar gemacht. Nachdem Sie das XAML-Steuerelement in Ihre App als benanntes Steuerelement eingebettet haben, können Sie in C#-Dateien auf dieses XAML-Steuerelement verweisen.

Nur eine Teilmenge der WebView2-Schnittstellen/-Funktionen wird in WinUI verfügbar gemacht:

• Das WebView2 XAML-Objekt macht die CoreWebView2 -Schnittstelle zusammen mit der wichtigsten Funktionalität verfügbar.

• Schnittstellen wie CoreWebView2Controller sind ausgeblendet, da WinUI die Umgebungs- und Fenstererstellung im Hintergrund übernimmt.

Siehe auch XAML-Einschränkung weiter unten.

Schritt 1: Installieren von Visual Studio

In diesem Artikel werden die Schritte und Screenshots für Visual Studio 2022 Community Edition gezeigt. Microsoft Visual Studio 2019 Version 16.9 oder höher ist erforderlich. Visual Studio 2017 wird nicht unterstützt.

1. Wenn noch keine geeignete Version von Microsoft Visual Studio installiert ist, finden Sie weitere Informationen in einem neuen Fenster oder einer neuen Registerkarte unter Installieren von Visual Studio unter Einrichten Ihrer Entwicklungsumgebung für WebView2. Führen Sie die Schritte auf dieser Seite aus, um eine einfache Standardinstallation von Visual Studio durchzuführen, z. B. Visual Studio 2022 Community Edition.

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

2. Wenn Visual Studio im Code-Editor keine Zeilennummern zeigt, können Sie Zeilennummern aktivieren. Wählen Sie dazu Extras>Optionen>Text-Editor>Alle Sprachen>Zeilennummern aus. Klicken Sie anschließend auf OK.

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

1. Öffnen Sie Microsoft Visual Studio. Das öffnende Optionsfenster wird angezeigt:

   

2. Klicken Sie unten rechts auf Ohne Code fortfahren. Visual Studio wird geöffnet, leer:

   

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

   

Wenn das Fenster Ändern von Visual Studio 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 vorhanden ist:

   • .NET-Desktopentwicklung
   • Desktopentwicklung mit C++
   • Universelle Windows-Plattform Entwicklung

2. Erweitern Sie auf der rechten Seite im Abschnitt InstallationsdetailsUniverselle Windows-Plattform Entwicklung, und wählen Sie dann C++ (v143) Universelle Windows-Plattform Tools aus:

   

   Wenn alle diese Komponenten bereits installiert wurden, klicken Sie auf die Schaltfläche Schließen, schließen Sie das fenster Visual Studio-Installer, und fahren Sie mit dem nächsten Hauptabschnitt der folgenden Schritte fort.

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 vornahm? Visual Studio-Installer. Verifizierter Herausgeber: Microsoft Corporation. Dateiursprung: Festplatte auf diesem Computer. Weitere Details anzeigen (Schaltfläche)".

4. Klicken Sie auf die Schaltfläche Ja .

5. Das Dialogfeld "Bevor wir beginnen, schließen Sie Visual Studio":

   

6. Klicken Sie auf die Schaltfläche Weiter .

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

   

   Dieser Screenshot zeigt Visual Studio Professional 2022, obwohl dieser Artikel tatsächlich mit Visual Studio Community 2022 aktualisiert wurde.

   Die Installation kann einige Minuten dauern. Visual Studio wird mit einer leeren Projektmappen-Explorer angezeigt.

7. Drücken Sie ALT+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 Datei>Neues>Projekt 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 das Karte Neues Projekt erstellen:

   

2. Geben Sie oben im Textfeld Nach Vorlagen suchen den Text C# Leere App (Universelles Windows) ein, und wählen Sie dann die Karte C# Blank App (Universal Windows) aus:

   

3. Klicken Sie auf die Schaltfläche Weiter .

   Das Dialogfeld Neues Projekt konfigurieren wird für eine leere App (universelles Windows) 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:

   

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

8. Wenn der Abschnitt Entwicklermodusfenster angezeigt wird, klicken Sie in diesem Abschnitt auf Ein. Wenn Sie Ihren Computer noch nicht auf 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 Projektmappe und das neu erstellte Projekt an:

   

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 sich wie folgt an, wie die leere App aussieht:

1. Erstellen Sie das leere Projekt, und führen Sie es aus. Wählen Sie hierzu Debuggen>Debuggen starten (F5) aus. Das Fenster der App wird geöffnet, zeigt vorübergehend ein Raster an und zeigt dann den Inhalt der App an:

   

   Dies ist eine grundlegende WinUI 2(UWP)-App ohne WebView2.

2. Schließen Sie die App.

Als Nächstes richten Sie dieses neue WinUI 2-Projekt (UWP) 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 darüber stehenden Projektmappenknoten), 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 SuchfeldMicrosoft.UI.Xaml ein, und wählen Sie dann unter dem Suchfeld die Karte Microsoft.UI.Xaml aus:

   

   Für Version 2.8.0 oder höher ist im Abschnitt Abhängigkeiten unten Microsoft.Web.WebView2 aufgeführt.

   Für HoloLens 2 Entwicklung muss das Microsoft.Web.WebView2-Paket version 1.0.1722.45 oder höher sein, was möglicherweise höher als der Standardwert ist. WebView2 auf HoloLens 2 befindet sich in der Vorschau und kann vor der allgemeinen Verfügbarkeit geändert werden. WebView2 wird nur auf HoloLens 2 Geräten unterstützt, auf denen das Windows 11 Update ausgeführt wird. Weitere Informationen finden Sie unter Update HoloLens 2.

5. Stellen Sie im mittleren Bereich in der Dropdownliste Version sicher, dass Neueste stabil ausgewählt ist, Version 2.8.0 oder höher.

6. Klicken Sie auf die Schaltfläche Installieren .

   Das Dialogfeld Vorschau der Änderungen wird angezeigt:

   

7. Klicken Sie auf die Schaltfläche OK .

8. Das Dialogfeld Lizenzakzeptanz wird angezeigt:

   

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

   

   In der Infodatei sind einige Codezeilen aufgeführt, die dem ähneln, was wir hinzufügen.

10. Wählen Sie Datei>Alle speichern (STRG+UMSCHALT+S) aus.

Sie haben nun 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 in XAML-Code

Jetzt können Sie WebView2-Code zum Projekt hinzufügen. Fügen Sie zunächst wie folgt einen Namespaceverweis 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:

   

2. Fügen Sie im Code-Editor im <Page> Starttag <Pagedes Elements das folgende Attribut unterhalb der anderen xmlns: Attribute 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) ein WebView2-Steuerelement hinzu, indem Sie das folgende Element hinzufügen:

   <controls:WebView2 x:Name="WebView2" Source="https://bing.com"/>
   

4. Drücken Sie STRG+S , um die Datei zu speichern.

   Über der MainPage.xaml Datei im Code-Editor wird möglicherweise eine Vorschau des Inhalts des WebView2-Steuerelements angezeigt, oder er bleibt leer (weiß), bis Sie die App zuerst erstellen:

   

   Die wellenförmige Unterstreichung wird nach dem Erstellen und Ausführen der App im nächsten Schritt entfernt.

Schritt 7: Erstellen und Ausführen des Projekts, das das WebView2-Steuerelement enthält

1. Klicken Sie auf Debuggen>Debuggen starten (F5). (Informationen zum Erstellen für HoloLens 2 finden Sie unter Verwenden von Visual Studio zum Bereitstellen und Debuggen. Das App-Fenster wird geöffnet und zeigt kurz das WebView2-WebUI-Raster an:

   

2. Nach einem Moment zeigt das App-Fenster die Bing-Website im WebView2-Steuerelement für WebUI 2 an:

   

3. Wählen Sie in Visual Studio Debuggen>Debuggen Debuggen beenden aus, 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.

• Lesen Sie in einem neuen Fenster oder einer neuen Registerkarte Navigationsereignisse für WebView2-Apps, und kehren Sie dann zu dieser Seite zurück.

Besondere Überlegungen zu WebView2 unter WinUI 2 (UWP)

Das WebView2 WinUI 2-Steuerelement (UWP) befindet sich in der Entwicklung.

Benutzeroberfläche für automatisches Ausfüllen

Die Benutzeroberfläche zum automatischen Ausfüllen ist für WebView2 für UWP-Apps noch nicht implementiert.

Siehe auch:

• AutoAusfüllen in Der Übersicht über WebView2-Features und -APIs.

Als PDF drucken

In PDF drucken erfordert, dass die App Zugriff auf einen beschreibbaren Speicherort in UWP hat, z. B. auf einen lokalen Ordner. Eine vollständige Liste der Pfade, auf die UWP zugegriffen werden kann, finden Sie unter Dateizugriffsberechtigungen.

Siehe auch:

• Drucken in Übersicht über WebView2-Features und -APIs.

Standardmäßig drucken

Der Standarddruck ist für WebView2 für UWP-Apps deaktiviert. Sie können jedoch den aktuellen Viewport erfassen und drucken, indem Sie aufrufen CapturePreview.

Siehe auch:

• Bildaufnahme in Der Übersicht über WebView2-Features und -APIs.

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. Dies geschieht, wenn die WebView2.Source-Eigenschaft anfänglich festgelegt oder die WebView2.EnsureCoreWebView2Async-Methode aufgerufen wird.

Herunterladen von Dateien

Es gibt einige bekannte Einschränkungen für das aktuelle Downloadverhalten für WebView2 in UWP.

Speichern unter

Das Speichern von Dateien über Speichern unter funktioniert und ist für WebView2 für UWP-Apps aktiviert. Die Dateien werden in dem Ordner gespeichert, den der Benutzer auswählt.

In welchen Ordner die Dateien heruntergeladen werden?

Wenn der Host die ResultFilePath heruntergeladene Datei nicht ändert, werden die heruntergeladenen Dateien in einen Unterordner mit dem Namen des App-Pakets im Downloads Ordner heruntergeladen.

Wenn der Host die ResultFilePath der heruntergeladenen Datei ändert, wird die Datei nur heruntergeladen, wenn die App standardmäßig Zugriff auf diesen Dateipfad hat. Wenn Sie einen Dateispeicherort verwenden möchten, auf den die App standardmäßig keinen Zugriff hat, müssen Sie die entsprechende Funktion festlegen. Weitere Informationen finden Sie unter App-Funktionsdeklarationen in der UWP-Dokumentation.

Download-Hub

Das Öffnen von Dateien und Ordnern aus dem Downloads-Hub ist deaktiviert. Wenn Sie auf das Datei- oder Ordnersymbol klicken, wird die entsprechende Datei/der entsprechende Ordner nicht geöffnet.

Siehe auch:

• Downloads unter Übersicht über WebView2-Features und -APIs.

XAML-Einschränkung

Die XAML Island-Unterstützung erfordert zusätzlichen Aufwand und kann für zukünftige Releases in Betracht gezogen werden.

Festlegen von DefaultBackgroundColor

Auf WinUI 2 wird die DefaultBackgroundColor Eigenschaft nicht direkt verfügbar gemacht. Sie können die Standardhintergrundfarbe festlegen, indem Sie eine Umgebungsvariable wie folgt festlegen:

Environment.SetEnvironmentVariable("WEBVIEW2_DEFAULT_BACKGROUND_COLOR", "FF000000");

Siehe auch:

• .NET: WebView2.DefaultBackgroundColor-Eigenschaft
• Win32: ICoreWebView2Controller2::D efaultBackgroundColor-Eigenschaft (get, put)

Festlegen der Transparenz

In WinUI 2 wird Transparenz erreicht, indem die Farbe auf 00FFFFFFfestgelegt wird.

CSS-Cursor

In WinUI 2 (UWP) gelten für CSS-Cursor die folgenden Einschränkungen.

Bild-URLs

Der CSS-Cursor darf keine Bild-URL sein, z cursor: url(https://contoso.com/cursor.png), pointer;. B. . Weitere Informationen finden Sie unter CSS : Der aus der URL geladene Cursor funktioniert nicht.

Vordefinierte CSS-Cursor

In WinUI 2 (UWP) werden einige der vordefinierten CSS-Cursor nicht unterstützt. Sie können CSS-Cursor verwenden, um den Cursor auf einige der vordefinierten Cursor wie oder zu ändern, cursor: wait; aber nicht auf andere, zcursor: progress. B. oder cursor: none.cursor: crosshair;

Schlüsselwort	Unterstützt?
Allgemein
Auto	✔️
Standard	✔️
keine	❌
Links & status
Kontextmenü	✔️
Hilfe	✔️
Zeiger	✔️
Progress	❌
Warte	✔️
Selection
Zelle	❌
Fadenkreuz	✔️
text	✔️
Vertikaler Text	❌
Ziehen & Ablegen
alias	❌
Kopieren	❌
verschieben	✔️
no-drop	✔️
nicht zulässig	✔️
Greifen	❌
Greifen	❌
Ändern der Größe & Scrollens
All-scroll	✔️
col-resize	❌
Zeilengröße ändern	❌
n-Größe ändern	✔️
E-Größe ändern	✔️
s-resize	✔️
w-größe ändern	✔️
ne-resize	✔️
nw-resize	✔️
se-resize	✔️
sw-resize	✔️
ew-resize	✔️
ns-resize	✔️
nesw-resize	✔️
nwse-resize	✔️
Zoomen
Vergrößern	❌
Verkleineren	❌

Siehe auch:

• CSS-Cursor: Im Abschnitt Werte werden die oben genannten Schlüsselwort (keyword) Werte beschrieben.

Microsoft Edge-Entwicklertools

Unter WinUI 2 können Microsoft Edge DevTools nicht in einer store-signierten WebView2 WinUI 2(UWP)-App gestartet werden. Sie können dies jedoch umgehen, indem Sie das Remotedebuggen verwenden. Weitere Informationen finden Sie unter Remotedebuggen von WebView2 WinUI 2-Apps (UWP).

API-Einschränkungen

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

• CoreWebView2EnvironmentOptions
• CoreWebView2ControllerOptions

Siehe auch

• WebView2-API-Referenz
• WinUI 2-Beispiel-App (UWP): Schritte zum Herunterladen, Aktualisieren, Erstellen und Ausführen des WinUI 2 WebView2-Beispiels.
• Verwalten von Benutzerdatenordnern
• Beispielcode für WebView2 : Eine Anleitung zum WebView2Samples Repository.
• Bewährte Entwicklungsmethoden für WebView2-Apps

Github:

• WebView2Samples-Repository
• WebView2-UWP-Beispiel-App : WebView2-Beispiel für WinUI 2 (UWP).
• Probleme – microsoft-ui-xaml-Repository – zum Eingeben von WinUI-spezifischen Featureanforderungen oder Fehlern.
• Im Gegensatz zu einigen anderen Tutorials gibt es keine vollständige Version dieses Erste Schritte Tutorials im WebView2Samples-Repository.
• NuGet-Paket "Microsoft.UI.Xaml"
• Medien-App-Beispiele für Xbox