Freigeben über

CA1008: Enums sollten einen Wert von 0 (null) aufweisen.

Eigenschaft Wert
Regel-ID CA1008
Titel Enums sollten den Wert 0 haben.
Kategorie Design
Fix führt zu Unterbrechungen oder bleibt funktionsfähig Nicht unterbrechend: Wenn Sie aufgefordert werden, einen None Wert hinzuzufügen zur nicht gekennzeichneten Enumeration. Unterbrechung: Wenn Sie aufgefordert werden, Aufzählungswerte umzubenennen oder zu entfernen.
Standardmäßig in .NET 10 aktiviert Nein
Anwendbare Sprachen C# und Visual Basic

Ursache

Eine Enumeration ohne angewendete System.FlagsAttribute definiert kein Element, das den Wert Null hat. Oder eine Enumeration, auf die FlagsAttribute angewendet wurde, definiert ein Element, das den Wert Null hat, dessen Name jedoch nicht "None" ist. Oder die Enumeration definiert mehrere Member, die Nullwerte haben.

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 Members mit dem Wert null für andere Zwecke widerspricht der erwarteten Verwendung von FlagsAttribute, da die bitweisen Operatoren AND und OR mit dem Member nutzlos sind. Dies impliziert, dass nur einem Mitglied der Wert Null 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.

So beheben Sie Verstöße

Um einen Verstoß gegen diese Regel für Enumerationen ohne Flags-Attribut zu beheben, definieren Sie ein Mitglied, das den Wert Null aufweist. Dabei handelt es sich um eine nicht-unterbrechende Änderung. Für flags-attributierte Enumerationen, die ein nullwertiges Element definieren, benennen Sie das Element "None" und löschen Sie alle anderen Elemente, 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 auf none in der Konfigurationsdatei 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 konfigurieren, für alle Regeln, auf die sie angewendet werden, oder für alle Regeln auf die sie in dieser Kategorie (Entwurf) angewendet werden. Weitere Informationen finden Sie unter Konfigurationsoptionen für die Codequalitätsregel.

Einschließen bestimmter API-Oberflächen

Sie können konfigurieren, auf welchen Teilen Ihrer Codebasis je nach Barrierefreiheit diese Regel ausgeführt werden soll, indem Sie die Option api_surface festlegen. 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

Hinweis

Ersetzen Sie den XXXX-Teil von CAXXXX durch die ID der anwendbaren Regel.

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

  • Last updated on