Grundlegendes zu den verschiedenen WebView2 SDK-Versionen

  • Artikel

Das WebView2 SDK wird als Vorabversion oder Releaseversion des NuGet-Pakets Microsoft.Web.WebView2 bereitgestellt. Verwenden Sie entweder ein Vorabversions-SDK mit einem Vorschaukanal von Microsoft Edge, oder verwenden Sie ein Release-SDK mit der WebView2-Runtime.

Prerelease SDK-Pakete sind für die Verwendung während der Entwicklung vorgesehen, wenn Sie die neuesten WebView2-APIs, einschließlich der experimentellen APIs, testen möchten, bevor der Runtime Unterstützung für diese APIs hinzugefügt wird. Der Canary-Kanal wird empfohlen, da er über die Implementierungen der neuesten APIs verfügt. Wenn Sie experimentelle WebView2-APIs testen und verwenden möchten, verwenden Sie die folgende Kombination:

  • Eine Vorabversion des WebView2 SDK.
  • Ein Vorschaukanal von Microsoft Edge auf Ihrem Entwicklungsclient.

Release SDK-Pakete enthalten nur stabile APIs, keine experimentellen APIs. Wenn Sie an einem Produktionsrelease Ihrer WebView2-App arbeiten, verwenden Sie die folgende Kombination:

  • Eine Releaseversion des WebView2 SDK.
  • Die WebView2-Runtime auf Ihrem Entwicklungsclient.

Weitere Informationen zu den Paketen prerelease und Release SDK finden Sie unten.

Phasen der Einführung von APIs

Neue APIs werden in folgenden Phasen eingeführt:

API-status Beschreibung
Experimentelle 1. Zunächst ist eine API experimentell in einem Vorabversions-SDK. Sie können diese APIs testen und Feedback geben. Die API befindet sich noch nicht in einem Release-SDK.
Stabil in einem Vorabversions-SDK 2. Anschließend wird die API im Vorabversions-SDK zu Stable heraufgestuft. Die API befindet sich noch nicht in einem Release-SDK.
Stabil in einem Release-SDK 3. Anschließend wird die Stable-API so heraufgestuft, dass sie in das Release SDK aufgenommen wird. Dies geschieht in der Regel 1 Monat, nachdem die API in einem Vorabversions-SDK zu Stable heraufgestuft wurde. Die API verbleibt auch im Vorabversions-SDK.

Diagramm der Phasen der Einführung neuer APIs

Auswählen des zu verwendenden SDK-Typs

Um auszuwählen, welche Version des WebView2 SDK NuGet-Pakets ein Visual Studio-Projekt verwendet, klicken Sie in Visual Studio mit der rechten Maustaste auf ein Projekt, wählen NuGet-Pakete verwalten aus, aktivieren oder deaktivieren Sie das Kontrollkästchen Vorabversion einschließen , wählen Sie das Paket Microsoft.Web.WebView2 aus, und wählen Sie dann in der Dropdownliste Version eine Version des Microsoft.Web.WebView2-NuGet-Pakets aus.

Weitere Informationen finden Sie unter Installieren oder Aktualisieren des WebView2 SDK unter Einrichten Ihrer Entwicklungsumgebung für WebView2. Sie können auch die Liste der Microsoft.Web.WebView2 SDK-Pakete auf der NuGet-Website anzeigen.

Verwenden einer Vorabversion des SDK zusammen mit einem Vorschaukanal von Microsoft Edge

Testen Sie bei der Entwicklung einer Evergreen WebView2-App die App regelmäßig mit dem neuesten Microsoft Edge-Vorschaukanal, zusätzlich zu Tests mit der WebView2-Runtime. Da die Webplattform ständig weiterentwickelt wird, sind regelmäßige Tests die beste Möglichkeit, um sicherzustellen, dass Ihre App weiterhin wie beabsichtigt funktioniert.

Wenn Sie ein WebView2 Prerelease SDK-Paket verwenden, verwenden Sie einen Microsoft Edge-Vorschaukanal auf Ihrem Entwicklungsclient. Vorschaukanäle werden auch als Insider-Kanäle bezeichnet. Der Canary-Vorschaukanal wird anstelle von Beta oder Dev empfohlen, da Canary die neueste Version ist und über Implementierungen der neuesten experimentellen APIs verfügt.

Das Vorabversions-SDK-Paket ist eine Obermenge des Release SDK-Pakets. Ein Vorabversions-SDK enthält Methodensignaturen für:

  • Experimentelle APIs.
  • Stabile APIs, die nicht mehr experimentell sind, aber noch nicht in einem Release SDK enthalten sind.
  • Stabile APIs, die zu Release-SDKs hinzugefügt wurden.

