CA1027: Marcar enumerações com FlagsAttribute

  • Artigo
Property Valor
ID da regra CA1027
Título Marcar enumerações com FlagsAttribute
Categoria Projetar
Correção interruptiva ou sem interrupção Sem interrupção
Habilitado por padrão no .NET 8 Não

Causa

Os valores de uma enumeração são poderes de dois ou são combinações de outros valores definidos na enumeração, e o atributo System.FlagsAttribute não está presente. Para reduzir falsos positivos, essa regra não relata uma violação para enumerações com valores contíguos.

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

Descrição da regra

Uma enumeração é um tipo de valor que define um conjunto de constantes nomeadas relacionadas. Aplique FlagsAttribute a uma enumeração quando suas constantes nomeadas puderem ser combinadas de maneira significativa. Por exemplo, considere uma enumeração dos dias da semana em um aplicativo que controla quais recursos do dia estão disponíveis. Se a disponibilidade de cada recurso for codificada usando a enumeração com o FlagsAttribute presente, qualquer combinação de dias poderá ser representada. Sem o atributo, somente um dia da semana pode ser representado.

Para campos que armazenam enumerações combináveis, os valores de enumeração individuais são tratados como grupos de bits no campo. Portanto, esses campos às vezes são chamados de campos de bits. Para combinar valores de enumeração para armazenamento em um campo de bits, use os operadores condicionais boolianos. Para testar um campo de bits a fim de determinar se um valor de enumeração específico está presente, use os operadores lógicos boolianos. Para que um campo de bits armazene e recupere valores de enumeração combinados corretamente, cada valor definido na enumeração deve ser uma potência de dois. A menos que seja assim, os operadores lógicos boolianos não poderão extrair os valores de enumeração individuais armazenados no campo.

Como corrigir violações

Para corrigir uma violação dessa regra, adicione FlagsAttribute à enumeração.

Quando suprimir avisos

Suprima um aviso dessa regra se você não quiser que os valores de enumeração sejam combináveis.

Suprimir um aviso

Para suprimir apenas uma violação, adicione diretivas de pré-processador ao arquivo de origem a fim de desabilitar e, em seguida, reabilitar a regra.

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

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

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

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

Configurar código para analisar

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

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

Incluir superfícies de API específicas

É possível configurar em quais partes da base de código essa regra deverá ser executada, com base na acessibilidade. Por exemplo, para especificar que a regra deverá ser executada apenas na superfície de API não pública, adicione o seguinte par chave-valor a um arquivo .editorconfig no projeto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Exemplo

No exemplo a seguir, DaysEnumNeedsFlags é uma enumeração que atende aos requisitos de uso do FlagsAttribute, mas que não o tem. A enumeração ColorEnumShouldNotHaveFlag não tem valores que são potências de dois, mas especifica FlagsAttribute incorretamente. Isso viola a regra CA2217: não marcar enums com FlagsAttribute.

// Violates rule: MarkEnumsWithFlags.
public enum DaysEnumNeedsFlags
{
    None = 0,
    Monday = 1,
    Tuesday = 2,
    Wednesday = 4,
    Thursday = 8,
    Friday = 16,
    All = Monday | Tuesday | Wednesday | Thursday | Friday
}

// Violates rule: DoNotMarkEnumsWithFlags.
[FlagsAttribute]
public enum ColorEnumShouldNotHaveFlag
{
    None = 0,
    Red = 1,
    Orange = 3,
    Yellow = 4
}

Confira também