CA1027 : Marquer les enums avec FlagsAttribute

  • Article
Propriété Value
Identificateur de la règle CA1027
Titre Marquer les enums avec FlagsAttribute
Catégorie Conception
Le correctif est cassant ou non cassant Sans rupture
Activé par défaut dans .NET 8 Non

Cause

Les valeurs d’une énumération sont des puissances de deux ou sont des combinaisons d’autres valeurs définies dans l’énumération, et l’attribut System.FlagsAttribute n’est pas présent. Pour réduire les faux positifs, cette règle ne signale pas de violation pour les énumérations qui ont des valeurs contiguës.

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

Description de la règle

Une énumération est un type valeur qui définit un jeu de constantes nommées associées. Appliquez FlagsAttribute à une énumération lorsque ses constantes nommées peuvent être combinées de manière pertinente. Par exemple, supposez une énumération des jours de la semaine dans une application qui effectue le suivi des ressources du jour qui sont disponibles. Si la disponibilité de chaque ressource est encodée à l’aide de l’énumération qui présente FlagsAttribute, n’importe quelle combinaison de jours peut être représentée. Sans l’attribut, un seul jour de la semaine peut être représenté.

Pour les champs qui stockent des énumérations combinables, les valeurs d’énumération individuelles sont traitées comme des groupes de bits dans le champ. Par conséquent, ces champs sont parfois appelés champs de bits. Pour combiner des valeurs d’énumération pour le stockage dans un champ de bits, utilisez les opérateurs conditionnels booléens. Pour tester un champ de bits pour déterminer si une valeur d’énumération spécifique est présente, utilisez les opérateurs logiques booléens. Pour qu’un champ de bits stocke et récupère correctement les valeurs d’énumération combinées, chaque valeur définie dans l’énumération doit être une puissance de deux. Dans le cas contraire, les opérateurs logiques booléens ne pourront pas extraire les valeurs d’énumération individuelles stockées dans le champ.

Comment corriger les violations

Pour corriger une violation de cette règle, ajoutez FlagsAttribute à l’énumération.

Quand supprimer les avertissements

Supprimez un avertissement de cette règle si vous ne souhaitez pas que les valeurs d’énumération soient combinables.

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

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.CA1027.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 (Conception) 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

Exemple

Dans l’exemple suivant, DaysEnumNeedsFlags est une énumération qui répond aux exigences d’utilisation de FlagsAttribute, mais qui ne l’a pas. L’énumération ColorEnumShouldNotHaveFlag n’a pas de valeurs qui sont des puissances de deux, mais spécifie incorrectement FlagsAttribute. Cela enfreint la règle CA2217 : Ne marquez pas les énumérations avec FlagsAttribute.

// Violates rule: MarkEnumsWithFlags.
public enum DaysEnumNeedsFlags
{
    None = 0,
    Monday = 1,
    Tuesday = 2,
    Wednesday = 4,
    Thursday = 8,
    Friday = 16,
    All = Monday | Tuesday | Wednesday | Thursday | Friday
}

// Violates rule: DoNotMarkEnumsWithFlags.
[FlagsAttribute]
public enum ColorEnumShouldNotHaveFlag
{
    None = 0,
    Red = 1,
    Orange = 3,
    Yellow = 4
}

Voir aussi