CA1008 : Les enums doivent avoir la valeur zéro

  • Article
Propriété Value
Identificateur de la règle CA1008
Titre Les enums doivent avoir la valeur zéro
Catégorie Conception
Le correctif est cassant ou non cassant Non cassant : lorsque vous êtes invité à ajouter une valeur None à une énumération sans indicateur. Cassant : lorsque vous êtes invité à renommer ou à supprimer des valeurs d’énumération.
Activé par défaut dans .NET 8 Non

Cause

Une énumération sans un System.FlagsAttribute appliqué ne définit pas un membre dont la valeur est égale à zéro. Ou une énumération qui a un FlagsAttribute appliqué définit un membre dont la valeur est zéro, mais son nom n’est pas « Aucun ». Ou l’énumération définit plusieurs membres à valeur zéro.

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

Description de la règle

La valeur par défaut d'une énumération non initialisée, comme d'autres types valeur, est zéro. Une énumération attribuée sans indicateur doit définir un membre de valeur zéro afin que la valeur par défaut soit une valeur valide de l'énumération. Si c’est le cas, nommez le membre « None » (ou l’un des noms autorisés supplémentaires). Sinon, affectez zéro au membre le plus fréquemment utilisé. Par défaut, si la valeur du premier membre d’énumération n’est pas définie dans la déclaration, sa valeur est égale à zéro.

Si une énumération qui a le FlagsAttribute appliqué définit un membre à valeur nulle, son nom doit être « None » (ou l’un des noms autorisés supplémentaires) pour indiquer qu’aucune valeur n’a été définie dans l’énumération. L’utilisation d’un membre à valeur zéro à tout autre but est contraire à l’utilisation de FlagsAttribute dans le sens où le AND les opérateurs au niveau du bit OR sont inutiles avec le membre. Cela implique qu’un seul membre doit être affecté à la valeur zéro. Si plusieurs membres ayant la valeur zéro se produisent dans une énumération attribuée d’indicateurs, Enum.ToString() retourne des résultats incorrects pour les membres qui ne sont pas zéro.

Comment corriger les violations

Pour remédier à une infraction de cette règle pour les énumérations non attribuées d’indicateurs, définissez un membre ayant la valeur zéro ; il s’agit d’un changement non cassant. Pour les énumérations attribuées par des indicateurs qui définissent un membre à valeur zéro, nommez ce membre « None » et supprimez tous les autres membres dont la valeur est zéro ; c’est un changement cassant.

Quand supprimer les avertissements

Ne supprimez pas d’avertissement de cette règle, à l’exception des énumérations attribuées par des indicateurs précédemment expédiés.

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

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

Noms de champs de valeur nulle supplémentaires

Dans .NET 7 et les versions ultérieures, vous pouvez configurer d’autres noms autorisés pour un champ d’énumération de valeur zéro, en plus de None. Séparez plusieurs noms par le caractère |. Le tableau suivant montre quelques exemples.

Valeur d'option Résumé
dotnet_code_quality.CA1008.additional_enum_none_names = Never Autorise à la fois None et Never
dotnet_code_quality.CA1008.additional_enum_none_names = Never|Nothing Autorise None, Neveret Nothing

Exemple

L’exemple suivant montre deux énumérations qui répondent à la règle et à une énumération, BadTraceOptions, qui enfreint la règle.

using System;

namespace ca1008
{
    public enum TraceLevel
    {
        Off = 0,
        Error = 1,
        Warning = 2,
        Info = 3,
        Verbose = 4
    }

    [Flags]
    public enum TraceOptions
    {
        None = 0,
        CallStack = 0x01,
        LogicalStack = 0x02,
        DateTime = 0x04,
        Timestamp = 0x08,
    }

    [Flags]
    public enum BadTraceOptions
    {
        CallStack = 0,
        LogicalStack = 0x01,
        DateTime = 0x02,
        Timestamp = 0x04,
    }

    class UseBadTraceOptions
    {
        static void MainTrace()
        {
            // Set the flags.
            BadTraceOptions badOptions =
               BadTraceOptions.LogicalStack | BadTraceOptions.Timestamp;

            // Check whether CallStack is set.
            if ((badOptions & BadTraceOptions.CallStack) ==
                BadTraceOptions.CallStack)
            {
                // This 'if' statement is always true.
            }
        }
    }
}

Imports System

Namespace ca1008

    Public Enum TraceLevel
        Off = 0
        AnError = 1
        Warning = 2
        Info = 3
        Verbose = 4
    End Enum

    <Flags>
    Public Enum TraceOptions
        None = 0
        CallStack = &H1
        LogicalStack = &H2
        DateTime = &H4
        Timestamp = &H8
    End Enum

    <Flags>
    Public Enum BadTraceOptions
        CallStack = 0
        LogicalStack = &H1
        DateTime = &H2
        Timestamp = &H4
    End Enum

    Class UseBadTraceOptions

        Shared Sub Main1008()

            ' Set the flags.
            Dim badOptions As BadTraceOptions =
            BadTraceOptions.LogicalStack Or BadTraceOptions.Timestamp

            ' Check whether CallStack is set.
            If ((badOptions And BadTraceOptions.CallStack) =
             BadTraceOptions.CallStack) Then
                ' This 'If' statement is always true.
            End If

        End Sub

    End Class

End Namespace

Voir aussi