Partilhar via

CA1027: Marcar enums com FlagsAttribute

  • Artigo
Property valor
ID da regra CA1027
Título Marcar enums com FlagsAttribute
Categoria Desenho
A correção está quebrando ou não quebrando Sem quebra
Habilitado por padrão no .NET 9 Não

Motivo

Os valores de uma enumeração são potências de dois ou são combinações de outros valores que são definidos na enumeração, e o System.FlagsAttribute atributo não está presente. Para reduzir falsos positivos, esta regra não relata uma violação para enumerações que têm valores contíguos.

Por padrão, essa regra examina apenas 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 forma 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 presente FlagsAttribute , qualquer combinação de dias poderá ser representada. Sem o atributo, apenas 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 booleanos. Para testar um campo bit para determinar se um valor de enumeração específico está presente, use os operadores lógicos booleanos. Para que um campo bit 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 isso seja assim, os operadores lógicos booleanos 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 desta regra se não quiser que os valores de enumeração sejam combináveis.

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 CA1027
// The code that's violating the rule is on this line.
#pragma warning restore CA1027

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

[*.{cs,vb}]
dotnet_diagnostic.CA1027.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

Exemplo

No exemplo a seguir, é uma enumeração que atende aos requisitos para usoFlagsAttribute, DaysEnumNeedsFlags mas não a tem. A ColorEnumShouldNotHaveFlag enumeração não tem valores que são poderes de dois, mas especifica FlagsAttributeincorretamente . 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
}

Consulte também