CA1717 : Seuls les noms des enums FlagsAttribute doivent être au pluriel

  • Article
Propriété Value
Identificateur de la règle CA1717
Titre Seuls les noms des enums FlagsAttribute doivent être au pluriel
Catégorie Dénomination
Le correctif est cassant ou non cassant Rupture
Activé par défaut dans .NET 8 Non

Cause

Le nom d’une énumération se termine par un mot pluriel et l’énumération n’est pas marquée avec l’attribut System.FlagsAttribute.

Par défaut, cette règle examine uniquement les énumérations visibles en externe, mais elle est configurable.

Description de la règle

Selon les conventions d’attribution de nom, un nom au pluriel pour une énumération indique que plusieurs valeurs de l’énumération peuvent être spécifiées simultanément. Le FlagsAttribute indique au compilateur que l’énumération doit être traitée comme un champ de bits qui active les opérations au niveau du bit sur l’énumération.

Si une seule valeur d’une énumération peut être spécifiée à la fois, le nom de l’énumération doit être un mot singulier. Par exemple, une énumération qui définit les jours de la semaine peut être destinée à être utilisée dans une application où vous pouvez spécifier plusieurs jours. Cette énumération doit avoir le FlagsAttribute et être appelée « Days ». Une énumération similaire qui autorise la spécification d’un seul jour n’aurait pas l’attribut et pourrait être appelée « Day ».

Les conventions de nommage fournissent une recherche commune pour les bibliothèques qui ciblent le common language runtime. Cela réduit le temps nécessaire à l’apprentissage d’une nouvelle bibliothèque de logiciels et augmente la confiance des clients que la bibliothèque a été développée par une personne qui a une expertise dans le développement de code managé.

Comment corriger les violations

Donnez le nom de l’énumération à un mot singulier ou ajoutez le FlagsAttribute.

Quand supprimer les avertissements

Il est sûr de supprimer un avertissement de la règle si le nom se termine par un mot singulier.

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 CA1717
// The code that's violating the rule is on this line.
#pragma warning restore CA1717

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.CA1717.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

Voir aussi