Modifications qui affectent la compatibilitéChanges that affect compatibility

Tout au long de son histoire, .NET a tenté de maintenir un niveau élevé de compatibilité de version en version et entre les différentes déclinaisons de .NET.Throughout its history, .NET has attempted to maintain a high level of compatibility from version to version and across flavors of .NET. Cette philosophie s’applique toujours avec .NET Core.This continues to be true for .NET Core. Bien que .NET Core peut être considéré comme une nouvelle technologie indépendante du .NET Framework, deux facteurs majeurs limitent la capacité de .NET Core à diverger du .NET Framework :Although .NET Core can be considered as a new technology that is independent of the .NET Framework, two major factors limit the ability of .NET Core to diverge from .NET Framework:

  • Un grand nombre de développeurs ont développé à la base ou continuent à développer des applications .NET Framework.A large number of developers either originally developed or continue to develop .NET Framework applications. Ils s’attendent à un comportement cohérent entre les implémentations de .NET.They expect consistent behavior across .NET implementations.

  • Les projets de bibliothèque .NET Standard permettent aux développeurs de créer des bibliothèques qui ciblent les API communes partagées par .NET Core et .NET Framework..NET Standard library projects allow developers to create libraries that target common APIs shared by .NET Core and .NET Framework. Les développeurs s’attendent à ce qu’une bibliothèque utilisée dans une application .NET Core se comporte comme la bibliothèque utilisée dans une application .NET Framework.Developers expect that a library used in a .NET Core application should behave identically to the same library used in a .NET Framework application.

En plus de la compatibilité entre les implémentations de .NET, les développeurs s’attendent à un haut niveau de compatibilité entre les versions de .NET Core.Along with compatibility across .NET implementations, developers expect a high level of compatibility across .NET Core versions. En particulier, le code écrit pour une version antérieure de .NET Core doit s’exécuter sans problème sur une version ultérieure de .NET Core.In particular, code written for an earlier version of .NET Core should run seamlessly on a later version of .NET Core. En fait, de nombreux développeurs s’attendent à ce que les nouvelles API dans les dernières versions de .NET Core soient également compatibles avec les versions préliminaires dans lesquelles ces API ont été introduites.In fact, many developers expect that the new APIs found in newly released versions of .NET Core should also be compatible with the pre-release versions in which those APIs were introduced.

Cet article décrit les modifications qui affectent la compatibilité et la façon dont l’équipe .NET évalue chaque type de modification.This article outlines changes that affect compatibility and the way in which the .NET team evaluates each type of change. Comprendre comment l’équipe .NET approche des modifications avec rupture possibles est particulièrement utile pour les développeurs qui ouvrent des requêtes de tirage qui modifient le comportement des API .NET existantes.Understanding how the .NET team approaches possible breaking changes is particularly helpful for developers who open pull requests that modify the behavior of existing .NET APIs.

Les sections suivantes décrivent les catégories de modifications apportées aux API .NET Core et leur impact sur la compatibilité des applications.The following sections describe the categories of changes made to .NET Core APIs and their impact on application compatibility. Les modifications sont autorisées ✔️, interdites ❌ ou nécessitent un jugement et une évaluation de la manière prévisible, évidente et cohérente du ❓ comportement précédent.Changes are either allowed ✔️, disallowed ❌, or require judgment and an evaluation of how predictable, obvious, and consistent the previous behavior was ❓.

Notes

  • En plus de servir de guide sur l’évaluation des modifications apportées aux bibliothèques .NET, les développeurs de bibliothèques peuvent également utiliser ces critères pour évaluer les modifications apportées à leurs bibliothèques qui ciblent plusieurs implémentations et versions de .NET.In addition to serving as a guide to how changes to .NET libraries are evaluated, library developers can also use these criteria to evaluate changes to their libraries that target multiple .NET implementations and versions.
  • Pour plus d’informations sur les catégories de compatibilité, par exemple, compatibilité ascendante et descendante, consultez compatibilité.For information about the compatibility categories, for example, forward and backwards compatibility, see Compatibility.

Modifications au contrat publicModifications to the public contract

