Kits de développement logiciel (SDK) de version préliminaire et de version pour WebView2

Le SDK WebView2 est fourni en tant que version préliminaire ou commerciale du package Microsoft.Web.WebView2 NuGet. Utilisez soit un SDK de préversion avec un canal d’aperçu de Microsoft Edge, soit utilisez un SDK de mise en production avec le runtime WebView2.

Contenu détaillé :

Introduction

Avant-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 que la prise en charge de ces API ne soit ajoutée au Runtime. Le canal Canary est recommandé, car il contient les implémentations des API les plus récentes. Lorsque vous souhaitez tester et utiliser les API WebView2 expérimentales, utilisez la combinaison suivante :

  • Une version préliminaire du SDK WebView2.
  • Canal d’aperçu de Microsoft Edge sur votre client de développement.

Version 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 :

  • Une version commerciale du SDK WebView2.
  • Le runtime WebView2 sur votre client de développement.

Vous trouverez ci-dessous plus de détails sur les packages SDK de version préliminaire et de publication.

Phases de présentation des API

Les nouvelles API sont introduites par phases comme suit :

Status de l’API Description
Expérimental dans un SDK en version préliminaire 1. Tout d’abord, une API est expérimentale dans un SDK de préversion. (Parfois, les API ignorent la phase expérimentale et sont ajoutées directement dans un SDK stable dans la version préliminaire.) Vous pouvez tester ces API et fournir des commentaires. L’API n’est pas encore dans un SDK de mise en production.
Stable dans un Kit de développement logiciel (SDK) version préliminaire 2. Ensuite, l’API est promue stable dans le Kit de développement logiciel (SDK) version préliminaire. L’API n’est pas encore dans un SDK de mise en production.
Stable dans un SDK de mise en production 3. Ensuite, l’API stable est promue pour être incluse dans le SDK de mise en production. (Parfois, les API sont simultanément promues stables dans un SDK de préversion et stables dans un SDK de version.) Cela se produit généralement 1 mois après la promotion de l’API à stable dans un kit de développement logiciel (SDK) en version préliminaire. L’API est également conservée dans la version préliminaire du Kit de développement logiciel (SDK).

Diagramme des phases d’introduction de nouvelles API

Voir aussi :

Sélection du type de SDK à utiliser

Pour sélectionner la version du package NuGet du SDK WebView2 utilisée par un projet Visual Studio, 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 version préliminaire , 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 de détails, consultez Installer ou mettre à jour le 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 version préliminaire du Kit de développement logiciel (SDK) avec un canal d’aperçu de Microsoft Edge

Lorsque vous développez une application WebView2 Evergreen, testez régulièrement l’application par rapport au dernier canal d’aperçu 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 WebView2 Prerelease SDK, utilisez un canal d’aperçu Microsoft Edge sur votre client de développement. Les canaux d’aperçu sont également appelés canaux Insiders . Nous recommandons d’utiliser le canal d’aperçu de Canary plutôt que Bêta ou Dev, car Canary est le plus récent et comporte des implémentations des dernières API expérimentales.

Le package du Kit de développement logiciel (SDK) de la version préliminaire est un sur-ensemble du package du Kit de développement logiciel (SDK) de la version préliminaire. Un Kit de développement logiciel (SDK) de version préliminaire 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 SDK de mise en production.
  • API stables ajoutées aux SDK de mise en production.

Les canaux de prévisualisation 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 SDK de préversion 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 d’utiliser par défaut WebView2 Runtime, consultez Basculer vers un canal d’aperçu pour tester les API et fonctionnalités à venir.

Voir aussi :

Utiliser une version commerciale du SDK avec le runtime

Lorsque vous utilisez un package WebView2 Release SDK, utilisez Evergreen WebView2 Runtime sur votre client de développement, plutôt qu’un canal d’aperçu Microsoft Edge. Par défaut, une application WebView2 cible le Runtime plutôt que Microsoft Edge. Par conception, le canal stable Microsoft Edge ne prend pas en charge WebView2.

Le package Release SDK contient toutes les API stables qui sont dans la version de production et n’inclut pas les signatures de méthode pour les API expérimentales. Toutes les API incluses dans un package SDK Release sont entièrement prises en charge, dans un nombre de versions égal ou supérieur du runtime WebView2.

Voir aussi :

Pour plus d’informations sur la mise à jour automatique du runtime Evergreen, consultez les ressources suivantes :

Cadence de publication

Voir :

Version et numéro de build minimum pour instancier WebView2

Pour que le client puisse créer une instance WebView2 et utiliser l’ensemble d’API de la version de disponibilité générale WebView2 (SDK build 616), le client doit disposer de WebView2 Runtime version 86.0.616.0 ou ultérieure. Le 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 avoir la version 86.0.616.0 ou ultérieure du canal d’aperçu Microsoft Edge, ou la version 86.0.616.0 ou ultérieure du runtime WebView2.

Compatibilité descendante des API

Le SDK de version WebView2 est compatible en amont depuis la version 1 (SDK de publication 1.0.622.22, pour Runtime 86 (19 octobre 2020) dans Notes de version archivées pour le SDK WebView2). Vous pouvez mettre à jour votre application WebView2 pour utiliser les dernières API de la version la plus récente du SDK. Votre application continuera à fonctionner sur les clients, car les clients disposent automatiquement de la dernière version d’Evergreen WebView2 Runtime.

