Partager via

API en préversion

  • Article

La plateforme .NET est fière de prendre au sérieux la compatibilité. En tant que tel, l’écosystème des bibliothèques tend à éviter les changements cassants, en particulier en ce qui concerne l’API.

Néanmoins, lors de la conception des API, il est important de recueillir les commentaires des utilisateurs et de modifier l’API en fonction de ces commentaires si nécessaire. Pour éviter les surprises, il est important que les utilisateurs sachent quelles API sont considérées comme stables et lesquelles sont encore en cours de développement et pourraient changer.

Il y a plusieurs façons pour une API d’exprimer qu’elle est sous forme de préversion :

  • L’ensemble du composant est considéré comme préversion :

    • Exposé dans une préversion du runtime .NET
    • Exposé dans un package NuGet de préversion

  • Dans le cas contraire, un composant stable marque spécifiquement certaines API comme préversion :

Cet article explique comment choisir entre ces options et comment chacune d’elles fonctionne.

Préversions du runtime .NET

À l’exception des Release Candidates (RCs) avec une licence go-live, les versions de préversion du runtime et du SDK .NET ne sont pas prises en charge.

Ainsi, toutes les API ajoutées dans le cadre d’un aperçu de .NET sont considérées comme susceptibles d’être modifiées, en fonction des commentaires que les préversions reçoivent. Pour utiliser une préversion de runtime .NET, vous devez explicitement cibler une version plus récente du cadre. Ce faisant, vous consentez implicitement à utiliser des API susceptibles d’être modifiées.

Pré-mise en production des packages NuGet

Les packages NuGet peuvent être stables ou marqués comme pré-mise en production, c’est-à-dire que le package a un suffixe pré-mise en production. Par exemple, System.Text.Json 9.0.0-preview.2.24128.5 a un suffixe de pré-mise en production de preview.2.24128.5.

Les auteurs de packages ne prennent généralement pas en charge les paquets en pré-mise en production et les utilisent comme moyen de recueillir les réactions des premiers utilisateurs.

Lors de l’installation de packages, que ce soit via l’interface de gestion ou l’interface utilisateur, vous devez généralement indiquer explicitement si vous souhaitez installer la version pré-mise en production, exprimant ainsi implicitement votre consentement à utiliser des API qui pourraient être modifiées.

RequiresPreviewFeaturesAttribute

Depuis .NET 6, la plateforme inclut l’attribut RequiresPreviewFeaturesAttribute.

Cet attribut est utilisé pour les API qui requièrent des comportements de préversion à travers la pile, y compris le runtime, le compilateur C# et les bibliothèques. Lorsque vous utilisez des API marquées avec cet attribut, vous recevez une erreur de génération, sauf si votre projet définit <EnablePreviewFeatures>true</EnablePreviewFeatures>. Définir cette propriété sur true définit également <LangVersion>Preview</LangVersion>, ce qui permet l’utilisation des fonctionnalités de langage de préversion.

L’équipe .NET a utilisé l’attribut RequiresPreviewFeaturesAttribute dans .NET 6 pour tester les mathématiques génériques, car il nécessitait des membres d’interface statiques, qui étaient en avant-première à l’époque.

ExperimentalAttribute

.NET 8 a ajouté ExperimentalAttribute, qui ne nécessite aucune fonctionnalité en préversion du runtime ou du langage et indique simplement qu’une API donnée n’est pas encore stable.

Lors de la génération sur une API expérimentale, le compilateur génère une erreur. Chaque fonctionnalité marquée comme expérimentale possède son propre ID de diagnostic distinct. Pour exprimer votre consentement à leur utilisation, vous supprimez le diagnostic spécifique. Vous pouvez le faire via l’un des moyens permettant de supprimer les diagnostics, mais la méthode recommandée consiste à ajouter le diagnostic à la propriété <NoWarn> du projet.

Étant donné que chaque fonctionnalité expérimentale possède un identifiant distinct, le fait de consentir à l’utilisation d’une fonctionnalité expérimentale ne signifie pas que l’on consente à l’utilisation d’une autre fonctionnalité.

Pour plus d’informations, consultez Fonctionnalités expérimentales.

Vous avez le choix entre les options :

Les développeurs de bibliothèques ne doivent utiliser que des paquets NuGet pré-version ou marquer les API avec [Experimental] :

  • Pour les nouvelles API introduites dans une version de pré-mise en production de votre package, vous n’avez rien à faire; le package exprime déjà la qualité de la préversion.

  • Si vous souhaitez expédier un package stable qui contient des API de qualité en préversion, vous devez marquer ces API à l’aide de [Experimental]. Veillez à utiliser votre propre ID de diagnostic et à le rendre spécifique à ces fonctionnalités. Si vous avez plusieurs fonctionnalités indépendantes, envisagez d’utiliser plusieurs ID.

L’attribut [RequiresPreviewFeatures] est destiné uniquement aux composants de la plateforme .NET elle-même. Et même là, il n’est utilisé que pour les API qui nécessitent des fonctionnalités en préversion de la langue. S’il s’agit simplement d’une API en préversion, la plateforme .NET utilise l’attribut [Experimental].

L’exception à cette règle est le cas où vous construisez une bibliothèque stable et que vous souhaitez exposer certaines fonctionnalités qui dépendent à leur tour des comportements de runtime ou de préversion de la langue. Dans ce cas, vous devez utiliser [RequiresPreviewFeatures] pour les points d’entrée de cette fonctionnalité. Cependant, vous devez tenir compte du fait que les utilisateurs de ces API doivent également activer les fonctionnalités en préversion, ce qui les expose à tous les comportements de préversion du runtime, de la bibliothèque et de la langue.