Vorschaukanäle von Microsoft Edge stellen die Implementierungen von experimentellen WebView2-APIs und stabilen APIs bereit. Die experimentellen APIs können basierend auf Feedback geändert werden. Vermeiden Sie die Verwendung eines Vorabversions-SDK-Pakets zum Erstellen von Produktions-Apps.

Informationen dazu, wie Sie Ihre App vorübergehend auf einen Vorschaukanal verweisen, anstatt standardmäßig auf die WebView2-Runtime zu verweisen, finden Sie unter Testen anstehender APIs und Features.

Verwenden einer Releaseversion des SDK zusammen mit der Runtime

Wenn Sie ein WebView2 Release SDK-Paket verwenden, verwenden Sie die WebView2 Evergreen Runtime auf Ihrem Entwicklungsclient anstelle eines Microsoft Edge-Vorschaukanals. Standardmäßig ist eine WebView2-App auf die Runtime und nicht auf Microsoft Edge ausgerichtet. Der Microsoft Edge Stable-Kanal unterstützt WebView2 standardmäßig nicht.

Das Release SDK-Paket enthält alle Stable Win32 C/C++- und .NET-APIs, die sich in der Produktionsversion befinden, und enthält keine Methodensignaturen für experimentelle APIs. Alle APIs, die sich in einem Release SDK-Paket befinden, werden vollständig unterstützt, und zwar in einer gleichen oder einer höheren Buildnummer der WebView2-Runtime.

Das Release SDK-Paket enthält die folgenden Komponenten:

Weitere Informationen zum automatischen Aktualisieren der Evergreen Runtime finden Sie unter Verteilen Ihrer App und der WebView2-Runtime.

Releaserhythmus

Neue Versionen des WebView2 SDK werden im gleichen allgemeinen Rhythmus wie der Microsoft Edge-Browser ausgeliefert, der ungefähr alle vier Wochen erfolgt.

Mindestversion und Buildnummer zum Instanziieren von WebView2

Damit der Client eine WebView2-instance erstellen und den Satz von APIs im WebView2 General Availability Release (SDK Build 616) verwenden kann, muss der Client über webView2 Runtime Version 86.0.616.0 oder höher verfügen. Runtime 86.0.616.0 ist ein spezielles Release, da es sich um die Allgemeinverfügbarkeitsversion handelt.

Auf einem Entwicklungscomputer muss der Client entweder über die Microsoft Edge-Vorschaukanalversion 86.0.616.0 oder höher oder die WebView2-Runtime-Version 86.0.616.0 oder höher verfügen.

Vorwärtskompatibilität von APIs

Das WebView2-Release-SDK ist seit Version 1 vorwärtskompatibel (Release SDK 1.0.622.22 in archivierten Versionshinweisen für das WebView2 SDK). Sie können Ihre WebView2-App aktualisieren, um die neuesten APIs aus der neuesten Releaseversion des SDK zu verwenden. Ihre App funktioniert weiterhin auf Clients, da Clients automatisch über die neueste WebView2 Evergreen Runtime verfügen.

Die WebView2-APIs in einem Release SDK-Paket sind stabil und vorwärtskompatibel. Eine WebView2-API funktioniert, wenn eine WebView2-Runtime verwendet wird, deren Buildnummer gleich oder höher als die SDK-Buildnummer ist, in der die API eingeführt wurde. Die Buildnummer ist der dritte Teil der vierteiligen Versionsnummer für das Webview2 SDK und der vierteiligen Versionsnummer für Microsoft Edge und die WebView2-Runtime.

  • Wenn Sie ein WebView2 SDK verwenden, das über eine Buildnummer gleich oder kleiner als die WebView2-Runtime verfügt, funktioniert jede API, auf die Sie in diesem SDK Zugriff haben, mit dieser Version der Runtime.

  • Wenn Sie ein WebView2 SDK verwenden, dessen Buildnummer größer als die WebView2-Runtime ist, sind die implementierungen der neueren APIs in der Runtime nicht verfügbar.

Beispiel: Eine API wird in SDK 1.0 eingeführt. 900.0: Diese API würde mit Runtime 94.0 funktionieren. 900+.0, jedoch nicht mit Runtime 90.0. 700,0.

