Partilhar via

CA1008: Enums deve ter valor zero

  • Artigo
Property valor
ID da regra CA1008
Título Enums deve ter valor zero
Categoria Desenho
A correção está quebrando ou não quebrando Non-breaking - Quando você é solicitado a adicionar um None valor a uma enumeração não-sinalizador. Quebrando - Quando você for solicitado a renomear ou remover quaisquer valores de enumeração.
Habilitado por padrão no .NET 9 Não

Motivo

Uma enumeração sem um aplicado System.FlagsAttribute não define um membro que tenha um valor zero. Ou, uma enumeração que tem um aplicado FlagsAttribute define um membro que tem um valor de zero, mas seu nome não é 'Nenhum'. Ou, a enumeração define vários membros com valor zero.

Por padrão, essa regra examina apenas enumerações visíveis externamente, mas isso é configurável.

Descrição da regra

O valor padrão de uma enumeração não inicializada, assim como outros tipos de valor, é zero. Uma enumeração não atribuída a sinalizadores deve definir um membro que tenha o valor zero para que o valor padrão seja um valor válido da enumeração. Se for caso disso, nomeie o membro como «Nenhum» (ou um dos nomes adicionais permitidos). Caso contrário, atribua zero ao membro usado com mais frequência. Por padrão, se o valor do primeiro membro de enumeração não estiver definido na declaração, seu valor será zero.

Se uma enumeração que tem o FlagsAttribute aplicado define um membro de valor zero, seu nome deve ser 'Nenhum' (ou um dos nomes adicionais permitidos) para indicar que nenhum valor foi definido na enumeração. Usar um membro de valor zero para qualquer outra finalidade é contrário ao uso do FlagsAttribute em que os AND OR operadores e bitwise são inúteis com o membro. Isto implica que apenas um membro deve ser atribuído o valor zero. Se vários membros que têm o valor zero ocorrerem em uma enumeração atribuída a sinalizadores, Enum.ToString() retornará resultados incorretos para membros que não são zero.

Como corrigir violações

Para corrigir uma violação dessa regra para enumerações não atribuídas a sinalizadores, defina um membro que tenha o valor zero; trata-se de uma mudança ininterrupta. Para enumerações atribuídas a sinalizadores que definem um membro com valor zero, nomeie esse membro como 'Nenhum' e exclua quaisquer outros membros que tenham um valor zero; Esta é uma mudança revolucionária.

Quando suprimir avisos

Não suprima um aviso desta regra, exceto para enumerações atribuídas a sinalizadores que tenham sido enviadas anteriormente.

Suprimir um aviso

Se você quiser apenas suprimir uma única violação, adicione diretivas de pré-processador ao seu arquivo de origem para desativar e, em seguida, reativar a regra.

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

Para desabilitar a regra de um arquivo, pasta ou projeto, defina sua gravidade como none no arquivo de configuração.

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

Para obter mais informações, consulte Como suprimir avisos de análise de código.

Configurar código para análise

Use a opção a seguir para configurar em quais partes da sua base de código executar essa regra.

Você pode configurar essa opção apenas para esta regra, para todas as regras às quais ela se aplica ou para todas as regras nesta categoria (Design) às quais ela se aplica. Para obter mais informações, consulte Opções de configuração da regra de qualidade de código.

Incluir superfícies de API específicas

Você pode configurar em quais partes da sua base de código executar essa regra, com base em sua acessibilidade. Por exemplo, para especificar que a regra deve ser executada somente na superfície de API não pública, adicione o seguinte par chave-valor a um arquivo .editorconfig em seu projeto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Nomes de campos adicionais de valor zero

No .NET 7 e versões posteriores, você pode configurar outros nomes permitidos para um campo de enumeração de valor zero, além Nonede . Separe vários nomes pelo | personagem. A tabela a seguir mostra alguns exemplos.

Valor da opção Resumo
dotnet_code_quality.CA1008.additional_enum_none_names = Never Permite que ambos e NoneNever
dotnet_code_quality.CA1008.additional_enum_none_names = Never|Nothing Permite None, Nevere Nothing

Exemplo

O exemplo a seguir mostra duas enumerações que satisfazem a regra e uma enumeração, BadTraceOptions, que viola a regra.

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

Consulte também