CA1008: Výčty by měly mít nulovou hodnotu

  • Článek
Vlastnost Hodnota
ID pravidla CA1008
Název Výčty by měly mít nulovou hodnotu
Kategorie Návrh
Oprava způsobující chybu nebo chybu způsobující chybu Non-breaking – Když se zobrazí výzva k přidání None hodnoty do výčtu bez příznaku. Přerušení – Když se zobrazí výzva k přejmenování nebo odebrání všech hodnot výčtu
Povoleno ve výchozím nastavení v .NET 8 No

Příčina

Výčet bez použití System.FlagsAttribute nedefinuje člen, který má hodnotu nula. Nebo výčet, který má použitou FlagsAttribute definici členu, který má hodnotu nula, ale jeho název není None. Nebo výčet definuje více členů s nulovou hodnotou.

Ve výchozím nastavení toto pravidlo sleduje jenom externě viditelné výčty, ale dá se konfigurovat.

Popis pravidla

Výchozí hodnota neinicializovaného výčtu, stejně jako jiné typy hodnot, je nula. Výčet bez příznaků by měl definovat člen, který má hodnotu nula, aby výchozí hodnota byla platná hodnota výčtu. V případě potřeby pojmenujte člena None (nebo jeden z dalších povolených názvů). V opačném případě přiřaďte nulu nejčastěji používanému členu. Ve výchozím nastavení platí, že pokud hodnota prvního členu výčtu není nastavena v deklaraci, její hodnota je nula.

Pokud výčet, který má použitou FlagsAttribute definici členu s nulovou hodnotou, jeho název by měl být None (nebo jeden z dalších povolených názvů), který označuje, že v výčtu nebyly nastaveny žádné hodnoty. Použití členu s nulovou hodnotou pro jakýkoli jiný účel je v rozporu s použitím operátoru FlagsAttribute , který AND a OR bitové operátory jsou u člena nepoužité. To znamená, že hodnotu nula by měla být přiřazena pouze jednomu členu. Pokud v výčtu s atributem flags-attributed dojde více členů s nulovou hodnotou, vrátí nesprávné výsledky pro členy, Enum.ToString() které nejsou nula.

Jak opravit porušení

Chcete-li opravit porušení tohoto pravidla pro výčty bez příznaků, definujte člena, který má hodnotu nula; jedná se o nerušnou změnu. Pro výčty atributů flags, které definují člen s nulovou hodnotou, pojmenujte tento člen 'None' a odstraňte všechny ostatní členy, které mají hodnotu nula; to je zásadní změna.

Kdy potlačit upozornění

Nepotlačujte upozornění z tohoto pravidla s výjimkou výčtů přiřazených příznakem, které byly dříve odeslány.

Potlačení upozornění

Pokud chcete pouze potlačit jedno porušení, přidejte do zdrojového souboru direktivy preprocesoru, abyste pravidlo zakázali a znovu povolili.

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

Pokud chcete pravidlo pro soubor, složku nebo projekt zakázat, nastavte jeho závažnost v none konfiguračním souboru.

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

Další informace naleznete v tématu Jak potlačit upozornění analýzy kódu.

Konfigurace kódu pro analýzu

Pomocí následující možnosti nakonfigurujte, ve kterých částech základu kódu se má toto pravidlo spouštět.

Tuto možnost můžete nakonfigurovat jenom pro toto pravidlo, pro všechna pravidla, která platí, nebo pro všechna pravidla v této kategorii (Návrh), na která platí. Další informace naleznete v tématu Možnosti konfigurace pravidla kvality kódu.

Zahrnutí konkrétních povrchů rozhraní API

Na základě přístupnosti můžete nakonfigurovat, na kterých částech základu kódu se má toto pravidlo spouštět. Pokud chcete například určit, že pravidlo by se mělo spouštět jenom na neveřejné ploše rozhraní API, přidejte do souboru .editorconfig v projektu následující pár klíč-hodnota:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Další názvy polí nulové hodnoty

V .NET 7 a novějších verzích můžete kromě toho nakonfigurovat další povolené názvy pro pole Nonevýčtu nulové hodnoty. Oddělte několik názvů znakem | . Následující tabulka uvádí několik příkladů.

Hodnota možnosti Shrnutí
dotnet_code_quality.CA1008.additional_enum_none_names = Never Umožňuje obojí None i Never
dotnet_code_quality.CA1008.additional_enum_none_names = Never|Nothing Umožňuje None, Nevera Nothing

Příklad

Následující příklad ukazuje dva výčty, které vyhovují pravidlu a výčtu, BadTraceOptionskteré porušují pravidlo.

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

Viz také