Considérations relatives à la version et à la mise à jour pour les développeurs C#

La compatibilité est un objectif important, car de nouvelles fonctionnalités sont ajoutées au langage C#. Dans presque tous les cas, le code existant peut être recompilé avec une nouvelle version du compilateur sans aucun problème. L’équipe du runtime .NET a également pour objectif de garantir la compatibilité des bibliothèques mises à jour. Dans presque tous les cas, lorsque votre application est lancée à partir d’un runtime mis à jour avec des bibliothèques mises à jour, le comportement est exactement identique à celui des versions précédentes.

La version de langage utilisée pour compiler votre application correspond généralement au moniker de framework cible runtime référencé dans votre projet. Pour plus d’informations sur la modification de la version de langue par défaut, consultez l’article intitulé Configurer votre version de langue. Ce comportement par défaut garantit une compatibilité maximale.

Lorsque des modifications cassants sont introduites, elles sont classées comme suit :

• Changement cassant binaire : un changement cassant binaire provoque un comportement différent, y compris éventuellement un blocage, dans votre application ou bibliothèque lors du lancement à l’aide d’un nouveau runtime. Vous devez recompiler votre application pour incorporer ces modifications. Le fichier binaire existant ne fonctionne pas correctement.
• Modification cassant la source : une modification cassante de source modifie la signification de votre code source. Vous devez modifier le code source avant de compiler votre application avec la dernière version du langage. Votre fichier binaire existant s’exécute correctement avec l’hôte et le runtime plus récents. Notez que pour la syntaxe du langage, une modification cassant la source est également un changement comportemental, tel que défini dans les changements cassants au moment de l’exécution.

Quand une modification cassant binaire affecte votre application, vous devez recompiler votre application, mais vous n’avez pas besoin de modifier le code source. Lorsqu’une modification cassant de source affecte votre application, le fichier binaire existant s’exécute toujours correctement dans les environnements avec le runtime et les bibliothèques mis à jour. Toutefois, vous devez apporter des modifications sources pour recompiler avec la nouvelle version du langage et le runtime. Si une modification est à la fois une rupture de source et une rupture binaire, vous devez recompiler votre application avec la dernière version et effectuer des mises à jour sources.

En raison de l’objectif d’éviter les changements cassants par l’équipe de langage C# et l’équipe d’exécution, la mise à jour de votre application est généralement une question de mise à jour du TFM et de reconstruction de l’application. Toutefois, pour les bibliothèques distribuées publiquement, vous devez évaluer soigneusement votre stratégie pour les tfms prises en charge et les versions de langage prises en charge. Vous pouvez créer une bibliothèque avec des fonctionnalités trouvées dans la dernière version et vous devez vous assurer que les applications créées à l’aide des versions précédentes du compilateur peuvent l’utiliser. Vous pouvez également mettre à niveau une bibliothèque existante et un grand nombre de vos utilisateurs n’ont peut-être pas encore mis à niveau les versions.

Présentation des changements cassants dans vos bibliothèques

Lorsque vous adoptez de nouvelles fonctionnalités de langage dans l’API publique de votre bibliothèque, vous devez évaluer si l’adoption de la fonctionnalité introduit une modification binaire ou de rupture de source pour les utilisateurs de votre bibliothèque. Toutes les modifications apportées à votre implémentation interne qui n’apparaissent pas dans les public interfaces ou protected qui ne sont pas compatibles.

Une modification cassant binaire nécessite que vos utilisateurs recompilent leur code afin d’utiliser la nouvelle version. Par exemple, considérez cette méthode publique :

public double CalculateSquare(double value) => value * value;

Si vous ajoutez le in modificateur à la méthode, il s’agit d’un changement cassant binaire :

public double CalculateSquare(in double value) => value * value;

Les utilisateurs doivent recompiler toutes les applications qui utilisent la CalculateSquare méthode pour que la nouvelle bibliothèque fonctionne correctement.

Une modification cassant la source exige que vos utilisateurs modifient leur code avant de recompiler. Par exemple, considérez ce type :

public class Person
{
    public string FirstName { get; }
    public string LastName { get; }

    public Person(string firstName, string lastName) => (FirstName, LastName) = (firstName, lastName);

    // other details omitted
}

Dans une version plus récente, vous souhaitez tirer parti des membres synthétisés générés pour record les types. Vous apportez la modification suivante :

public record class Person(string FirstName, string LastName);

La modification précédente nécessite des modifications pour n’importe quel type dérivé de Person. Toutes ces déclarations doivent ajouter le record modificateur à leurs déclarations.

Impact des changements cassants

Lorsque vous ajoutez une modification cassant binaire à votre bibliothèque, vous forcez tous les projets qui utilisent votre bibliothèque à recompiler. Toutefois, aucun du code source dans ces projets n’a besoin de changer. Par conséquent, l’impact du changement cassant est raisonnablement faible pour chaque projet.

Lorsque vous apportez une modification cassant de source à votre bibliothèque, vous avez besoin de tous les projets pour apporter des modifications sources afin d’utiliser votre nouvelle bibliothèque. Si la modification nécessaire nécessite de nouvelles fonctionnalités linguistiques, vous forcez ces projets à effectuer une mise à niveau vers la même version de langue et le TFM que vous utilisez maintenant. Vous avez besoin d’un travail supplémentaire pour vos utilisateurs, et éventuellement vous les avez forcés à mettre à niveau.

L’impact de toute modification cassant que vous apportez dépend du nombre de projets qui ont une dépendance sur votre bibliothèque. Si votre bibliothèque est utilisée en interne par quelques applications, vous pouvez réagir aux changements cassants dans tous les projets impactés. Toutefois, si votre bibliothèque est téléchargée publiquement, vous devez évaluer l’impact potentiel et envisager des alternatives :

• Vous pouvez ajouter de nouvelles API qui sont parallèles aux API existantes.
• Vous pouvez envisager des builds parallèles pour différentes tfms.
• Vous pouvez envisager de cibler plusieurs cibles.