CA1008: Enumerationen müssen einen Wert von 0 (null) aufweisen.

  • Artikel
Eigenschaft Wert
Regel-ID CA1008
Titel Enumerationen müssen einen Wert von 0 (null) aufweisen.
Kategorie Design
Fix führt oder führt nicht zur Unterbrechung Nicht unterbrechend: Wenn Sie aufgefordert werden, einen None Wert hinzuzufügen zur nicht gekennzeichneten Enumeration. Unterbrechen: Wenn Sie aufgefordert werden, Enumerationswerte umzubenennen oder zu entfernen.
Standardmäßig in .NET 8 aktiviert Nein

Ursache

Eine Enumeration ohne angewendete System.FlagsAttribute definiert keinen Member, der den Nullwert aufweist. Oder eine Enumeration, die über einen angewendeten verfügt, FlagsAttribute definiert einen Member, der den Nullwert aufweist, dessen Name jedoch nicht "None" ist. Oder die Enumeration definiert mehrere Member mit Nullwerten.

Standardmäßig werden mit dieser Regel nur extern sichtbare Enumerationen überprüft, aber dies ist konfigurierbar.

Regelbeschreibung

Der Standardwert einer nicht initialisierten Enumeration ist ebenso, wie der anderen Werttypen, Null. Eine Enumeration ohne das Flags-Attribut sollte einen Member mit dem Nullwert definieren, damit der Standardwert ein gültiger Wert der Enumeration ist. Geben Sie dem Member ggf. den Namen „None“ (oder einen der zusätzlichen zulässigen Namen). Andernfalls sollten Sie dem am häufigsten verwendeten Member Null zuweisen. Wenn der Wert des ersten Enumerationsmembers nicht in der Deklaration festgelegt ist, ist der Wert standardmäßig auf 0 festgelegt.

Wenn eine Enumeration, auf die FlagsAttribute angewandt wurde, einen nullwertiges Member definiert, sollte dessen Name „None“ lauten (oder einer der zusätzlichen zulässigen Namen), um anzuzeigen, dass keine Werte in der Aufzählung festgelegt wurden. Die Verwendung eines Elements mit einem nullwertigen Member für andere Zwecke steht im Gegensatz zur Verwendung von FlagsAttribute in, da die bitweisen Operatoren AND und OR mit dem Member nutzlos sind. Dies impliziert, dass nur einem Member dem Nullwert zugewiesen werden soll. Wenn mehrere Member mit dem Nullwert in einer durch Flags attribuierten Enumeration auftreten, Enum.ToString() gibt falsche Ergebnisse für Member zurück, die nicht 0 sind.

Behandeln von Verstößen

Um einen Verstoß gegen diese Regel für Enumerationen mit nicht-Flags-Attributen zu beheben, definieren Sie einen Member, der den Nullwert aufweist. Dabei handelt es sich um einen Nonbreaking Change. Für Flags-attributierte Enumerationen, die einen Null-wertigen Member definieren, benennen Sie den Member "None" und löschen Sie alle anderen Member, die den nullwert aufweisen. Dies ist eine Breaking Change.

Wann sollten Warnungen unterdrückt werden?

Unterdrücken Sie keine Warnung dieser Regel, außer bei von Flags attributierten Enumerationen, die zuvor versandt wurden.

Unterdrücken einer Warnung

Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.

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

Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad in der Konfigurationsdatei auf none fest.

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

Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.

Konfigurieren des zu analysierenden Codes

Mithilfe der folgenden Option können Sie konfigurieren, für welche Teile Ihrer Codebasis diese Regel ausgeführt werden soll.

Sie können diese Optionen nur für diese Regel, für alle zutreffenden Regeln oder für alle zutreffenden Regeln in dieser Kategorie (Entwurf) konfigurieren. Weitere Informationen finden Sie unter Konfigurationsoptionen für die Codequalitätsregel.

Einschließen bestimmter API-Oberflächen

Sie können je nach Zugänglichkeit festlegen, für welche Bestandteile Ihrer Codebasis diese Regel ausgeführt wird. Sie können beispielsweise festlegen, dass die Regel nur für die nicht öffentliche API-Oberfläche ausgeführt werden soll, indem Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzufügen:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Zusätzliche Nullwertfeldnamen

In .NET 7 und höheren Versionen können Sie neben None noch andere zulässige Namen für ein Nullwert-Enumerationsfeld konfigurieren. Trennen Sie mehrere Namen durch das Zeichen | voneinander. Die folgende Tabelle enthält einige Beispiele.

Optionswert Zusammenfassung
dotnet_code_quality.CA1008.additional_enum_none_names = Never Erlaubt sowohl None als auch Never
dotnet_code_quality.CA1008.additional_enum_none_names = Never|Nothing Erlaubt None, Never und Nothing

Beispiel

Das folgende Beispiel zeigt zwei Enumerationen, die die Regel erfüllen, und eine Enumeration, die gegen BadTraceOptions die Regel verstößt.

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

Siehe auch