CA1008: Wyliczenia powinny mieć wartość zero
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 None polecenia , Never i Nothing |
Przykład
W poniższym przykładzie przedstawiono dwa wyliczenia spełniające regułę i wyliczenie , BadTraceOptions
któ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
Powiązane reguły
- CA2217: Nie oznaczaj wyliczeń za pomocą atrybutu FlagsAttribute
- CA1700: Nie nadawaj wartościom wyliczenia nazwy „Reserved”
- CA1712: Nie poprzedzaj wartości wyliczenia nazwą typu
- CA1028: Magazyn typu wyliczeniowego powinien być typu Int32
- CA1027: Oznacz typy wyliczeniowe atrybutem Flags