Udostępnij za pośrednictwem

CA1008: Wyliczenia powinny mieć wartość zero

  • Artykuł
Właściwości Wartość
Identyfikator reguły CA1008
Tytuł Typy wyliczeniowe powinny mieć wartość zero
Kategoria Projekt
Poprawka powodująca niezgodność lub niezgodność Niezgodność — po wyświetleniu monitu None o dodanie wartości do wyliczenia innego niż flaga. Niezgodność — po wyświetleniu monitu o zmianę nazwy lub usunięcie wszystkich wartości wyliczenia.
Domyślnie włączone na platformie .NET 8 Nie.

Przyczyna

Wyliczenie bez zastosowanego System.FlagsAttribute nie definiuje elementu członkowskiego, który ma wartość zero. Lub wyliczenie, które ma zastosowane FlagsAttribute definiuje element członkowski, który ma wartość zero, ale jego nazwa nie jest "Brak". Ewentualnie wyliczenie definiuje wiele zera wartości składowych.

Domyślnie ta reguła analizuje tylko widoczne zewnętrznie wyliczenia, ale można to skonfigurować.

Opis reguły

Wartość domyślna niezainicjowanego wyliczenia, podobnie jak inne typy wartości, wynosi zero. Wyliczenie bez flagi powinno zdefiniować element członkowski, który ma wartość zero, tak aby wartość domyślna to prawidłowa wartość wyliczenia. W razie potrzeby nadaj członkowi nazwę "None" (lub jedną z dodatkowych dozwolonych nazw). W przeciwnym razie przypisz zero do najczęściej używanego elementu członkowskiego. Domyślnie, jeśli wartość pierwszego elementu członkowskiego wyliczenia nie jest ustawiona w deklaracji, jego wartość to zero.

Jeśli wyliczenie, które ma FlagsAttribute zastosowane definiuje element członkowski o wartości zerowej, jego nazwa powinna mieć wartość "None" (lub jedną z dodatkowych dozwolonych nazw), aby wskazać, że żadne wartości nie zostały ustawione w wyliczeniu. Używanie elementu członkowskiego o wartości zerowej do dowolnego innego celu jest sprzeczne z użyciem FlagsAttribute elementu w tym, że AND operatory i OR bitowe są bezużyteczne z elementem członkowskim. Oznacza to, że tylko jeden element członkowski powinien mieć przypisaną wartość zero. Jeśli wiele elementów członkowskich, które mają wartość zero, wystąpi w wyliczenie przypisane przez flagi, Enum.ToString() zwraca nieprawidłowe wyniki dla elementów członkowskich, które nie są zero.

Jak naprawić naruszenia

Aby naprawić naruszenie tej reguły w przypadku wyliczeń przypisanych bez flag, zdefiniuj element członkowski, który ma wartość zero; jest to zmiana niezgodna. W przypadku wyliczenia atrybutów flag definiujących element członkowski o zerowej wartości nazwij ten element członkowski "Brak" i usuń wszystkie inne elementy członkowskie, które mają wartość zero; jest to zmiana powodująca niezgodność.

Kiedy pomijać ostrzeżenia

Nie pomijaj ostrzeżenia z tej reguły z wyjątkiem wyliczeń przypisanych flag, które zostały wcześniej wysłane.

Pomijanie ostrzeżenia

Jeśli chcesz po prostu pominąć pojedyncze naruszenie, dodaj dyrektywy preprocesora do pliku źródłowego, aby wyłączyć, a następnie ponownie włączyć regułę.

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

Aby wyłączyć regułę dla pliku, folderu lub projektu, ustaw jego ważność na none w pliku konfiguracji.

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

Aby uzyskać więcej informacji, zobacz Jak pominąć ostrzeżenia dotyczące analizy kodu.

Konfigurowanie kodu do analizowania

Użyj następującej opcji, aby skonfigurować, które części bazy kodu mają być uruchamiane w tej regule.

Tę opcję można skonfigurować tylko dla tej reguły, dla wszystkich reguł, do których ma ona zastosowanie, lub dla wszystkich reguł w tej kategorii (Projekt), których dotyczy. Aby uzyskać więcej informacji, zobacz Opcje konfiguracji reguły jakości kodu.

Uwzględnij określone powierzchnie interfejsu API

Możesz skonfigurować, na których częściach bazy kodu ma być uruchamiana ta reguła, na podstawie ich ułatwień dostępu. Aby na przykład określić, że reguła powinna być uruchamiana tylko na powierzchni niepublicznego interfejsu API, dodaj następującą parę klucz-wartość do pliku editorconfig w projekcie:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Dodatkowe nazwy pól o wartości zerowej

W programie .NET 7 i nowszych wersjach można skonfigurować inne dozwolone nazwy dla pola wyliczania zerowej wartości oprócz None. Oddziel wiele nazw znakami | . W poniższej tabeli przedstawiono kilka przykładów.

Wartość opcji Podsumowanie
dotnet_code_quality.CA1008.additional_enum_none_names = Never Zezwala zarówno na, jak None i Never
dotnet_code_quality.CA1008.additional_enum_none_names = Never|Nothing Zezwala na Nonepolecenia , Neveri Nothing

Przykład

W poniższym przykładzie przedstawiono dwa wyliczenia spełniające regułę i wyliczenie , BadTraceOptionsktóre naruszają regułę.

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

Zobacz też