Partilhar via

CA1710: Os identificadores devem ter o sufixo correto

  • Artigo
Property valor
ID da regra CA1710
Título Os identificadores devem ter o sufixo correto
Categoria Atribuição de nomes
A correção está quebrando ou não quebrando Quebrando
Habilitado por padrão no .NET 8 Não

Motivo

Um identificador não tem o sufixo correto.

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

Descrição da regra

Por convenção, os nomes dos tipos que estendem certos tipos base ou que implementam determinadas interfaces, ou tipos derivados desses tipos, têm um sufixo associado ao tipo base ou interface.

As convenções de nomenclatura fornecem uma aparência comum para bibliotecas que visam o 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 base e interfaces que têm sufixos associados.

Tipo de base/Interface Sufixo
System.Attribute Atributo
System.EventArgs EventArgs
System.Exception Exceção
System.Collections.ICollection Coleção
System.Collections.IDictionary Dicionário
System.Collections.IEnumerable Coleção
System.Collections.Generic.IReadOnlyDictionary<TKey,TValue> Dicionário
System.Collections.Queue Recolha ou Fila
System.Collections.Stack Coleção ou Pilha
System.Collections.Generic.ICollection<T> Coleção
System.Collections.Generic.IDictionary<TKey,TValue> Dicionário
System.Data.DataSet Conjunto de dados
System.Data.DataTable Coleção ou DataTable
System.IO.Stream Fluxo
System.Security.IPermission Permissão
System.Security.Policy.IMembershipCondition Condição
Um delegado manipulador de eventos. Manipulador de eventos

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

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

Tipos que implementam ou têm nomes que terminam com a palavra 'Dicionário', mesmo que o tipo também implemente IDictionaryIEnumerable ou IReadOnlyDictionary<TKey,TValue>ICollection. As convenções de nomenclatura do sufixo 'Collection' e 'Dictionary' permitem que os usuários distingam entre os dois padrões de enumeração a seguir.

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

foreach(SomeType x in SomeCollection) { }

Os tipos com o sufixo 'Dicionário' seguem este padrão de enumeração.

foreach(SomeType x in SomeDictionary.Values) { }

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

Como corrigir violações

Renomeie o tipo para que ele seja sufixo 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 itens diversos. Nesse caso, um nome que forneça informações significativas sobre a implementação, 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 suprima um aviso dessa regra porque o sufixo indica que o tipo pode ser enumerado usando uma foreach instrução.

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

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

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

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

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

Configurar código para análise

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

Você pode configurar essas opções apenas para esta regra, para todas as regras às quais ela se aplica ou para todas as regras nesta categoria (Nomenclatura) à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

Excluir tipos de base indiretos

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

dotnet_code_quality.CA1710.exclude_indirect_base_types = false

Sufixos adicionais necessários

Você pode fornecer sufixos adicionais necessários ou substituir o comportamento de alguns sufixos codificados adicionando o seguinte par chave-valor a um arquivo .editorconfig em seu projeto:

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

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

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

Exemplos:

Valor da opção Resumo
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class Todos os tipos que herdam de 'MyClass' são obrigados a 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 obrigados a ter o sufixo 'Class' E todos os tipos que implementam 'MyNamespace.IPath' são obrigados a 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 'Collection'.

CA1711: Os identificadores não devem ter sufixo incorreto

Consulte também