CA1700 : Ne nommez pas les valeurs enum 'Reserved'

  • Article
Propriété Value
Identificateur de la règle CA1700
Titre Ne nommez pas les valeurs enum 'Reserved'
Catégorie Dénomination
Le correctif est cassant ou non cassant Rupture
Activé par défaut dans .NET 8 Non

Cause

Le nom d’un membre d’énumération contient le mot « réservé ».

Description de la règle

Cette règle suppose qu'un membre de l'énumération dont le nom contient le terme "reserved" n'est pas utilisé actuellement, mais constitue un espace réservé à renommer ou à supprimer dans une version ultérieure. Renommer ou supprimer un membre constitue une modification avec rupture. Vous ne devez pas vous attendre à ce que les utilisateurs ignorent un membre simplement parce que son nom contient « réservé », et vous ne pouvez pas non plus compter sur les utilisateurs pour lire ou respecter la documentation. En outre, comme les membres réservés apparaissent dans les navigateurs d’objets et les environnements de développement intégré intelligent, ils peuvent entraîner une confusion quant aux membres qui sont réellement utilisés.

Au lieu d’utiliser un membre réservé, ajoutez un nouveau membre à l’énumération dans la version ultérieure. Dans la plupart des cas, l’ajout du nouveau membre n’est pas un changement cassant, tant que l’ajout n’entraîne pas le changement des valeurs des membres d’origine.

Dans un nombre limité de cas, l’ajout d’un membre est un changement cassant même lorsque les membres d’origine conservent leurs valeurs d’origine. Principalement, le nouveau membre ne peut pas être retourné à partir de chemins de code existants sans les appelants cassants qui utilisent une instruction switch (Select en Visual Basic) sur la valeur de retour qui englobe l’ensemble de la liste des membres et qui lèvent une exception dans le cas par défaut. Une préoccupation secondaire est que le code client peut ne pas gérer le changement de comportement des méthodes de réflexion telles que System.Enum.IsDefined. Par conséquent, si le nouveau membre doit être retourné à partir de méthodes existantes ou si une incompatibilité d’application connue se produit en raison d’une mauvaise utilisation de la réflexion, la seule solution non cassante consiste à :

  1. Ajouter une nouvelle énumération qui contient les membres d’origine et les nouveaux membres.

  2. Marquer l’énumération d’origine avec l’attribut System.ObsoleteAttribute.

    Suivre la même procédure pour tous les types ou membres visibles en externe qui exposent l’énumération d’origine.

Comment corriger les violations

Pour corriger une violation de cette règle, supprimez ou renommez le membre.

Quand supprimer les avertissements

Il est prudent de supprimer un avertissement de cette règle pour un membre actuellement utilisé ou pour les bibliothèques qui ont déjà été livrées.

Supprimer un avertissement

Si vous voulez supprimer une seule violation, ajoutez des directives de préprocesseur à votre fichier source pour désactiver et réactiver la règle.

#pragma warning disable CA1700
// The code that's violating the rule is on this line.
#pragma warning restore CA1700

Pour désactiver la règle sur un fichier, un dossier ou un projet, définissez sa gravité sur none dans le fichier de configuration.

[*.{cs,vb}]
dotnet_diagnostic.CA1700.severity = none

Pour plus d’informations, consultez Comment supprimer les avertissements de l’analyse de code.

Configurer le code à analyser

Utilisez l’option suivante pour configurer les parties de votre codebase sur lesquelles exécuter cette règle.

Vous pouvez configurer cette option pour cette règle uniquement, pour toutes les règles auxquelles elle s’applique ou pour toutes les règles de cette catégorie (Nommage) auxquelles elle s’applique. Pour plus d’informations, consultez Options de configuration des règles de qualité du code.

Inclure des surfaces d’API spécifiques

Vous pouvez configurer les parties de votre codebase sur lesquelles exécuter cette règle, en fonction de leur accessibilité. Par exemple, pour spécifier que la règle doit s’exécuter uniquement sur la surface d’API non publique, ajoutez la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CAXXXX.api_surface = private, internal

CA2217 : Ne marquez pas les enums avec l'attribut FlagsAttribute

CA1712 : N'ajoutez pas le nom de type en guise de préfixe à des valeurs enum

CA1028 : Enum Storage doit être Int32

CA1008 : Les enums doivent avoir la valeur zéro

CA1027 : Marquer les enums avec FlagsAttribute