Comprendre les différentes versions du Kit de développement logiciel (SDK) WebView2

  • Article

Le Kit de développement logiciel (SDK) WebView2 est fourni sous la forme d’une préversion ou d’une version release du package NuGet Microsoft.Web.WebView2 . Utilisez un Kit de développement logiciel (SDK) préversion avec un canal d’aperçu de Microsoft Edge, ou utilisez un Kit de développement logiciel (SDK) Release avec le runtime WebView2.

Préversion Les packages sdk sont à utiliser pendant le développement si vous souhaitez tester les dernières API WebView2, y compris les API expérimentales, avant d’ajouter la prise en charge de ces API au runtime. Le canal Canary est recommandé, car il dispose des implémentations des dernières API. Lorsque vous souhaitez tester et utiliser des API WebView2 expérimentales, utilisez la combinaison suivante :

  • Version préliminaire du Kit de développement logiciel (SDK) WebView2.
  • Un canal en préversion de Microsoft Edge sur votre client de développement.

Libération Les packages sdk contiennent uniquement des API stables, et non des API expérimentales. Lorsque vous travaillez sur une version de production de votre application WebView2, utilisez la combinaison suivante :

  • Version release du Kit de développement logiciel (SDK) WebView2.
  • Runtime WebView2 sur votre client de développement.

Vous trouverez ci-dessous plus d’informations sur les packages du Kit de développement logiciel (SDK) de préversion et de mise en production.

Phases d’introduction des API

Les nouvelles API sont introduites en phases comme suit :

status d’API Description
Expérimental 1. Tout d’abord, une API est expérimentale dans un SDK préversion. Vous pouvez tester ces API et fournir des commentaires. L’API n’est pas encore dans un Kit de développement logiciel (SDK) release.
Stable dans un Kit de développement logiciel (SDK) préversion 2. Ensuite, l’API est promue stable dans le Kit de développement logiciel (SDK) préversion. L’API n’est pas encore dans un Kit de développement logiciel (SDK) release.
Stable dans un Kit de développement logiciel (SDK) release 3. Ensuite, l’API stable est promue pour être incluse dans le Kit de développement logiciel (SDK) release. Cela se produit généralement 1 mois après que l’API est promue stable dans un KIT DE développement logiciel (SDK) préversion. L’API reste également dans le Kit de développement logiciel (SDK) préversion.

Diagramme des phases d’introduction de nouvelles API

Sélection du type de KIT de développement logiciel (SDK) à utiliser

Pour sélectionner la version du package NuGet du Kit de développement logiciel (SDK) WebView2 qu’un projet Visual Studio utilise, dans Visual Studio, cliquez avec le bouton droit sur un projet, sélectionnez Gérer les packages NuGet, cochez ou décochez la case Inclure la préversion , sélectionnez le package Microsoft.Web.WebView2 , puis, dans la liste déroulante Version , sélectionnez une version du package NuGet Microsoft.Web.WebView2 .

Pour plus d’informations, consultez Installer ou mettre à jour le Kit de développement logiciel (SDK) WebView2 dans Configurer votre environnement de développement pour WebView2. Vous pouvez également afficher la liste des packages du Kit de développement logiciel (SDK) Microsoft.Web.WebView2 sur le site NuGet.

Utiliser une préversion du Kit de développement logiciel (SDK) ainsi qu’un canal d’aperçu de Microsoft Edge

Lors du développement d’une application Evergreen WebView2, testez régulièrement l’application par rapport au dernier canal de préversion de Microsoft Edge, en plus de tester le runtime WebView2. Étant donné que la plateforme web évolue constamment, des tests réguliers sont le meilleur moyen de s’assurer que votre application continuera à fonctionner comme prévu.

Lorsque vous utilisez un package sdk de préversion WebView2, utilisez un canal de préversion Microsoft Edge sur votre client de développement. Les canaux d’aperçu sont également appelés canaux Insiders . Le canal d’évaluation Canary est recommandé plutôt que bêta ou dev, car Canary est le plus récent et a des implémentations des dernières API expérimentales.

Le package du KIT de développement logiciel (SDK) préversion est un sur-ensemble du package du Kit de développement logiciel (SDK) release. Un Kit de développement logiciel (SDK) préversion contient des signatures de méthode pour :

  • API expérimentales.
  • API stables qui ne sont plus expérimentales, mais qui n’ont pas encore été incluses dans un Kit de développement logiciel (SDK) release.
  • API stables qui ont été ajoutées aux Kits de développement logiciel (SDK) release.