Les modifications de cette catégorie modifient la surface d’exposition publique d’un type.Changes in this category modify the public surface area of a type. La plupart des modifications de cette catégorie ne sont pas autorisées dans la mesure où elles enfreignent une compatibilité descendante (la possibilité pour une application qui a été développée avec une version précédente d’une API de s’exécuter sans recompilation sur une version ultérieure).Most of the changes in this category are disallowed since they violate backwards compatibility (the ability of an application that was developed with a previous version of an API to execute without recompilation on a later version).

TypesTypes

  • ✔️ autorisé : suppression d’une implémentation d’interface d’un type quand l’interface est déjà implémentée par un type de base✔️ ALLOWED: Removing an interface implementation from a type when the interface is already implemented by a base type

  • Nécessite un jugement : ajout d’une nouvelle implémentation d’interface à un typeREQUIRES JUDGMENT: Adding a new interface implementation to a type

    Il s’agit d’une modification acceptable, car elle n’affectera pas les clients existants.This is an acceptable change because it does not adversely affect existing clients. Toutes les modifications au type doivent fonctionner dans les limites des modifications acceptables définies ici pour la nouvelle implémentation afin de rester acceptables.Any changes to the type must work within the boundaries of acceptable changes defined here for the new implementation to remain acceptable. Une prudence extrême est nécessaire lors de l’ajout d’interfaces qui affectent directement la capacité d’un concepteur ou sérialiseur à générer du code ou des données qui ne peuvent pas être consommées à un bas niveau.Extreme caution is necessary when adding interfaces that directly affect the ability of a designer or serializer to generate code or data that cannot be consumed down-level. Par exemple, l’interface ISerializable.An example is the ISerializable interface.

  • Nécessite un jugement : présentation d’une nouvelle classe de baseREQUIRES JUDGMENT: Introducing a new base class

    Un type peut être introduit dans une hiérarchie entre deux types existants s’il n’introduit pas de nouveaux membres abstraits ou si vous modifiez la sémantique ou le comportement de types existants.A type can be introduced into a hierarchy between two existing types if it doesn't introduce any new abstract members or change the semantics or behavior of existing types. Par exemple, dans .NET Framework 2.0, la classe DbConnection est devenue une classe de base pour SqlConnection, qui était précédemment dérivée directement de Component.For example, in .NET Framework 2.0, the DbConnection class became a new base class for SqlConnection, which had previously derived directly from Component.

  • ✔️ autorisé : déplacement d’un type d’un assembly vers un autre✔️ ALLOWED: Moving a type from one assembly to another

    L' ancien assembly doit être marqué avec le TypeForwardedToAttribute qui pointe vers le nouvel assembly.The old assembly must be marked with the TypeForwardedToAttribute that points to the new assembly.

  • ✔️ autorisé : remplacement d’un type struct par readonly struct un type✔️ ALLOWED: Changing a struct type to a readonly struct type

    La modification readonly struct d’un type en struct type n’est pas autorisée.Changing a readonly struct type to a struct type is not allowed.

  • ✔️ autorisé : ajout du mot clé sealed ou abstract à un type lorsqu’il n’y a aucun constructeur accessible (public ou protégé)✔️ ALLOWED: Adding the sealed or abstract keyword to a type when there are no accessible (public or protected) constructors

  • ✔️ autorisé : extension de la visibilité d’un type✔️ ALLOWED: Expanding the visibility of a type

  • ❌Non autorisé : modification de l’espace de noms ou du nom d’un typeDISALLOWED: Changing the namespace or name of a type

  • ❌Non autorisé : renommer ou supprimer un type publicDISALLOWED: Renaming or removing a public type

    Cela empêche tout code qui utilise le type renommé ou supprimé de fonctionner.This breaks all code that uses the renamed or removed type.

  • Non autorisé : modification du type sous-jacent d’une énumérationDISALLOWED: Changing the underlying type of an enumeration

    Il s’agit d’un changement cassant au niveau de la compilation et du comportement ainsi qu’un changement cassant binaire qui peut rendre les arguments d’attribut non analysables.This is a compile-time and behavioral breaking change as well as a binary breaking change that can make attribute arguments unparsable.

  • ❌Non autorisé : scelle un type qui a été précédemment non scelléDISALLOWED: Sealing a type that was previously unsealed

  • Non autorisé : ajout d’une interface à l’ensemble des types de base d’une interfaceDISALLOWED: Adding an interface to the set of base types of an interface

    Si une interface implémente une interface qu’elle n’implémentait pas précédemment, tous les types implémentant la version d’origine de l’interface cessent de fonctionner.If an interface implements an interface that it previously did not implement, all types that implemented the original version of the interface are broken.

  • Nécessite un jugement : la suppression d’une classe de l’ensemble de classes de base ou d’une interface de l’ensemble des interfaces implémentéesREQUIRES JUDGMENT: Removing a class from the set of base classes or an interface from the set of implemented interfaces

    Il existe une exception à la règle pour la suppression de l’interface : vous pouvez ajouter l’implémentation d’une interface qui dérive de l’interface supprimée.There is one exception to the rule for interface removal: you can add the implementation of an interface that derives from the removed interface. Par exemple, vous pouvez supprimer IDisposable si le type ou l’interface implémente désormais IComponent, qui implémente IDisposable.For example, you can remove IDisposable if the type or interface now implements IComponent, which implements IDisposable.

  • ❌Non **autorisé : modification d’un readonly struct type en type struct **DISALLOWED: Changing a readonly struct type to a struct type

    Toutefois, le changement d’un struct type en readonly struct type est autorisé.The change of a struct type to a readonly struct type is allowed, however.

  • ❌Non autorisé : modification d’un type struct en ref struct type, et vice versaDISALLOWED: Changing a struct type to a ref struct type, and vice versa

  • ❌Non autorisé : réduction de la visibilité d’un typeDISALLOWED: Reducing the visibility of a type

    Toutefois, l’augmentation de la visibilité d’un type est autorisée.However, increasing the visibility of a type is allowed.

