Vorabversions- und Release-SDKs für WebView2

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

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

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

Veröffentlichung SDK-Pakete enthalten nur stabile APIs, keine experimentellen APIs. Wenn Sie an einer Produktionsversion Ihrer WebView2-App arbeiten, verwenden Sie die folgende Kombination:

  • Eine Release-Version des WebView2-SDKs.
  • Die WebView2-Runtime auf Ihrem Entwicklungsclient.

Weitere Details zu den Prerelease- und Release-SDK-Paketen finden Sie unten.

Phasen der Einführung von APIs

Neue APIs werden in Phasen wie folgt eingeführt:

API-Status Beschreibung
Experimentell in einem Vorabversions-SDK 1. Erstens ist eine API in einem Vorabversions-SDK experimentell. (Manchmal überspringen APIs die Experimentierphase und werden direkt in ein Stable im Prerelease-SDK hinzugefügt.) Sie können diese APIs testen und Feedback geben. Die API ist noch nicht in einem Release-SDK enthalten.
Stabil in einem Vorabversions-SDK 2. Anschließend wird die API im Prerelease-SDK auf "stabil" heraufgestuft. Die API ist noch nicht in einem Release-SDK enthalten.
Stabil in einem Release-SDK 3. Anschließend wird die Stable-API höhergestuft, um in das Release SDK aufgenommen zu werden. (Manchmal werden APIs gleichzeitig in einem Vorabversions-SDK auf "Stabil" und in einem Release-SDK auf "Stabil" heraufgestuft.) Dies geschieht in der Regel 1 Monat nach der Heraufstufung der API in ein Vorabversions-SDK auf Stable. Die API verbleibt auch im Prerelease-SDK.

Diagramm der Phasen der Einführung neuer APIs

Siehe auch:

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 Sie NuGet-Pakete verwalten aus, aktivieren oder deaktivieren Sie das Kontrollkästchen Vorabversion einschließen , wählen Sie das Microsoft.Web.WebView2-Paket 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 in Einrichten Ihrer Entwicklungsumgebung für WebView2. Sie können die Liste der Microsoft.Web.WebView2 SDK-Pakete auch auf der NuGet-Website anzeigen.

Verwenden Sie eine Vorabversion des SDK zusammen mit einem Vorschaukanal von Microsoft Edge

Wenn Sie eine Evergreen WebView2-App entwickeln, testen Sie die App regelmäßig mit dem neuesten Microsoft Edge-Vorschaukanal, zusätzlich zur WebView2-Runtime. Da sich die Webplattform ständig weiterentwickelt, können Sie durch regelmäßige Tests am besten sicherstellen, dass Ihre App weiterhin wie vorgesehen funktioniert.

Wenn Sie ein WebView2-Vorabversions-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 Implementierungen der neuesten experimentellen APIs enthält.

Das Prerelease 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 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 sich basierend auf Feedback ändern. Vermeiden Sie die Verwendung eines SDK-Vorabversionspakets zum Erstellen von Produktions-Apps.

Informationen zum vorübergehenden Verweisen Ihrer App auf einen Vorschaukanal, anstatt standardmäßig auf die WebView2-Runtime zu verweisen, finden Sie unter Wechseln zu einem Vorschaukanal zum Testen anstehender APIs und Features.

Siehe auch:

Verwenden Sie eine Releaseversion des SDK zusammen mit der Runtime

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

Das Release SDK-Paket enthält alle stabilen APIs der Produktionsversion und keine Methodensignaturen für experimentelle APIs. Alle APIs, die in einem Release SDK-Paket enthalten sind, werden in einer gleichen oder höheren Buildnummer der WebView2-Runtime vollständig unterstützt.

Siehe auch:

Weitere Informationen zum automatischen Aktualisieren der Evergreen Runtime finden Sie unter:

Veröffentlichungsrhythmus

Siehe:

Mindestversions- und Buildnummer zum Instanziieren von WebView2

