Delen via

CA1008: Enums moet een nulwaarde hebben

  • Artikel
Eigenschappen Weergegeven als
Regel-id CA1008
Titel Enums moeten nulwaarde hebben
Categorie Ontwerpen
Oplossing is brekend of niet-brekend Niet-verbrekend: wanneer u wordt gevraagd een None waarde toe te voegen aan een opsomming zonder vlag. Fouten veroorzaken: wanneer u wordt gevraagd om de naam van opsommingswaarden te wijzigen of te verwijderen.
Standaard ingeschakeld in .NET 8 Nee

Oorzaak

Een opsomming zonder een toegepaste System.FlagsAttribute opsomming definieert geen lid met een waarde van nul. Of een opsomming die een toegepaste FlagsAttribute waarde heeft, definieert een lid met een waarde van nul, maar de naam is niet 'Geen'. Of de opsomming definieert meerdere leden met een nulwaarde.

Deze regel kijkt standaard alleen naar extern zichtbare opsommingen, maar dit is configureerbaar.

Beschrijving van regel

De standaardwaarde van een niet-geïnitialiseerde opsomming, net als andere waardetypen, is nul. Een opsomming zonder vlaggen moet een lid definiëren dat de waarde nul heeft, zodat de standaardwaarde een geldige waarde van de opsomming is. Geef indien van toepassing de naam 'Geen' (of een van de extra toegestane namen). Wijs anders nul toe aan het meest gebruikte lid. Als de waarde van het eerste opsommingslid niet is ingesteld in de declaratie, is de waarde standaard nul.

Als een opsomming met de FlagsAttribute toegepaste waarde een lid met nulwaarden definieert, moet de naam 'Geen' (of een van de extra toegestane namen) zijn om aan te geven dat er geen waarden zijn ingesteld in de opsomming. Het gebruik van een nulwaardelid voor elk ander doel is in strijd met het gebruik van de FlagsAttribute operatoren AND en OR bitsgewijze operatoren zijn nutteloos met het lid. Dit impliceert dat slechts één lid de waarde nul moet krijgen. Als meerdere leden met de waarde nul voorkomen in een opsomming die is toegewezen aan vlaggen, Enum.ToString() worden onjuiste resultaten geretourneerd voor leden die niet nul zijn.

Schendingen oplossen

Als u een schending van deze regel wilt oplossen voor niet-vlaggen toegeschreven opsommingen, definieert u een lid met de waarde nul; dit is een niet-belangrijke wijziging. Voor markeringen die een lid met nulwaarde definiëren, noemt u dit lid geen en verwijdert u alle andere leden met een waarde nul; dit is een belangrijke wijziging.

Wanneer waarschuwingen onderdrukken

Onderdrukt geen waarschuwing van deze regel, met uitzondering van opsommingen die zijn toegewezen aan vlaggen die eerder zijn verzonden.

Een waarschuwing onderdrukken

Als u slechts één schending wilt onderdrukken, voegt u preprocessorrichtlijnen toe aan uw bronbestand om de regel uit te schakelen en vervolgens opnieuw in te schakelen.

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

Als u de regel voor een bestand, map of project wilt uitschakelen, stelt u de ernst none ervan in op het configuratiebestand.

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

Zie Codeanalysewaarschuwingen onderdrukken voor meer informatie.

Code configureren om te analyseren

Gebruik de volgende optie om te configureren op welke onderdelen van uw codebase deze regel moet worden uitgevoerd.

U kunt deze optie configureren voor alleen deze regel, voor alle regels waarop deze van toepassing is, of voor alle regels in deze categorie (ontwerp) waarop deze van toepassing is. Zie de configuratieopties voor de codekwaliteitsregel voor meer informatie.

Specifieke API-oppervlakken opnemen

U kunt instellen op welke onderdelen van uw codebase deze regel moet worden uitgevoerd, op basis van hun toegankelijkheid. Als u bijvoorbeeld wilt opgeven dat de regel alleen moet worden uitgevoerd op het niet-openbare API-oppervlak, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Aanvullende veldnamen met nulwaarden

In .NET 7 en latere versies kunt u andere toegestane namen configureren voor een opsommingsveld met nulwaarden, naast None. Scheid meerdere namen door het | teken. In de volgende tabel ziet u enkele voorbeelden.

Optiewaarde Samenvatting
dotnet_code_quality.CA1008.additional_enum_none_names = Never Hiermee staat u zowel als NoneNever
dotnet_code_quality.CA1008.additional_enum_none_names = Never|Nothing Hiermee staat u Nonetoe, Neveren Nothing

Opmerking

In het volgende voorbeeld ziet u twee opsommingen die voldoen aan de regel en een opsomming, BadTraceOptionsdie de regel schendt.

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

Zie ook