Compartilhar via

CA1710: Identificadores devem ter um sufixo correto

  • Artigo
Property Valor
ID da regra CA1710
Título Identificadores devem ter um sufixo correto
Categoria Nomenclatura
Correção interruptiva ou sem interrupção Quebra
Habilitado por padrão no .NET 9 Não

Causa

Um identificador não tem o sufixo correto.

Por padrão, essa regra apenas analisará os identificadores visíveis externamente, mas isso é configurável.

Descrição da regra

Por convenção, os nomes dos tipos que estendem determinados tipos básicos ou que implementam determinadas interfaces, ou tipos derivados desses tipos, têm um sufixo associado ao tipo básico ou à interface.

As convenções de nomenclatura fornecem uma aparência comum para bibliotecas destinadas ao Common Language Runtime. Isso reduz a curva de aprendizado necessária para novas bibliotecas 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.

A tabela a seguir lista os tipos básicos e interfaces que possuem sufixos associados.

Tipo/interface base Sufixo
System.Attribute Attribute
System.EventArgs EventArgs
System.Exception Exception
System.Collections.ICollection Collection
System.Collections.IDictionary Dictionary
System.Collections.IEnumerable Collection
System.Collections.Generic.IReadOnlyDictionary<TKey,TValue> Dictionary
System.Collections.Queue Collection ou Queue
System.Collections.Stack Collection ou Stack
System.Collections.Generic.ICollection<T> Collection
System.Collections.Generic.IDictionary<TKey,TValue> Dictionary
System.Data.DataSet DataSet
System.Data.DataTable Collection ou DataTable
System.IO.Stream Stream
System.Security.IPermission Permission
System.Security.Policy.IMembershipCondition Condition
Um delegado de manipulador de eventos. EventHandler

Os tipos que implementam ICollection e são um tipo generalizado de estrutura de dados, como um dicionário, uma pilha ou uma fila, são nomes permitidos que fornecem informações significativas sobre o uso pretendido do tipo.

Tipos que implementam ICollection e são uma coleção de itens específicos têm nomes que terminam com a palavra Collection. Por exemplo, uma coleção de objetos Queue teria o nome QueueCollection. O sufixo Collection significa que os membros da coleção podem ser enumerados usando a instrução foreach (For Each no Visual Basic).

Os tipos que implementam IDictionary ou IReadOnlyDictionary<TKey,TValue> têm nomes que terminam com a palavra Dictionary mesmo que o tipo também implemente IEnumerable ou ICollection. As convenções de nomenclatura de sufixo Collection e Dictionary permitem que os usuários distinguem entre os dois padrões de enumeração a seguir.

Os tipos com o sufixo Collection seguem esse padrão de enumeração.

foreach(SomeType x in SomeCollection) { }

Os tipos com o sufixo Dictionary seguem esse padrão de enumeração.

foreach(SomeType x in SomeDictionary.Values) { }

Um objeto DataSet consiste em uma coleção de objetos DataTable que consistem em coleções e objetos System.Data.DataColumnSystem.Data.DataRow, entre outros. Essas coleções implementam ICollection por meio da classe base System.Data.InternalDataCollectionBase.

Como corrigir violações

Renomeie o tipo para que seja sufixado com o termo correto.

Quando suprimir avisos

É seguro suprimir um aviso para usar o sufixo Collection se o tipo for uma estrutura de dados generalizada que pode ser estendida ou que conterá um conjunto arbitrário de diversos itens. Nesse caso, um nome que forneça as informações significativas sobre a implementação, desempenho ou outras características da estrutura de dados pode fazer sentido (por exemplo, BinaryTree). Nos casos em que o tipo representa uma coleção de um tipo específico (por exemplo, StringCollection), não suprime um aviso dessa regra porque o sufixo indica que o tipo pode ser enumerado usando uma instrução foreach.

Para outros sufixos, não suprima um aviso dessa regra. O sufixo permite que o uso pretendido seja evidente a partir do nome do tipo.

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

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.CA1710.severity = none

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

Configurar código para analisar

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

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

Incluir superfícies de API específicas

Você pode configurar em quais partes da base de código executar essa regra, com base em sua acessibilidade, definindo a opção api_surface. 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

Nota

Substitua a parte XXXX de CAXXXX pela ID da regra aplicável.

Excluir tipos de base indiretos

Você poderá configurar se quiser excluir tipos de base indiretos da regra. Por padrão, essa opção é definida como verdadeira, o que restringe a análise ao tipo base atual.

dotnet_code_quality.CA1710.exclude_indirect_base_types = false

Sufixos adicionais necessários

É possível fornecer sufixos necessários adicionais ou substituir o comportamento de alguns sufixos codificados adicionando o seguinte par chave-valor a um arquivo .editorconfig no projeto:

dotnet_code_quality.CA1710.additional_required_suffixes = [type]->[suffix]

Separe vários valores com um caractere |. Os tipos podem ser especificados em um dos seguintes formatos:

  • Somente nome do tipo (inclui todos os tipos com o nome, independentemente do tipo ou namespace que contém).
  • Nomes totalmente qualificados no formato de ID de documentação do símbolo, com um prefixo opcional T:.

Exemplos:

Valor de Opção Resumo
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class Todos os tipos que herdam de 'MyClass' são necessários para ter o sufixo 'Class'.
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class|MyNamespace.IPath->Path Todos os tipos que herdam de 'MyClass' são necessários para ter o sufixo 'Class' E todos os tipos que implementam 'MyNamespace.IPath' são necessários para ter o sufixo 'Path'.
dotnet_code_quality.CA1710.additional_required_suffixes = T:System.Data.IDataReader->{} Substitui sufixos internos. Nesse caso, todos os tipos que implementam 'IDataReader' não são mais necessários para terminar em 'Coleção'.

CA1711: Identificadores não devem ter um sufixo incorreto

Confira também