Dela via

CA1008: Uppräkningar bör ha noll värde

  • Artikel
Property Värde
Regel-ID CA1008
Title Uppräkningar bör ha noll värde
Kategori Designa
Korrigeringen är icke-bakåtkompatibel Icke-icke-icke-bakåtkompatibel – När du uppmanas att lägga till ett None värde i en uppräkning som inte är flaggad. Icke-bakåtkompatibel – När du uppmanas att byta namn på eller ta bort uppräkningsvärden.
Aktiverad som standard i .NET 9 Nej

Orsak

En uppräkning utan en tillämpad System.FlagsAttribute definierar inte en medlem som har värdet noll. Eller en uppräkning som har en tillämpad FlagsAttribute definierar en medlem som har värdet noll men namnet är inte "Ingen". Eller så definierar uppräkningen flera, nollvärdesmedlemmar.

Som standard tittar den här regeln bara på externt synliga uppräkningar, men det kan konfigureras.

Regelbeskrivning

Standardvärdet för en ennitialiserad uppräkning, precis som andra värdetyper, är noll. En icke-flaggad uppräkning bör definiera en medlem som har värdet noll så att standardvärdet är ett giltigt värde för uppräkningen. Om det är lämpligt namnger du medlemmen "Ingen" (eller något av de ytterligare tillåtna namnen). Annars tilldelar du noll till den mest använda medlemmen. Om värdet för den första uppräkningsmedlemmen inte anges i deklarationen är värdet noll som standard.

Om en uppräkning som har tillämpats FlagsAttribute definierar en nollvärdesmedlem, bör dess namn vara "Ingen" (eller ett av de ytterligare tillåtna namnen) för att indikera att inga värden har angetts i uppräkningen. Att använda en nollvärdesmedlem för något annat syfte strider mot användningen av FlagsAttribute i så fall att AND operatorerna och OR bitvis är värdelösa med medlemmen. Detta innebär att endast en medlem ska tilldelas värdet noll. Om flera medlemmar som har värdet noll inträffar i en flaggtilldelad uppräkning returnerar Enum.ToString() felaktiga resultat för medlemmar som inte är noll.

Så här åtgärdar du överträdelser

Om du vill åtgärda ett brott mot den här regeln för icke-flaggor-tillskrivna uppräkningar definierar du en medlem som har värdet noll. Detta är en icke-icke-icke-bakåtkompatibel ändring. För flaggor-tillskrivna uppräkningar som definierar en nollvärdesmedlem namnger du den här medlemmen "Ingen" och tar bort andra medlemmar som har värdet noll. Detta är en icke-bakåtkompatibel förändring.

När du ska ignorera varningar

Utelämna inte en varning från den här regeln förutom flaggor-tillskrivna uppräkningar som tidigare har levererats.

Ignorera en varning

Om du bara vill förhindra en enda överträdelse lägger du till förprocessordirektiv i källfilen för att inaktivera och aktiverar sedan regeln igen.

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

Om du vill inaktivera regeln för en fil, mapp eller ett projekt anger du dess allvarlighetsgrad till none i konfigurationsfilen.

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

Mer information finns i Så här utelämnar du kodanalysvarningar.

Konfigurera kod för analys

Använd följande alternativ för att konfigurera vilka delar av kodbasen som regeln ska köras på.

Du kan konfigurera det här alternativet för bara den här regeln, för alla regler som gäller för eller för alla regler i den här kategorin (design) som den gäller för. Mer information finns i Konfigurationsalternativ för kodkvalitetsregel.

Inkludera specifika API-ytor

Du kan konfigurera vilka delar av kodbasen som ska köras med den här regeln baserat på deras tillgänglighet. Om du till exempel vill ange att regeln endast ska köras mot den icke-offentliga API-ytan lägger du till följande nyckel/värde-par i en .editorconfig-fil i projektet:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Ytterligare fältnamn med nollvärde

I .NET 7 och senare versioner kan du konfigurera andra tillåtna namn för ett nollvärdesuppräkningsfält None, förutom . Avgränsa flera namn med | tecknet. I följande tabell visas några exempel.

Alternativvärde Sammanfattning
dotnet_code_quality.CA1008.additional_enum_none_names = Never Tillåter både None och Never
dotnet_code_quality.CA1008.additional_enum_none_names = Never|Nothing Tillåter None, Neveroch Nothing

Exempel

I följande exempel visas två uppräkningar som uppfyller regeln och en uppräkning, BadTraceOptions, som bryter mot regeln.

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

Se även