Comparteix a través de

CA1008: Las enumeraciones deben tener un valor igual a cero

Propiedad Valor
Identificador de la regla CA1008
Título Las enumeraciones deben tener un valor igual a cero
Categoría Diseño
La corrección interrumpe o no interrumpe No bloqueante: cuando se le pida agregar un valor None a una enumeración sin bandera. Alerta: cuando se le pida renombrar o eliminar cualquier valor de enumeración.
Habilitado de forma predeterminada en .NET 10 No
Idiomas aplicables C# y Visual Basic

Causa

Una enumeración sin un elemento System.FlagsAttribute aplicado no define ningún miembro que tenga un valor de cero. O bien, una enumeración que tiene un elemento FlagsAttribute aplicado define un miembro que tiene un valor de cero, pero cuyo nombre no es "None". O bien, la enumeración define varios miembros que tienen un valor de cero.

De forma predeterminada, esta regla solo examina las enumeraciones visibles externamente, pero es configurable.

Descripción de la regla

El valor predeterminado de una enumeración no inicializada, igual que los otros tipos de valor, es cero. Una enumeración con atributo y sin marcadores debería definir un miembro que tenga el valor de cero de modo que el valor predeterminado sea un valor válido de la enumeración. Si procede, asigne al miembro el nombre «Ninguno» (o uno de los nombres permitidos adicionales). De lo contrario, asigne cero al miembro que se use con más frecuencia. De forma predeterminada, si el valor del primer miembro de la enumeración no se establece en la declaración, su valor es cero.

Si una enumeración a la que se le haya aplicado define un miembro con valor cero, su nombre debe ser «Ninguno» (o uno de los nombres adicionales permitidos ) para indicar que no se han establecido valores en la enumeración. El uso de un miembro con valor cero para cualquier otro propósito es contrario al uso de FlagsAttribute en que los operadores bit a bit AND y OR son inútiles con el miembro. Esto implica que solo un miembro debe tener asignado el valor cero. Si se producen varios miembros que tienen el valor cero en una enumeración con atributo y marcadores, Enum.ToString() devuelve resultados incorrectos para los miembros que no son cero.

Cómo corregir infracciones

Para corregir una infracción de esta regla en enumeraciones no atribuidas a flags, defina un miembro que tenga el valor 0; se trata de un cambio sin ruptura. En el caso de las enumeraciones con atributo y marcadores que definen un miembro con valor cero, asigne el nombre "None" a este miembro y elimine cualquier otro miembro que tenga un valor cero; se trata de un cambio importante.

Cuándo suprimir las advertencias

No suprima las advertencias de esta regla, excepto para las enumeraciones con atributos de banderas que se hayan enviado previamente.

Supresión de una advertencia

Si solo quiere suprimir una única infracción, agregue directivas de preprocesador al archivo de origen para deshabilitar y volver a habilitar la regla.

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

Para deshabilitar la regla de un archivo, una carpeta o un proyecto, establezca su gravedad en none del archivo de configuración.

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

Para obtener más información, consulte Procedimiento para suprimir advertencias de análisis de código.

Configuración del código para analizar

Use la opción siguiente para configurar en qué partes del código base ejecutar esta regla.

Puede configurar estas opciones tan solo para esta regla, para todas las reglas a las que sean aplicables o para todas las reglas de esta categoría (Design) para las que sean aplicables. Para más información, vea Opciones de configuración de reglas de calidad de código.

Incluir superficies de API específicas

Puede configurar en qué partes del código base se ejecutará esta regla, en función de su accesibilidad, mediante la configuración de la opción api_surface. Por ejemplo, para especificar que la regla solo se debe ejecutar en la superficie de API no públicas, agregue el siguiente par clave-valor a un archivo .editorconfig en el proyecto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Nota:

Reemplace la parte XXXX de CAXXXX por el identificador de la regla que sea de aplicación.

Nombres de campo de valor cero adicionales

En .NET 7 y versiones posteriores, puede configurar otros nombres permitidos para un campo de enumeración de valor cero, además de None. Separa varios nombres por el carácter |. En la tabla siguiente se proporcionan algunos ejemplos.

Valor de la opción Resumen
dotnet_code_quality.CA1008.additional_enum_none_names = Never Permite None y Never
dotnet_code_quality.CA1008.additional_enum_none_names = Never|Nothing Permite None, Never, y Nothing

Ejemplo

En el ejemplo siguiente se muestran dos enumeraciones que cumplen la regla y una enumeración, BadTraceOptions, que la infringe.

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 también

  • Last updated on