Share via

CA1700: Não nomear valores de enumeração 'Reserved'

  • Artigo
Property Valor
ID da regra CA1700
Título Não nomear valores de enumeração 'Reserved'
Categoria Nomenclatura
Correção interruptiva ou sem interrupção Quebra
Habilitado por padrão no .NET 8 Não

Causa

O nome de um membro de enumeração contém a palavra "reservado".

Descrição da regra

Esta regra pressupõe que um membro da enumeração que tenha um nome que contém "reserved" não é usado atualmente, mas é um espaço reservado a ser renomeado ou removido em uma versão futura. Renomear ou remover um membro é uma alteração drástica. Você não deve esperar que os usuários ignorem um membro apenas porque seu nome contém "reservado", nem pode confiar que os usuários leiam ou cumpram a documentação. Além disso, como os membros reservados aparecem em navegadores de objetos e ambientes de desenvolvimento integrados inteligentes, eles podem causar confusão sobre quais membros estão realmente sendo usados.

Em vez de usar um membro reservado, adicione um novo membro à enumeração na versão futura. Na maioria dos casos, a adição do novo membro não é uma alteração importante, desde que a adição não altere os valores dos membros originais.

Em um número limitado de casos, a adição de um membro é uma alteração importante, mesmo quando os membros originais mantêm seus valores originais. Principalmente, o novo membro não pode ser retornado de caminhos de código existentes sem interromper os chamadores que usam uma instrução switch (Select no Visual Basic) no valor de retorno que abrange toda a lista de membros e que lançam uma exceção no caso padrão. Uma preocupação secundária é que o código do cliente pode não lidar com a mudança de comportamento de métodos de reflexão como System.Enum.IsDefined. Consequentemente, se o novo membro tiver que ser retornado de métodos existentes ou ocorrer uma incompatibilidade de aplicativo conhecida devido ao uso insatisfatório de reflexão, a única solução ininterrupta é:

  1. Adicione uma nova enumeração que contém os membros originais e novos.

  2. Marque a enumeração original com o atributo System.ObsoleteAttribute.

    Siga o mesmo procedimento para quaisquer tipos ou membros visíveis externamente que exponham a enumeração original.

Como corrigir violações

Para corrigir uma violação desta regra, remova ou renomeie o membro.

Quando suprimir avisos

É seguro suprimir um aviso desta regra para um membro que está sendo usado no momento ou para bibliotecas que já foram enviadas.

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

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.CA1700.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

CA2217: Não marcar enumerações com FlagsAttribute

CA1712: Não prefixar valores de enumeração com um nome de tipo

CA1028: O armazenamento de enumerações deve ser Int32

CA1008: Enumerações devem ter valor zero

CA1027: Marcar enumerações com FlagsAttribute