CA1008: Enums moet een nulwaarde hebben

Eigenschap Waarde
Regel-id CA1008
Titel Enums moeten nulwaarde hebben
Categorie Ontwerpen
Fix kan brekend of niet-brekend zijn Niet-verbrekend: wanneer u wordt gevraagd een None waarde toe te voegen aan een opsomming zonder vlag. Breekpunt: wanneer u wordt gevraagd om opsommingswaarden te hernoemen of te verwijderen.
Standaard ingeschakeld in .NET 10 Nee
Toepasselijke talen C# en Visual Basic

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 de naam 'Geen', indien van toepassing (of een van de aanvullende 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 andere doelen is in strijd met hoe de FlagsAttribute wordt gebruikt, omdat de bitsgewijze operatoren AND en OR nutteloos zijn 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.

Hoe schendingen op te lossen

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 vlaggen-toegekende enumeraties die een lid met de waarde nul definiëren, noem dit lid 'None' en verwijder alle andere leden met de waarde nul; dit is een brekende 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 voor meer informatie Hoe codeanalysewaarschuwingen te onderdrukken.

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 opties configureren voor alleen deze regel, voor alle regels waarop ze van toepassing zijn, of voor alle regels in deze categorie (Ontwerp) waarop ze van toepassing zijn. Zie de configuratieopties voor de codekwaliteitsregel voor meer informatie.

Specifieke API-oppervlakken opnemen

U kunt configureren op welke onderdelen van uw codebase deze regel moet worden uitgevoerd, op basis van hun toegankelijkheid, door de optie api_surface in te stellen. 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

Notitie

Vervang het XXXX deel van CAXXXX door de id van de toepasselijke regel.

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 zijn zowel None als Never toegestaan.
dotnet_code_quality.CA1008.additional_enum_none_names = Never|Nothing Hiermee staat u None, Never en Nothing toe

Voorbeeld

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

  • Last updated on