Les canaux d’aperçu de Microsoft Edge fournissent les implémentations des API WebView2 expérimentales et des API stables. Les API expérimentales sont susceptibles d’être modifiées en fonction des commentaires. Évitez d’utiliser un package de préversion du SDK pour créer des applications de production.

Pour plus d’informations sur le pointage temporaire de votre application vers un canal d’aperçu au lieu de passer par défaut au runtime WebView2, consultez Tester les API et fonctionnalités à venir.

Voir aussi :

Utiliser une version release du Kit de développement logiciel (SDK) avec le runtime

Lorsque vous utilisez un package du Kit de développement logiciel (SDK) WebView2 Release, utilisez le runtime Evergreen WebView2 sur votre client de développement, plutôt qu’un canal de préversion Microsoft Edge. Par défaut, une application WebView2 cible le runtime plutôt que Microsoft Edge. Par défaut, le canal Stable Microsoft Edge ne prend pas en charge WebView2.

Le package du Kit de développement logiciel (SDK) Release contient toutes les API Win32 stables C/C++ et .NET en production, et n’inclut pas les signatures de méthode pour les API expérimentales. Toutes les API qui se trouvent dans un package du Kit de développement logiciel (SDK) release sont entièrement prises en charge, dans un numéro de build égal ou supérieur du runtime WebView2.

Le package du Kit de développement logiciel (SDK) Release contient les composants suivants :

Pour plus d’informations sur la mise à jour automatique du runtime Evergreen, consultez Distribuer votre application et le runtime WebView2.

Cadence de mise en production

Les nouvelles versions du Kit de développement logiciel (SDK) WebView2 sont fournies à la même cadence générale que le navigateur Microsoft Edge, soit environ toutes les quatre semaines.

Version et numéro de build minimum pour instancier WebView2

Pour que le client puisse créer un instance WebView2 et utiliser l’ensemble d’API dans la version en disponibilité générale de WebView2 (sdk build 616), le client doit disposer de WebView2 Runtime version 86.0.616.0 ou ultérieure. Runtime 86.0.616.0 est une version spéciale, car il s’agit de la version en disponibilité générale.

Sur un ordinateur de développement, le client doit disposer du canal Microsoft Edge version 86.0.616.0 ou ultérieure, ou du runtime WebView2 version 86.0.616.0 ou ultérieure.

Compatibilité descendante des API

Le Kit de développement logiciel (SDK) webView2 est compatible avec l’avant depuis la version 1 (version 1.0.622.22 dans notes de publication archivées pour le Kit de développement logiciel (SDK) WebView2). Vous pouvez mettre à jour votre application WebView2 pour utiliser les DERNIÈRES API de la version release la plus récente du Kit de développement logiciel (SDK). Votre application continuera à fonctionner sur les clients, car les clients disposent automatiquement du dernier runtime Evergreen WebView2.

Les API WebView2 d’un package du Kit de développement logiciel (SDK) release sont stables et compatibles avec l’avant. Une API WebView2 fonctionne lors de l’utilisation d’un runtime WebView2 dont le numéro de build est égal ou supérieur au numéro de build du Kit de développement logiciel (SDK) dans lequel l’API a été introduite. Le numéro de build est la troisième partie du numéro de version en quatre parties pour le Kit de développement logiciel (SDK) Webview2 et le numéro de version en quatre parties pour Microsoft Edge et le runtime WebView2.

  • Lorsque vous utilisez un Kit de développement logiciel (SDK) WebView2 dont le numéro de build est égal ou inférieur à celui du runtime WebView2, chaque API à laquelle vous avez accès dans ce KIT de développement logiciel (SDK) fonctionne avec cette version du runtime.

  • Lorsque vous utilisez un Kit de développement logiciel (SDK) WebView2 dont le numéro de build est supérieur au runtime WebView2, les implémentations des API les plus récentes ne sont pas disponibles dans le runtime.

Par exemple, si une API est introduite dans le SDK 1.0. 900.0, cette API fonctionne avec Runtime 94.0. 900+.0, mais pas avec Runtime 90.0. 700.0.