Damit der Client eine WebView2-Instance erstellen und den Satz von APIs im WebView2-Release für allgemeine Verfügbarkeit (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 das Release für allgemeine Verfügbarkeit handelt.

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

Vorwärtskompatibilität von APIs

Das WebView2-Release-SDK ist seit Version 1 (Release SDK 1.0.622.22, für Runtime 86 (19. Oktober 2020) in Archivierte Versionshinweise für das WebView2-SDK) vorwärtskompatibel. 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 Evergreen WebView2-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, die über eine oder eine höhere Buildnummer als die SDK-Buildnummer verfügt, in der die API eingeführt wurde. Die Buildnummer ist der dritte Teil der vierteiligen Versionsnummer für das Webview2-SDK sowie der vierteiligen Versionsnummer für Microsoft Edge und die WebView2-Runtime.

  • Wenn Sie ein WebView2-SDK verwenden, dessen Buildnummer gleich oder kleiner als die WebView2-Runtime ist, funktioniert jede API, auf die Sie in diesem SDK Zugriff haben, mit dieser Version der Runtime.

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

Zum Beispiel, wenn eine API in SDK 1.0 eingeführt wird. 900.0 verwenden, würde diese API mit der Runtime 94.0 funktionieren. 900+.0, aber nicht mit Runtime 90.0. 700,0.

Sie müssen die WebView2-SDK-Version, die Sie für die Entwicklung verwenden, und die WebView2-Runtimeversion, die auf Clientcomputern installiert ist, koordinieren. Der Client sollte über eine Version der Runtime verfügen, die alle neuesten APIs unterstützt, die in der SDK-Version enthalten sind, die Sie zum Entwickeln der App verwenden. Für die vollständige Unterstützung der neuesten APIs in einer Releaseversion des SDK 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, in der Entwicklung befindliche Features auszuprobieren. 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-Vorabversions-SDK-Paket sind nicht garantiert aufwä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 Evergreen WebView2 Runtime. Wenn eine Vorabversion des WebView2-SDK anfänglich verfügbar gemacht wird, funktioniert dieses SDK nur mit Microsoft Edge Canary. Kurz darauf 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 geben Sie Feedback, bevor die experimentellen APIs zu stabilen, aufwärtskompatiblen APIs heraufgestuft werden.

  • Es ist nicht garantiert, dass die experimentellen APIs (in einem Vorabversions-SDK) aufwärtskompatibel sind.
  • Die Stable-APIs, die in einem Vorabversions-SDK enthalten sind, sind aufwärtskompatibel, auch wenn sie noch nicht in einem Release-SDK enthalten sind.
  • Die Stable-APIs in einem Release-SDK sind vorwärtskompatibel.

Weitere Informationen finden Sie oben unter Vorwärtskompatibilität von APIs.

Das WebView2-Team bittet um Feedback zu experimentellen WebView2-APIs, die in zukünftigen Versionen zu stabilen APIs heraufgestuft werden könnten. Die experimentellen APIs sind in der WebView2 SDK-Referenzdokumentation als "experimentell" gekennzeichnet, 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.

Siehe auch:

Umstieg von experimentellen APIs auf stabile APIs

Sobald eine API vom experimentellen in den stabilen Status verschoben wurde, müssen Sie den Code Ihrer App in die stabile API verschieben. Die Verwendung experimenteller APIs oder eines Vorabversions-SDK wird für Produktions-Apps nicht empfohlen. Befolgen Sie diese Methoden, wenn Sie Ihre App von experimentellen APIs auf die Verwendung stabiler APIs umstellen:

  • 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 in Einrichten Ihrer Entwicklungsumgebung für WebView2.

  • Aktualisieren Sie den Code Ihrer App, um stabile 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 auf Stable heraufgestuft wurde, wird die experimentelle Version dieser API für zwei Versionen des Prerelease-SDKs unterstützt, allerdings in einem veralteten Zustand. In nachfolgenden Versionen des Prerelease-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 Benutzerversion der WebView2-Runtime implementiert ist. Siehe Featureerkennung, um zu testen, ob die installierte Runtime kürzlich hinzugefügte APIs unterstützt, unten.

  • Hinweis nur für .NET: In einer Vorabversion des WebView2-SDK werden die stabilen .NET-APIs auf die entsprechenden experimentellen APIs zurückgreifen, wenn die WebView2-Runtime des Benutzers nur über die experimentelle API-Implementierung und nicht über die stabile API-Implementierung verfügt.

Übereinstimmung der Runtime-Version 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-Admin 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 kürzlich verwendeten SDK verwendet.

Falls das Aktualisieren der WebView2-Runtime auf dem Client verhindert wird, stellen Sie sicher, dass Sie die Mindestbuildnummer der WebView2-Runtime kennen, die von Ihrer App benötigt wird. 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 mindestens erforderliche Runtime-Version zur Unterstützung der Version für allgemeine Verfügbarkeit des SDK (Build 616) ist älter als die für die neueste Runtime. Die neueste Runtime unterstützt alle APIs, die im neuesten Release SDK enthalten sind.

Informationen zum Überprüfen der Kompatibilität zwischen bestimmten Buildnummern des SDK und der Runtime- oder Microsoft Edge-Vorschaukanäle finden Sie in den Versionshinweisen zu WebView2.

Featureerkennung, um zu testen, ob die installierte Runtime kürzlich hinzugefügte APIs unterstützt

Wenn Ihre App die Evergreen-Runtime anstelle der Fixierten Version verwendet, sollten Sie alle Aufrufe relativ neuer WebView2-APIs mithilfe von QueryInterface oder try-catchumschließen. Es gibt Grenzfälle, in denen die Evergreen-Runtime eines Clients nicht der neueste Build ist und daher hinter die SDK-Buildnummer zurückfällt, weil der Admin möglicherweise die Aktualisierung der WebView2-Runtime vorübergehend unterdrückt 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 "featureerkennen", 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:

.NET und WinUI und WinRT

Verwenden try/catch Sie eine Ausnahme, und suchen Sie 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 deutet wahrscheinlich darauf hin, dass die WebView2-Runtime des Clients eine ältere Version ist, die diese API nicht unterstützt.

Win32 C/C++

Wenn Sie den DLL-Export CreateCoreWebView2Environment anfordern und für ein beliebiges CoreWebView2 Objekt ausgeführt wirdQueryInterface, testen Sie, ob der Rückgabewert von E_NOINTERFACEist. Dieser Rückgabewert deutet wahrscheinlich darauf hin, dass die WebView2-Runtime des Clients eine ältere Version ist, die diese Schnittstelle nicht unterstützt.

Ein Beispiel für die Überprüfung der Existenz 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.

Ordnungsgemäßen Fallback bereitstellen

Wenn Ihr Code feststellt, dass eine API in der installierten WebView2-Runtime des Clients nicht verfügbar ist, sollten Sie ein ordnungsgemäßes Fallback für das zugeordnete Feature bereitstellen oder den Benutzer darüber informieren, dass er die WebView2-Runtime aktualisieren muss, um das Feature verwenden zu können.

Siehe auch

Dokumentation für Microsoft Edge Enterprise:

Downloads:

GitHub:

  • Last updated on