CA1717: Apenas enumerações FlagsAttribute devem ter nomes no plural

  • Artigo
Property Valor
ID da regra CA1717
Título Apenas enumerações FlagsAttribute devem ter nomes no plural
Categoria Nomenclatura
Correção interruptiva ou sem interrupção Quebra
Habilitado por padrão no .NET 8 Não

Causa

O nome de uma enumeração termina em uma palavra plural e a enumeração não é marcada com o atributo System.FlagsAttribute.

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

Descrição da regra

As convenções de nomenclatura determinam que um nome plural para uma enumeração indica que mais de um valor da enumeração pode ser especificado simultaneamente. O FlagsAttribute informa aos compiladores que a enumeração deverá ser tratada como um campo de bits que habilita operações bit a bit na enumeração.

Se apenas um valor de uma enumeração puder ser especificado por vez, o nome da enumeração deverá ser uma palavra singular. Por exemplo, uma enumeração que define os dias da semana pode ser destinada a ser usada em um aplicativo em que você pode especificar vários dias. Essa enumeração deve ter o FlagsAttribute e poderá ser chamada de 'Days'. Uma enumeração semelhante que permite que apenas um único dia seja especificado não teria o atributo e poderia ser chamada de 'Day'.

As convenções de nomenclatura fornecem uma aparência comum para bibliotecas destinadas ao Common Language Runtime. Isso reduz o tempo necessário para aprender uma nova biblioteca de software e aumenta a confiança do cliente de que a biblioteca foi desenvolvida por alguém com experiência no desenvolvimento de código gerenciado.

Como corrigir violações

Faça do nome da enumeração uma palavra singular ou adicione o FlagsAttribute.

Quando suprimir avisos

É seguro suprimir um aviso da regra se o nome terminar em uma palavra singular.

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

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.CA1717.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 (Nomenclatura) à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

Confira também