Udostępnij za pośrednictwem

CA1008: Wyliczenia powinny mieć wartość zero

Właściwości Wartość
Identyfikator reguły CA1008
Tytuł Typy wyliczeniowe powinny mieć wartość zero
Kategoria Projektowanie
Poprawka łamiąca lub nienaruszająca Nieprzerwane - Gdy pojawi się monit o dodanie wartości None do wyliczenia, które nie jest flagą. Gdy zostaniesz poproszony o zmianę nazwy lub usunięcie jakichkolwiek wartości wyliczenia.
Domyślnie włączone na platformie .NET 10 Nie.
Zastosowane języki C# i Visual Basic

Przyczyna

Wyliczenie bez zastosowanego System.FlagsAttribute nie definiuje elementu, którego wartość wynosi zero. Albo wyliczenie, któremu przypisano FlagsAttribute, definiuje element członkowski o wartości zero, ale jego nazwa nie jest 'None'. Lub wyliczenie definiuje wielu członków o zerowej wartości.

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 członka. 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 tym, jak FlagsAttribute jest używany, ponieważ operatory AND i OR bitowe są bezużyteczne w połączeniu z tym elementem. Oznacza to, że tylko jeden element członkowski powinien mieć przypisaną wartość zero. Jeśli wielu członków ma wartość zero i pojawiają się w wyliczeniu oznaczonym flagami, Enum.ToString() zwraca nieprawidłowe wyniki dla członków, które nie mają wartości zero.

Jak naprawić naruszenia

Aby naprawić naruszenie tej reguły w przypadku wyliczeń bez atrybutów flag, zdefiniuj element członkowski, który ma wartość zero; jest to zmiana niełamliwa. W przypadku wyliczeń z przypisanymi flagami, które definiują 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, która powoduje niezgodność.

Kiedy pomijać ostrzeżenia

Nie pomijaj ostrzeżenia z tej reguły z wyjątkiem wyliczeń opatrzonych flagami, 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 kodu mają być objęte tą regułą.

Możesz skonfigurować te opcje tylko dla tej reguły, dla wszystkich reguł, do których mają zastosowanie, lub dla wszystkich reguł w tej kategorii (Design), do których mają zastosowanie. 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óre części bazy kodu ma być stosowana ta reguła, na podstawie ich poziomu dostępu, ustawiając opcję api_surface. 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

Notatka

Zastąp część XXXXCAXXXX identyfikatorem odpowiedniej reguły.

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 None, jak i Never
dotnet_code_quality.CA1008.additional_enum_none_names = Never|Nothing Zezwala na None, Never i 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ż

  • Last updated on