Sie müssen die WebView2 SDK-Version, die Sie für die Entwicklung verwenden, und die WebView2-Runtime-Version koordinieren, die auf Clientcomputern installiert ist. Der Client sollte über eine Version der Runtime verfügen, die alle neuesten APIs unterstützt, die sich in der SDK-Version befinden, die Sie zum Entwickeln der App verwenden. Damit die neuesten APIs in einer Releaseversion des SDK vollständig unterstützt werden können, muss die Runtime auf dem Client über eine Buildnummer verfügen, die größer oder gleich der SDK-Buildnummer ist.

Experimentelle APIs

Verwenden Sie experimentelle APIs, um neue zukünftige Features zu testen, die sich in der Entwicklung befinden. Experimentelle APIs sind in Vorabversions-SDKs enthalten, aber nicht in Release-SDKs.

Entwickeln mit experimentellen APIs und Bereitstellen von Feedback

Die experimentellen APIs in einem WebView2 Prerelease SDK-Paket sind nicht garantiert vorwärtskompatibel und werden möglicherweise in zukünftigen Runtime-Updates entfernt.

Verwenden Sie für die vollständige Unterstützung experimenteller APIs einen Microsoft Edge-Vorschaukanal, nicht die WebView2 Evergreen Runtime. Wenn zunächst eine Vorabversion des WebView2 SDK verfügbar gemacht wird, funktioniert dieses SDK nur mit Microsoft Edge Canary. Kurz danach funktioniert das Prerelease SDK auch mit den Beta- und Dev-Kanälen.

Verwenden Sie ein Vorabversions-SDK, um neue experimentelle APIs frühzeitig auszuprobieren und Feedback zu geben, bevor die experimentellen APIs zu stabilen, vorwärtskompatiblen APIs heraufgestuft werden.

  • Die experimentellen APIs (in einem Vorabversions-SDK) sind nicht garantiert vorwärtskompatibel.
  • Die stabilen APIs, die sich in einem Vorabversions-SDK befinden, sind vorwärtskompatibel, auch wenn sie noch nicht in einem Release-SDK enthalten sind.
  • Die stabilen APIs, die sich in einem Release SDK befinden, sind vorwärtskompatibel.

Weitere Informationen finden Sie weiter oben unter Forward Compatibility of APIs (Vorwärtskompatibilität von APIs).

Das WebView2-Team sucht nach Feedback zu experimentellen WebView2-APIs, die in zukünftigen Versionen möglicherweise auf Stable heraufgestuft werden. Die experimentellen APIs werden in der WebView2 SDK-Referenzdokumentation als "experimentell" angegeben, z. B. "Hinweis: Dies ist eine experimentelle API, die mit unserem Vorabversions-SDK ausgeliefert wird."

Verwenden Sie das WebView2Feedback-Repository , um Die experimentellen APIs auszuwerten und Ihr Feedback zu teilen.

Wechseln von experimentellen APIs zu stabilen APIs

Nachdem eine API von Experimental zu Stable status verschoben wurde, müssen Sie den Code Ihrer App in die Stable-API verschieben. Die Verwendung experimenteller APIs oder eines Vorabversions-SDK wird für Produktions-Apps nicht empfohlen. Gehen Sie wie folgt vor, wenn Sie Ihre App von der Verwendung experimenteller APIs zu stabilen APIs verschieben:

  • Aktualisieren Sie in Ihrem Projekt in Visual Studio Ihre WebView2 SDK-Paketversion auf ein neueres Vorabversions-SDK oder Release-SDK. Weitere Informationen finden Sie unter Installieren oder Aktualisieren des WebView2 SDK unter Einrichten Ihrer Entwicklungsumgebung für WebView2.

  • Aktualisieren Sie den Code Ihrer App, um Stable-APIs anstelle von experimentellen APIs (für COM) zu verwenden. Die stable-API wird mit Fehlerbehebungen unterstützt, aber die experimentelle API ist veraltet und im neueren SDK (Vorabversion oder Release) nicht verfügbar. Nachdem eine API zu Stable heraufgestuft wurde, wird die experimentelle Version dieser API für zwei Versionen des Vorabversions-SDK in einem veralteten Zustand unterstützt. In nachfolgenden Versionen des Vorabversions-SDK können experimentelle APIs geändert, entfernt oder hinzugefügt werden.

  • Verwenden Sie immer die Featureerkennung, um sicherzustellen, dass die Stable-API in der Version des Benutzers der WebView2-Runtime implementiert ist. Informationen zum Testen, ob die installierte Runtime kürzlich hinzugefügte APIs unterstützt, finden Sie weiter unten unter Featureerkennung.

  • Hinweis nur für .NET: In einem Vorabversions-WebView2-SDK führen die stabilen .NET-APIs ein Fallback auf die entsprechenden experimentellen APIs aus, wenn die WebView2-Runtime des Benutzers nur über die Implementierung der experimentellen API verfügt und nicht über die Stable-API-Implementierung verfügt.

