API de prévisualisation
La plateforme .NET prend au sérieux la compatibilité. Ainsi, l'écosystème des bibliothèques a tendance à éviter d'apporter des modifications cassantes, en particulier en ce qui concerne l'API.
Néanmoins, lors de la conception d’API, il est important de pouvoir recueillir des commentaires des utilisateurs et apporter des modifications à l’API en fonction de ces commentaires si nécessaire. Pour éviter les surprises, vous devez comprendre quelles API vous utilisez sont considérées comme stables et celles qui sont toujours en développement actif et peuvent changer.
Il existe plusieurs façons pour une API d’exprimer qu’elle est sous forme d’aperçu :
L’ensemble du composant est considéré comme un aperçu s’il est exposé :
- Dans une préversion du runtime .NET.
- Dans un package NuGet de préversion.
Dans le cas contraire, un composant stable marque des API spécifiques comme préversion avec les attributs suivants :
Cet article explique comment chaque option fonctionne et, pour les développeurs de bibliothèques, comment choisir entre ces options.
Préversions du runtime .NET
À l’exception des candidats à la mise en production avec une licence go-live, les versions préliminaires du runtime .NET et du Kit de développement logiciel (SDK) ne sont pas prises en charge.
Par conséquent, toutes les API ajoutées dans le cadre d'une préversion .NET sont considérées comme susceptibles de changer en fonction des retours reçus lors des aperçus. Pour utiliser une préversion du runtime .NET, vous devez cibler explicitement une version plus récente du framework dans votre projet. En procédant ainsi, vous exprimez implicitement le consentement pour consommer des API susceptibles de changer.
Packages NuGet de préversion
Les packages NuGet peuvent être stables ou en préversion. Les packages de préversion sont marqués comme tels avec un suffixe de préversion sur leur version. Par exemple, l’utilisateur System.Text.Json 9.0.0-preview.2.24128.5 a un suffixe de préversion de preview.2.24128.5.
Les packages de préversion sont couramment utilisés comme moyen de recueillir des commentaires des utilisateurs précoces. Ils ne sont généralement pas pris en charge par leur auteur.
Lorsque vous installez un package, via l’interface cli ou l’interface utilisateur, vous devez indiquer explicitement si vous souhaitez installer une version préliminaire. En procédant ainsi, vous exprimez implicitement le consentement pour consommer des API susceptibles de changer.
RequiresPreviewFeaturesAttribute
L’attribut RequiresPreviewFeaturesAttribute est utilisé pour les API qui nécessitent des comportements d’aperçu sur la pile, notamment le runtime, le compilateur C# et les bibliothèques. Lorsque vous utilisez des API marquées avec cet attribut, vous recevrez une erreur de génération, sauf si votre fichier projet inclut la propriété <EnablePreviewFeatures>true</EnablePreviewFeatures>. La définition de cette propriété sur true définit également <LangVersion>Preview</LangVersion>, ce qui permet l’utilisation des fonctionnalités de langage d’aperçu.
Par exemple, dans .NET 6, la bibliothèque de mathématiques génériques a été marquée avec RequiresPreviewFeaturesAttribute, car elle nécessitait des membres d’interface statique, qui étaient en préversion à l’époque.
ExperimentalAttribute
.NET 8 a ajouté ExperimentalAttribute, qui ne nécessite aucune fonctionnalité d’aperçu 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 le consentement à l’utilisation d’une API expérimentale, 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 a un ID distinct, le consentement à l’utilisation d’une fonctionnalité expérimentale ne consent pas à l’utilisation d’une autre.
Pour plus d’informations, consultez Fonctionnalités expérimentales et l’article du guide C# sur les attributs généraux.
Conseils pour les développeurs de bibliothèques
Les développeurs de bibliothèque doivent généralement exprimer qu’une API est en préversion de l’une des deux manières suivantes :
- Pour les nouvelles API introduites dans une préversion de votre package, vous n'avez rien à faire ; le package exprime déjà la qualité de 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. Même là, il est utilisé uniquement pour les API qui nécessitent des fonctionnalités d’exécution et d’aperçu du langage. S’il s’agit simplement d’une API en préversion, la plateforme .NET utilise l’attribut [Experimental].
L’exception à cette règle est que vous créez une bibliothèque stable et que vous souhaitez exposer certaines fonctionnalités qui dépendent à leur tour des comportements d’aperçu du runtime ou du langage. Dans ce cas, vous devez utiliser [RequiresPreviewFeatures] pour les points d’entrée de cette fonctionnalité. Toutefois, vous devez considérer que les utilisateurs de ces API doivent également activer les fonctionnalités en préversion, ce qui les expose à tous les comportements d’aperçu du runtime, de la bibliothèque et du langage.