Vous devez coordonner la version du Kit de développement logiciel (SDK) WebView2 que vous utilisez pour le développement et la version du runtime WebView2 installée sur les ordinateurs clients. Le client doit disposer d’une version du runtime qui prend en charge toutes les DERNIÈRES API qui se trouvent dans la version du KIT de développement logiciel (SDK) que vous utilisez pour développer l’application. Pour une prise en charge complète des dernières API dans une version release du KIT de développement logiciel (SDK), le runtime sur le client doit avoir un numéro de build supérieur ou égal au numéro de build du SDK.

API expérimentales

Pour tester les nouvelles fonctionnalités en cours de développement, utilisez des API expérimentales . Les API expérimentales sont contenues dans les Kits de développement logiciel (SDK) préversion, mais pas dans les KITS DE développement logiciel (SDK) Release.

Développement avec des API expérimentales et commentaires

Il n’est pas garanti que les API expérimentales d’un package sdk de préversion WebView2 soient compatibles avec l’avant et qu’elles peuvent être supprimées dans les futures mises à jour du runtime.

Pour une prise en charge complète des API expérimentales, utilisez un canal de préversion Microsoft Edge, et non le runtime Evergreen WebView2. Lorsqu’une version préliminaire du Kit de développement logiciel (SDK) WebView2 est initialement mise à disposition, ce KIT de développement logiciel (SDK) fonctionne uniquement avec Microsoft Edge Canary. Peu de temps après cela, le Kit de développement logiciel (SDK) préversion fonctionne également avec les canaux Bêta et Dev.