MembresMembers

  • ✔️ **autorisé : extension de la visibilité d’un membre qui n’est pas virtuel **✔️ ALLOWED: Expanding the visibility of a member that is not virtual

  • ✔️ **autorisé : ajout d’un membre abstrait à un type public qui n’a pas de constructeurs (publics ou protégés) accessibles , ou le type est sealed **✔️ ALLOWED: Adding an abstract member to a public type that has no accessible (public or protected) constructors, or the type is sealed

    Toutefois, l’ajout à un membre abstrait à un type qui a des constructeurs accessibles (publics ou protégés) et n’est pas sealed n’est pas autorisé.However, adding an abstract member to a type that has accessible (public or protected) constructors and is not sealed is not allowed.

  • ✔️ **autorisé : restriction de la visibilité d’un membre protégé quand le type n’a pas de constructeurs accessibles (publics ou protégés) ou si le type est sealed **✔️ ALLOWED: Restricting the visibility of a protected member when the type has no accessible (public or protected) constructors, or the type is sealed

  • ✔️ autorisé : déplacement d’un membre dans une classe située plus haut dans la hiérarchie que le type à partir duquel il a été supprimé✔️ ALLOWED: Moving a member into a class higher in the hierarchy than the type from which it was removed

  • ✔️ autorisé : ajout ou suppression d’un remplacement✔️ ALLOWED: Adding or removing an override

    L’introduction d’une substitution peut amener les consommateurs précédents à ignorer le remplacement lors de l’appel de la base.Introducing an override might cause previous consumers to skip over the override when calling base.

  • ✔️ autorisé : ajout d’un constructeur à une classe, avec un constructeur sans paramètre si la classe n’avait pas précédemment de constructeurs✔️ ALLOWED: Adding a constructor to a class, along with a parameterless constructor if the class previously had no constructors

    Cependant, ajouter un constructeur à une classe qui n’avait auparavant aucun constructeur sans ajouter le constructeur sans paramètre n’est pas autorisé.However, adding a constructor to a class that previously had no constructors without adding the parameterless constructor is not allowed.

  • ✔️ autorisées : la modification d’un membre de abstract en Virtual✔️ ALLOWED: Changing a member from abstract to virtual

  • ✔️ autorisé : passage d’un ref readonly à une ref valeur de retour (à l’exception des méthodes virtuelles ou des interfaces)✔️ ALLOWED: Changing from a ref readonly to a ref return value (except for virtual methods or interfaces)

  • ✔️ autorisé : suppression de ReadOnly d’un champ, sauf si le type statique du champ est un type valeur mutable✔️ ALLOWED: Removing readonly from a field, unless the static type of the field is a mutable value type

  • ✔️ autorisé : appel d’un nouvel événement qui n’a pas été défini précédemment✔️ ALLOWED: Calling a new event that wasn't previously defined

  • Nécessite un jugement : ajout d’un nouveau champ d’instance à un typeREQUIRES JUDGMENT: Adding a new instance field to a type

    Cette modification a un impact sur la sérialisation.This change impacts serialization.

  • Interdit : renommer ou supprimer un membre ou un paramètre publicDISALLOWED: Renaming or removing a public member or parameter

    Cela empêche tout code qui utilise le membre ou paramètre renommé ou supprimé de fonctionner.This breaks all code that uses the renamed or removed member, or parameter.

    Cela comprend la suppression ou le changement de nom d’une méthode Getter ou Setter d’une propriété, ainsi que l’attribution d’un nouveau nom ou la suppression des membres de l’énumération.This includes removing or renaming a getter or setter from a property, as well as renaming or removing enumeration members.

  • Non autorisé : ajout d’un membre à une interfaceDISALLOWED: Adding a member to an interface

  • ❌Non autorisé : modification de la valeur d’une constante publique ou d’un membre d’énumérationDISALLOWED: Changing the value of a public constant or enumeration member

  • ❌Non autorisé : modification du type d’une propriété, d’un champ, d’un paramètre ou d’une valeur de retourDISALLOWED: Changing the type of a property, field, parameter, or return value

  • ❌Non autorisé : ajout, suppression ou modification de l’ordre des paramètresDISALLOWED: Adding, removing, or changing the order of parameters

  • ❌Non autorisé : ajout ou suppression du mot clé in, out ou ref à partir d’un paramètreDISALLOWED: Adding or removing the in, out , or ref keyword from a parameter

  • ❌Non autorisé : changement de nom d’un paramètre (y compris la modification de sa casse)DISALLOWED: Renaming a parameter (including changing its case)

    Cela est considéré comme un changement cassant pour deux raisons :This is considered breaking for two reasons:

  • ❌Non autorisé : passage d’une ref valeur de retour à une ref readonly valeur de retourDISALLOWED: Changing from a ref return value to a ref readonly return value

  • ❌️Non autorisé : passage d’un ref readonly à une ref valeur de retour sur une méthode ou une interface virtuelle❌️ DISALLOWED: Changing from a ref readonly to a ref return value on a virtual method or interface

  • ❌Non autorisé : ajout ou suppression d’une abstraite d’un membreDISALLOWED: Adding or removing abstract from a member

  • ❌Non autorisé : suppression du mot clé virtuel d’un membreDISALLOWED: Removing the virtual keyword from a member

    Bien que cela n’est souvent pas un changement cassant, car le compilateur C# a tendance à émettre des instructions callvirt en langage intermédiaire pour appeler des méthodes non virtuelles (callvirt effectue une vérification de valeur null, alors qu’un appel normal ne le fait pas), ce comportement n’est pas invariable pour plusieurs raisons :While this often is not a breaking change because the C# compiler tends to emit callvirt Intermediate Language (IL) instructions to call non-virtual methods (callvirt performs a null check, while a normal call doesn't), this behavior is not invariable for several reasons:

    • C# n’est pas le seul langage que .NET cible.C# is not the only language that .NET targets.

    • Le compilateur C# essaie progressivement d’optimiser callvirt en un appel normal chaque fois que la méthode cible est non virtuelle et n’a probablement pas la valeur null (par exemple une méthode accessible via l’opérateur de propagation de NULL ?).The C# compiler increasingly tries to optimize callvirt to a normal call whenever the target method is non-virtual and is probably not null (such as a method accessed through the ?. null propagation operator).

    Rendre une méthode virtuelle signifie que le code consommateur finirait souvent par l’appeler de façon non virtuelle.Making a method virtual means that the consumer code would often end up calling it non-virtually.

  • ❌Non autorisé : ajout du mot clé Virtual à un membreDISALLOWED: Adding the virtual keyword to a member

  • ❌Non autorisé : rendre un membre virtuel abstraitDISALLOWED: Making a virtual member abstract

    Un membre virtuel fournit une implémentation de méthode qui peut être substituée par une classe dérivée.A virtual member provides a method implementation that can be overridden by a derived class. Un membre abstrait ne fournit aucune implémentation et doit être substitué.An abstract member provides no implementation and must be overridden.

  • ❌**Non autorisé : ajout d’un membre abstrait à un type public qui a des constructeurs accessibles (publics ou protégés) et qui n’est pas sealed **DISALLOWED: Adding an abstract member to a public type that has accessible (public or protected) constructors and that is not sealed

  • ❌Non autorisé : ajout ou suppression du mot clé static d’un membreDISALLOWED: Adding or removing the static keyword from a member

  • Non autorisé : ajout d’une surcharge qui exclut une surcharge existante et définit un comportement différentDISALLOWED: Adding an overload that precludes an existing overload and defines a different behavior

    Cela empêche de fonctionner les clients existants qui étaient liés à la surcharge précédente.This breaks existing clients that were bound to the previous overload. Par exemple, si une classe a une seule version d’une méthode qui accepte un UInt32, un consommateur existant est correctement lié à cette surcharge lors du passage d’une valeur Int32.For example, if a class has a single version of a method that accepts a UInt32, an existing consumer will successfully bind to that overload when passing a Int32 value. Toutefois, si vous ajoutez une surcharge qui accepte un Int32 lors de la recompilation ou à l’aide d’une liaison tardive, le compilateur est maintenant lié à la nouvelle surcharge.However, if you add an overload that accepts an Int32, when recompiling or using late-binding, the compiler now binds to the new overload. Si un comportement différent se produit, il s’agit d’un changement cassant.If different behavior results, this is a breaking change.

  • Non autorisé : ajout d’un constructeur à une classe qui n’avait précédemment aucun constructeur sans ajouter le constructeur sans paramètreDISALLOWED: Adding a constructor to a class that previously had no constructor without adding the parameterless constructor

  • ❌️Non autorisé : ajout de ReadOnly à un champ❌️ DISALLOWED: Adding readonly to a field

  • ❌Non autorisé : réduction de la visibilité d’un membreDISALLOWED: Reducing the visibility of a member

    Cela inclut la réduction de la visibilité d’un membre protégé lorsqu’il y a des constructeurs accessibles ( public ou protected ) et que le type n’est pas sealed.This includes reducing the visibility of a protected member when there are accessible (public or protected) constructors and the type is not sealed. Si ce n’est pas le cas, la réduction de la visibilité d’un membre protégé est autorisée.If this is not the case, reducing the visibility of a protected member is allowed.

    L’amélioration de la visibilité d’un membre est autorisée.Increasing the visibility of a member is allowed.

  • ❌Non autorisé : modification du type d’un membreDISALLOWED: Changing the type of a member

    La valeur renvoyée d’une méthode ou le type d’une propriété ou d’un champ ne peut pas être modifiée.The return value of a method or the type of a property or field cannot be modified. Par exemple, la signature d’une méthode qui retourne un Object ne peut pas être modifiée afin de retourner un String, ou vice versa.For example, the signature of a method that returns an Object cannot be changed to return a String, or vice versa.

  • Non autorisé : ajout d’un champ à un struct qui n’avait précédemment aucun ÉtatDISALLOWED: Adding a field to a struct that previously had no state

    Les règles d’affectation autorisent l’utilisation de variables non initialisées tant que le type de variable est un struct sans état.Definite assignment rules allow the use of uninitialized variables so long as the variable type is a stateless struct. Si le struct est avec état, le code pourrait se retrouver avec des données non initialisées.If the struct is made stateful, code could end up with uninitialized data. Il s’agit potentiellement d’un changement cassant binaire et d’un changement cassant source.This is both potentially a source breaking and a binary breaking change.

  • Non autorisé : déclenchement d’un événement existant lorsqu’il n’a jamais été déclenché avantDISALLOWED: Firing an existing event when it was never fired before