Abgleichen der Laufzeitversion mit der SDK-Version

Beim Evergreen-Verteilungsansatz wird die WebView2-Runtime des Clients automatisch auf die neueste verfügbare Version aktualisiert. Ein Benutzer oder IT-Administrator kann jedoch die automatische Aktualisierung der WebView2-Runtime verhindern. Die daraus resultierende veraltete Runtime auf dem Client kann Kompatibilitätsprobleme mit Ihrer aktualisierten WebView2-App verursachen, die neue APIs aus einem aktuellen SDK verwendet.

Falls das Aktualisieren der WebView2-Runtime auf dem Client verhindert wird, stellen Sie sicher, dass Sie die minimale Buildnummer der WebView2-Runtime kennen, die für Ihre App erforderlich ist. Informationen zum Anzeigen oder Abrufen der neuesten WebView2-Runtime-Versionen finden Sie unter Herunterladen der WebView2-Runtime auf der Microsoft Edge WebView2-Seite unter developer.microsoft.com. Die erforderliche Runtime-Mindestversion zur Unterstützung der Version "Allgemeine Verfügbarkeit" des SDK (Build 616) ist älter als für die neueste Runtime. Die neueste Runtime unterstützt alle APIs, die im neuesten Release SDK enthalten sind.

Informationen zur Kompatibilität zwischen bestimmten Buildnummern des SDK und dem Runtime- oder Microsoft Edge-Vorschaukanal finden Sie unter Versionshinweise für das WebView2 SDK.

Featureerkennung zum Testen, ob die installierte Runtime kürzlich hinzugefügte APIs unterstützt

Wenn Ihre App die Evergreen Runtime anstelle einer festen Version verwendet, sollten Sie alle Aufrufe von relativ neuen WebView2-APIs mit QueryInterface oder try-catchumschließen. Es gibt Edgefälle, in denen die Evergreen Runtime eines Clients nicht der neueste Build ist und daher hinter die SDK-Buildnummer fällt, da die Admin möglicherweise das Update der WebView2-Runtime deaktiviert hat oder der Client offline ist.

Wenn Sie eine WebView2-App mit einer aktuellen Version des WebView2 SDK entwickeln und eine kürzlich hinzugefügte API verwenden, sollten Sie testen oder "feature-detect", ob diese API in der installierten WebView2-Runtime des Clients vorhanden ist. Wie Ihre App programmgesteuert auf API-Unterstützung testet, hängt von der Codierungsplattform ab.

  • Win32 C/C++. Testen Sie beim Anfordern des DLL-Exports CreateCoreWebView2Environment und bei der Ausführung QueryInterface für ein beliebiges CoreWebView2 Objekt den Rückgabewert .E_NOINTERFACE Dieser Rückgabewert gibt wahrscheinlich an, dass die WebView2-Runtime des Clients eine ältere Version ist, die diese Schnittstelle nicht unterstützt.

    Ein Beispiel für die Überprüfung auf das Vorhandensein bestimmter WebView2-APIs in der Runtime finden Sie try_query unter AppWindow.cpp. Diese Datei umschließt WebView2-API-Aufrufe in der Makrofunktion, die CHECK_FAILURE in definiert ist CheckFailure.h.

  • .NET und WinUI. Verwenden Sie eine Ausnahme, und suchen Sie try/catch nach einer No such interface supported Ausnahme, wenn Sie Methoden, Eigenschaften und Ereignisse verwenden, die neueren Versionen des WebView2 SDK hinzugefügt wurden. Diese Ausnahme weist wahrscheinlich darauf hin, dass die WebView2-Runtime des Clients eine ältere Version ist, die diese API nicht unterstützt.

Wenn Ihr Code feststellt, dass eine API in der auf dem Client installierten WebView2-Runtime nicht verfügbar ist, sollten Sie einen ordnungsgemäßen Fallback für das zugeordnete Feature bereitstellen oder den Benutzer darüber informieren, dass er die WebView2-Runtime aktualisieren muss, um das Feature zu verwenden.

Dieses Verfahren wird unter Testen, ob APIs von der installierten WebView2-Runtime unterstützt werden, als bewährte Methode für die WebView2-Entwicklung aufgeführt.