Utilisez un Kit de développement logiciel (SDK) de préversion pour tester rapidement de nouvelles API expérimentales et fournir des commentaires avant que les API expérimentales ne soient promues pour devenir des API stables et compatibles avec l’avance.

  • Il n’est pas garanti que les API expérimentales (dans un Kit de développement logiciel (SDK) soient compatibles avec les versions préliminaires.
  • Les API stables qui se trouvent dans un KIT de développement logiciel (SDK) préversion sont compatibles avec les versions antérieures, même si elles ne sont pas encore incluses dans un Kit de développement logiciel (SDK) release.
  • Les API stables qui se trouvent dans un Kit de développement logiciel (SDK) release sont compatibles avec l’avant.

Pour plus d’informations, consultez Compatibilité des API, ci-dessus.

L’équipe WebView2 recherche des commentaires sur les API WebView2 expérimentales qui pourraient être promues à Stable dans les versions ultérieures. Les API expérimentales sont indiquées comme « expérimentales » dans la documentation de référence du Kit de développement logiciel (SDK) WebView2, par exemple : « Remarque : Il s’agit d’une API expérimentale fournie avec notre kit sdk de préversion ».

Pour vous aider à évaluer les API expérimentales et à partager vos commentaires, utilisez le dépôt WebView2Feedback .

Passage d’API expérimentales à des API stables

Une fois qu’une API a été déplacée d’une status expérimentale vers status stable, vous devez déplacer le code de votre application vers l’API stable. L’utilisation d’API expérimentales ou d’un Kit de développement logiciel (SDK) de préversion n’est pas recommandée pour les applications de production. Suivez ces pratiques lors du déplacement de votre application de l’utilisation d’API expérimentales à l’utilisation d’API stables :

  • Dans votre projet dans Visual Studio, mettez à jour la version du package du Kit de développement logiciel (SDK) WebView2 vers un KIT de développement logiciel (SDK) de préversion ou de mise en production plus récent. Consultez Installer ou mettre à jour le Kit de développement logiciel (SDK) WebView2 dans Configurer votre environnement de développement pour WebView2.

  • Mettez à jour le code de votre application pour utiliser des API stables au lieu d’API expérimentales (pour COM). L’API stable sera prise en charge avec des correctifs de bogues, mais l’API expérimentale sera déconseillée et n’est pas disponible dans le sdk (préversion ou version) plus récent. Une fois qu’une API est promue stable, la version expérimentale de cette API est prise en charge pour deux versions du Kit de développement logiciel (SDK) préversion, dans un état déconseillé. Dans les versions ultérieures du Kit de développement logiciel (SDK) préversion, les API expérimentales peuvent être modifiées, supprimées ou ajoutées.

  • Utilisez toujours la détection des fonctionnalités pour vous assurer que l’API stable est implémentée dans la version de l’utilisateur du runtime WebView2. Consultez Détection des fonctionnalités pour tester si le runtime installé prend en charge les API récemment ajoutées ci-dessous.

  • Remarque pour .NET uniquement : dans un Kit de développement logiciel (SDK) WebView2 préversion, les API stables .NET sont de secours vers les API expérimentales correspondantes, si le runtime WebView2 de l’utilisateur a uniquement l’implémentation de l’API expérimentale et n’a pas l’implémentation de l’API stable.

Mise en correspondance de la version du runtime avec la version du Kit de développement logiciel (SDK)

Dans l’approche de distribution Evergreen, le runtime WebView2 du client est automatiquement mis à jour vers la dernière version disponible. Toutefois, un utilisateur ou un administrateur informatique peut choisir d’empêcher la mise à jour automatique du runtime WebView2. Le runtime obsolète qui en résulte sur le client peut entraîner des problèmes de compatibilité avec votre application WebView2 mise à jour qui utilise de nouvelles API d’un SDK récent.

Si la mise à jour du runtime WebView2 est empêchée sur le client, vérifiez que vous connaissez le numéro de build minimal du runtime WebView2 requis par votre application. Pour afficher ou obtenir les dernières versions du runtime WebView2, consultez Télécharger le runtime WebView2 dans la page Microsoft Edge WebView2 à developer.microsoft.com. La version minimale requise du runtime pour prendre en charge la version en disponibilité générale du Kit de développement logiciel (SDK) (build 616) est antérieure à celle du runtime le plus récent. Le runtime le plus récent prend en charge toutes les API qui se trouvent dans la dernière version du KIT de développement logiciel (SDK).

Pour case activée la compatibilité entre des numéros de build spécifiques du Kit de développement logiciel (SDK) et le canal Runtime ou Microsoft Edge en préversion, consultez notes de publication du Kit de développement logiciel (SDK) WebView2.

Détection de fonctionnalités pour tester si le runtime installé prend en charge les API récemment ajoutées

Si votre application utilise le runtime Evergreen plutôt que la version fixe, vous devez encapsuler tous les appels aux API WebView2 relativement nouvelles à l’aide QueryInterface de ou try-catch. Dans certains cas, le runtime persistant d’un client n’est pas la dernière build et se trouve donc derrière le numéro de build du KIT de développement logiciel (SDK), car le Administration a peut-être désactivé la mise à jour du runtime WebView2 ou le client est peut-être hors connexion.

Lorsque vous développez une application WebView2 à l’aide d’une version récente du Kit de développement logiciel (SDK) WebView2, si vous utilisez une API récemment ajoutée, vous devez tester ou « détecter les fonctionnalités » si cette API est présente dans le runtime WebView2 installé du client. La façon dont votre application teste par programmation la prise en charge des API dépend de la plateforme de codage.

  • Win32 C/C++. Lors de la demande d’exportation CreateCoreWebView2Environment dll et lors de l’exécution QueryInterface sur n’importe quel CoreWebView2 objet, testez la valeur de retour .E_NOINTERFACE Cette valeur de retour indique probablement que le runtime WebView2 du client est une version antérieure qui ne prend pas en charge cette interface.

    Pour obtenir un exemple de vérification de l’existence d’API WebView2 spécifiques dans le runtime, recherchez try_query dans AppWindow.cpp. Ce fichier encapsule les appels de l’API WebView2 dans la CHECK_FAILURE fonction macro, définie dans CheckFailure.h.

  • .NET et WinUI. Utilisez try/catch et case activée pour une No such interface supported exception lors de l’utilisation de méthodes, de propriétés et d’événements ajoutés à des versions plus récentes du Kit de développement logiciel (SDK) WebView2. Cette exception indique probablement que le runtime WebView2 du client est une version antérieure qui ne prend pas en charge cette API.

Si votre code détermine qu’une API n’est pas disponible dans le runtime WebView2 installé du client, vous devez fournir une solution de secours appropriée pour la fonctionnalité associée ou informer l’utilisateur qu’il doit mettre à jour le runtime WebView2 pour utiliser la fonctionnalité.

Cette technique est répertoriée en tant que meilleure pratique de développement WebView2 dans Tester si les API sont prises en charge par le runtime WebView2 installé.