Changements de comportementBehavioral changes

AssemblysAssemblies

  • ✔️ autorisé : rendre un assembly portable quand les mêmes plateformes sont toujours prises en charge✔️ ALLOWED: Making an assembly portable when the same platforms are still supported

  • Non autorisé : modification du nom d’un assemblyDISALLOWED: Changing the name of an assembly

  • Non autorisé : modification de la clé publique d’un assemblyDISALLOWED: Changing the public key of an assembly

Propriétés, champs, paramètres et valeurs renvoyéesProperties, fields, parameters, and return values

  • ✔️ autorisé : modification de la valeur d’une propriété, d’un champ, d’une valeur de retour ou d’un paramètre de sortie en un type plus dérivé✔️ ALLOWED: Changing the value of a property, field, return value, or out parameter to a more derived type

    Par exemple, une méthode qui retourne un type Object peut retourner une instance de String.For example, a method that returns a type of Object can return a String instance. (Toutefois, la signature de méthode ne peut pas être modifiée).(However, the method signature cannot change.)

  • ✔️ **autorisé : l’extension de la plage de valeurs acceptées pour une propriété ou un paramètre si le membre n’est pas virtuel **✔️ ALLOWED: Increasing the range of accepted values for a property or parameter if the member is not virtual

    Alors que la plage de valeurs qui peuvent être passées à la méthode ou qui sont retournées par le membre peut être développée, le paramètre ou le type de membre ne peut pas.While the range of values that can be passed to the method or are returned by the member can expand, the parameter or member type cannot. Par exemple, tandis que les valeurs passées à une méthode peuvent s’étendre de 0-124 à 0-255, le type de paramètre ne peut pas être changé de Byte à Int32.For example, while the values passed to a method can expand from 0-124 to 0-255, the parameter type cannot change from Byte to Int32.

  • ❌**Non autorisé : en accroissant la plage de valeurs acceptées pour une propriété ou un paramètre si le membre est virtuel **DISALLOWED: Increasing the range of accepted values for a property or parameter if the member is virtual

    Ce changement empêche le fonctionnement des membres substitués existants, qui ne fonctionneront pas correctement pour la plage de valeurs étendue.This change breaks existing overridden members, which will not function correctly for the extended range of values.

  • ❌Non autorisé : diminution de la plage de valeurs acceptées pour une propriété ou un paramètreDISALLOWED: Decreasing the range of accepted values for a property or parameter

  • ❌Non **autorisé : l’extension de la plage des valeurs retournées pour une propriété, un champ, une valeur de retour ou un paramètre de sortie **DISALLOWED: Increasing the range of returned values for a property, field, return value, or out parameter

  • ❌Non **autorisé : modification des valeurs retournées pour une propriété, un champ, une valeur de retour de méthode ou un paramètre de sortie **DISALLOWED: Changing the returned values for a property, field, method return value, or out parameter

  • ❌Non autorisé : modification de la valeur par défaut d’une propriété, d’un champ ou d’un paramètreDISALLOWED: Changing the default value of a property, field, or parameter

  • ❌Non autorisé : modification de la précision d’une valeur de retour numériqueDISALLOWED: Changing the precision of a numeric return value

  • Nécessite un jugement : une modification de l’analyse de l’entrée et la levée de nouvelles exceptions (même si le comportement de l’analyse n’est pas spécifié dans la documentation )REQUIRES JUDGMENT: A change in the parsing of input and throwing new exceptions (even if parsing behavior is not specified in the documentation

ExceptionsExceptions

  • ✔️ autorisé : levée d’une exception plus dérivée qu’une exception existante✔️ ALLOWED: Throwing a more derived exception than an existing exception

    Étant donné que la nouvelle exception est une sous-classe d’une exception existante, le code de gestion des exceptions précédent continue à gérer l’exception.Because the new exception is a subclass of an existing exception, previous exception handling code continues to handle the exception. Par exemple, dans .NET Framework 4, les méthodes de création et de récupération de culture ont commencé à lever un CultureNotFoundException au lieu d’un ArgumentException si la culture est introuvable.For example, in .NET Framework 4, culture creation and retrieval methods began to throw a CultureNotFoundException instead of an ArgumentException if the culture could not be found. Étant donné que CultureNotFoundException dérive de ArgumentException, il s’agit d’une modification acceptable.Because CultureNotFoundException derives from ArgumentException, this is an acceptable change.

  • ✔️ **autorisé : la levée d’une exception plus spécifique que NotSupportedException , NotImplementedException , NullReferenceException **✔️ ALLOWED: Throwing a more specific exception than NotSupportedException, NotImplementedException, NullReferenceException

  • ✔️ autorisé : levée d’une exception considérée comme irrécupérable✔️ ALLOWED: Throwing an exception that is considered unrecoverable

    Les exceptions irrécupérables ne doivent pas être interceptées, mais plutôt être gérées par un gestionnaire fourre-tout de haut niveau.Unrecoverable exceptions should not be caught but instead should be handled by a high-level catch-all handler. Par conséquent, les utilisateurs ne sont pas censés avoir du code qui intercepte les exceptions explicites.Therefore, users are not expected to have code that catches these explicit exceptions. Les exceptions irrécupérables sont :The unrecoverable exceptions are:

  • ✔️ autorisé : levée d’une nouvelle exception dans un nouveau chemin d’accès de code✔️ ALLOWED: Throwing a new exception in a new code path

    L’exception doit s’appliquer uniquement à un nouveau chemin d’accès de code qui est exécuté avec les nouvelles valeurs de paramètre ou l’État et qui ne peut pas être exécuté par du code existant qui cible la version précédente.The exception must apply only to a new code-path that's executed with new parameter values or state and that can't be executed by existing code that targets the previous version.

  • ✔️ autorisé : suppression d’une exception pour activer un comportement plus robuste ou de nouveaux scénarios✔️ ALLOWED: Removing an exception to enable more robust behavior or new scenarios

    Par exemple, une méthode Divide qui pouvait auparavant uniquement gérer des valeurs positives et levait un ArgumentOutOfRangeException peut être modifiée pour prendre en charge les valeurs positives et négatives sans lever d’exception.For example, a Divide method that previously only handled positive values and threw an ArgumentOutOfRangeException otherwise can be changed to support both negative and positive values without throwing an exception.

  • ✔️ autorisé : modification du texte d’un message d’erreur✔️ ALLOWED: Changing the text of an error message

    Les développeurs ne doivent pas compter sur le texte des messages d’erreur, qui changent également selon la culture de l’utilisateur.Developers should not rely on the text of error messages, which also change based on the user's culture.

  • Interdit : levée d’une exception dans tout autre cas non listé ci-dessusDISALLOWED: Throwing an exception in any other case not listed above

  • Interdit : suppression d’une exception dans tout autre cas non listé ci-dessusDISALLOWED: Removing an exception in any other case not listed above

AttributsAttributes

  • ✔️ autorisé : modification de la valeur d’un attribut qui n’est pas observable✔️ ALLOWED: Changing the value of an attribute that is not observable

  • ❌**Non autorisé : modification de la valeur d’un attribut observable is **DISALLOWED: Changing the value of an attribute that is observable

  • Nécessite un jugement : suppression d’un attributREQUIRES JUDGMENT: Removing an attribute

    Dans la plupart des cas, la suppression d’un attribut (comme NonSerializedAttribute) est un changement cassant.In most cases, removing an attribute (such as NonSerializedAttribute) is a breaking change.

Plateforme prise en chargePlatform support

  • ✔️ autorisé : prise en charge d’une opération sur une plateforme qui n’était pas prise en charge précédemment✔️ ALLOWED: Supporting an operation on a platform that was previously not supported

  • Non autorisé : ne prend pas en charge ou ne nécessite pas une Service Pack spécifique pour une opération précédemment prise en charge sur une plateformeDISALLOWED: Not supporting or now requiring a specific service pack for an operation that was previously supported on a platform

Modifications de l’implémentation interneInternal implementation changes

  • Nécessite un jugement : modification de la surface d’exposition d’un type interneREQUIRES JUDGMENT: Changing the surface area of an internal type

    Ces modifications sont généralement autorisées, même si elles rompent la réflexion privée.Such changes are generally allowed, although they break private reflection. Dans certains cas, où les bibliothèques tierces les plus courantes ou un grand nombre de développeurs dépendent d’API internes, ces modifications ne peuvent pas être autorisées.In some cases, where popular third-party libraries or a large number of developers depend on the internal APIs, such changes may not be allowed.

  • Nécessite un jugement : modification de l’implémentation interne d’un membreREQUIRES JUDGMENT: Changing the internal implementation of a member

    Ces modifications sont généralement autorisées, même si elles rompent la réflexion privée.These changes are generally allowed, although they break private reflection. Dans certains cas où le code du client dépend souvent de la réflexion privée ou où la modification introduit des effets secondaires involontaires, ces modifications peuvent ne pas être autorisées.In some cases, where customer code frequently depends on private reflection or where the change introduces unintended side effects, these changes may not be allowed.

  • ✔️ autorisées : amélioration des performances d’une opération✔️ ALLOWED: Improving the performance of an operation

    La possibilité de modifier les performances d’une opération est essentielle, mais ces modifications peuvent endommager le code repose sur la vitesse actuelle d’une opération.The ability to modify the performance of an operation is essential, but such changes can break code that relies upon the current speed of an operation. Cela est particulièrement vrai pour du code qui dépend de la chronologie des opérations asynchrones.This is particularly true of code that depends on the timing of asynchronous operations. La modification des performances ne doit avoir aucun effet sur d’autres comportements de l’API en question ; dans le cas contraire, la modification sera arrêtée.The performance change should have no effect on other behavior of the API in question; otherwise, the change will be breaking.

  • ✔️ autorisées : en modifiant indirectement (et souvent défavorablement) les performances d’une opération✔️ ALLOWED: Indirectly (and often adversely) changing the performance of an operation

    Si la modification en question n’est pas considérée comme un changement cassant pour une raison quelconque, cela est acceptable.If the change in question is not categorized as breaking for some other reason, this is acceptable. Souvent, des mesures doivent être prises, ce qui peut inclure des opérations supplémentaires ou l’ajout de nouvelles fonctionnalités.Often, actions need to be taken that may include extra operations or that add new functionality. Cela affectera presque toujours les performances, mais peut s’avérer essentiel pour que l’API en question fonctionne comme prévu.This will almost always affect performance but may be essential to make the API in question function as expected.

  • ❌Non autorisé : modification d’une API synchrone en asynchrone (et inversement)DISALLOWED: Changing a synchronous API to asynchronous (and vice versa)

Modifications du codeCode changes

  • ✔️ autorisé : ajout de paramètres à un paramètre✔️ ALLOWED: Adding params to a parameter

  • ❌Non autorisé : modification d’un struct en classe et vice versaDISALLOWED: Changing a struct to a class and vice versa

  • ❌Non autorisé : ajout du mot clé checked à un bloc de codeDISALLOWED: Adding the checked keyword to a code block

    Cette modification peut pousser le code précédemment exécuté à lever OverflowException, ce qui n’est pas acceptable.This change may cause code that previously executed to throw an OverflowException and is unacceptable.

  • ❌Non autorisé : suppression des paramètres d’un paramètreDISALLOWED: Removing params from a parameter

  • ❌Non autorisé : modification de l’ordre dans lequel les événements sont déclenchésDISALLOWED: Changing the order in which events are fired

    Les développeurs peuvent raisonnablement s’attendre à ce que les événements se déclenchent dans le même ordre, et le code développeur dépend souvent de l’ordre dans lequel les événements sont déclenchés.Developers can reasonably expect events to fire in the same order, and developer code frequently depends on the order in which events are fired.

  • Non autorisé : suppression du déclenchement d’un événement sur une action donnéeDISALLOWED: Removing the raising of an event on a given action

  • ❌Non autorisé : modification du nombre de fois où les événements sont appelésDISALLOWED: Changing the number of times given events are called

  • Non autorisé : ajout FlagsAttribute de à un type énumérationDISALLOWED: Adding the FlagsAttribute to an enumeration type