Les API WebView2 d’un package SDK Release sont stables et compatibles en amont. 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 du numéro de version en quatre parties pour Microsoft Edge et le runtime WebView2.

  • Lorsque vous utilisez un 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 SDK fonctionne avec cette version du runtime.

  • Lorsque vous utilisez un SDK WebView2 dont le numéro de build est supérieur à celui du 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 fonctionnerait avec le runtime 94.0. 900+.0, mais pas avec Runtime 90.0. 700,0.

Vous devez coordonner la version du SDK WebView2 que vous utilisez pour le développement et la version WebView2 Runtime installée sur les machines clientes. Le client doit avoir une version du runtime qui prend en charge toutes les dernières API incluses 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 API les plus récentes dans une version commerciale 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 kit de développement logiciel (SDK).

API expérimentales

Pour essayer les nouvelles fonctionnalités en développement, utilisez les API expérimentales . Les API expérimentales sont contenues dans les SDK de préversion, mais pas dans les SDK de publication.

Développement avec des API expérimentales et commentaires

Les API expérimentales d’un package WebView2 Prerelease SDK ne sont pas garanties comme étant compatibles en amont et peuvent être supprimées dans les futures mises à jour d’exécution.

Pour une prise en charge complète des API expérimentales, utilisez un canal d’aperçu de 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) ne fonctionne qu’avec Microsoft Edge Canary. Peu de temps après, la version préliminaire du Kit de développement logiciel (SDK) fonctionne également avec les canaux bêta et de développement.

Utilisez un Kit de développement logiciel (SDK) de version préliminaire pour essayer les nouvelles API expérimentales en avant-première et fournir des commentaires avant que les API expérimentales ne soient promues pour devenir des API stables et compatibles en aval.

  • Les API expérimentales (dans un SDK de préversion) ne sont pas garanties comme étant compatibles en aval.
  • Les API stables qui se trouvent dans un SDK de préversion sont compatibles en aval, même si elles ne sont pas encore incluses dans un SDK de publication.
  • Les API stables qui se trouvent dans un SDK Release sont à compatibilité descendante.

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

L’équipe WebView2 recherche des commentaires sur les API WebView2 expérimentales qui pourraient être promues stables dans les prochaines versions. Les API expérimentales sont indiquées comme « expérimentales » dans la documentation de référence du SDK WebView2, par exemple : « Remarque : il s’agit d’une API expérimentale livrée avec notre SDK de préversion. »

Pour vous aider à évaluer les API expérimentales et à partager vos commentaires, utilisez le référentiel WebView2Feedback .

Voir aussi :

Passer d’API expérimentales à des API stables

Une fois qu’une API est passée du statut expérimental au status stable, vous devez déplacer le code de votre application vers l’API stable. L’utilisation d’API expérimentales ou d’un SDK de version préliminaire n’est pas recommandée pour les applications de production. Suivez ces pratiques lors du passage 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 de votre package WebView2 SDK vers un SDK de préversion ou un SDK de publication plus récent. Voir Installer ou mettre à jour le 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 des API expérimentales (pour COM). L’API stable sera prise en charge avec des corrections de bogues, mais l’API expérimentale sera déconseillée et ne sera pas disponible dans le SDK plus récent (version préliminaire ou publiée). Une fois qu’une API est promue à stable, la version expérimentale de cette API est prise en charge pour deux versions du SDK de préversion, dans un état déconseillé. Dans les versions ultérieures du SDK de la version préliminaire, 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. Reportez-vous à la section 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 une version préliminaire du Kit de développement logiciel (SDK) WebView2, les API stables .NET reviennent aux API expérimentales correspondantes, si le runtime WebView2 de l’utilisateur dispose uniquement de l’implémentation de l’API expérimentale et non de l’implémentation de l’API stable.

Mise en correspondance de la version d’exécution 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 à la dernière version disponible. Toutefois, un utilisateur ou un Administration 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 à partir d’un SDK récent.

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

Pour case activée la compatibilité entre des numéros de build spécifiques du SDK et le Runtime ou le canal d’aperçu Microsoft Edge, consultez les notes de publication pour 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 Evergreen Runtime plutôt que la version fixe, vous devez encapsuler tous les appels à des API WebView2 relativement nouvelles à l’aide QueryInterface de ou try-catch. Il existe des cas limites où le runtime Evergreen d’un client n’est pas la dernière build et prend donc du retard sur le numéro de build du kit de développement logiciel (SDK), car l’Administration a peut-être temporairement supprimé la mise à jour du runtime WebView2, ou le client est peut-être hors ligne.

Lorsque vous développez une application WebView2 à l’aide d’une version récente du 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 programme la prise en charge de l’API dépend de la plateforme de codage :

.NET et WinUI et WinRT

Utilisez try/catch et recherchez une No such interface supported exception dans la case activée lors de l’utilisation de méthodes, de propriétés et d’événements ajoutés à des versions plus récentes du 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.

Win32 C/C++

Lorsque vous demandez l’exportation CreateCoreWebView2Environment DLL et lors de l’exécution QueryInterface sur un 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_querydans AppWindow.cpp. Ce fichier encapsule les appels d’API WebView2 dans la CHECK_FAILURE fonction macro, définie dans CheckFailure.h.

Fournir une solution de secours élégante

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

Voir aussi

Documentation Microsoft Edge Entreprise :

Téléchargements :

GitHub :

  • Dernière mise à jour :