Regras de design

  • Artigo

As regras de design dão suporte à adesão às Diretrizes de design do .NET Framework.

Nesta seção

Regra Descrição
CA1000: Não declarar membros estáticos em tipos genéricos Quando um membro estático de um tipo genérico é chamado, o argumento de tipo deve ser especificado para o tipo. Quando um membro de instância genérico que não dá suporte à inferência é chamado, o argumento de tipo deve ser especificado para o membro. Nesses dois casos, a sintaxe para especificar o argumento de tipo é diferente e facilmente confundida.
CA1001: Tipos com campos descartáveis devem ser descartáveis Uma classe declara e implementa um campo de instância que é um tipo System.IDisposable, e a classe não implementa IDisposable. Uma classe que declara um campo IDisposable indiretamente possui um recurso não gerenciado e deve implementar a interface IDisposable.
CA1002: Não expor listas genéricas A System.Collections.Generic.List<(Of <(T>)>) é uma coleção genérica projetada para desempenho, não para herança. Por isso, List não contém membros virtuais. As coleções genéricas projetadas para herança devem ser expostas em seu lugar.
CA1003: Usar instâncias do manipulador de eventos genérico Um tipo contém um representante que retorna nulo, cuja assinatura contém dois parâmetros (o primeiro um objeto e o segundo um tipo atribuível a EventArgs), e o destino do assembly de contenção é o .NET Framework 2.0.
CA1005: Evitar parâmetros excessivos em tipos genéricos Quanto mais parâmetros de tipo um tipo genérico contiver, mais difícil será saber e lembrar-se do que cada parâmetro de tipo representa. Geralmente, a função é óbvia com um parâmetro de tipo, como em List<T>, e em certos casos com dois parâmetros de tipo, como em Dictionary<TKey, TValue>. No entanto, se houver mais de dois parâmetros de tipo, a dificuldade ficará muito grande para a maioria dos usuários.
CA1008: Enumerações devem ter valor zero O valor padrão de uma enumeração não inicializada, assim como o de outros tipos de valor, é zero. Uma enumeração atribuída por nonflags deve definir um membro usando o valor de zero de forma que o valor padrão seja um valor válido da enumeração. Se uma enumeração que tem o atributo FlagsAttribute aplicado definir um membro com valor, seu nome deverá ser “None” para indicar que nenhum valor foi definido na enumeração.
CA1010: Coleções devem implementar uma interface genérica Para ampliar a usabilidade de uma coleção, implemente uma das interfaces da coleção genéricas. Em seguida, a coleção pode ser usada para popular tipos de coleção genéricos.
CA1012: tipos abstratos não devem ter construtores públicos Construtores em tipos abstratos só podem ser chamados por tipos derivados. Como construtores públicos criam instâncias de um tipo e não é possível criar instâncias de um tipo abstrato, um tipo abstrato com um construtor público é projetado incorretamente.
CA1014: Marcar assemblies com CLSCompliantAttribute A CLS (Common Language Specification) define restrições de nomenclatura, tipos de dados e regras que assemblies deverão respeitar se forem usados em todas as linguagens de programação. Um bom design determina que todos os assemblies indiquem explicitamente a conformidade com CLS usando CLSCompliantAttribute. Se esse atributo não estiver presente em um assembly, o assembly não será compatível.
CA1016: Marcar assemblies com AssemblyVersionAttribute O .NET usa o número da versão para identificar exclusivamente um assembly e fazer a associação com tipos em assemblies fortemente nomeados. O número de versão é usado com a versão e a política do publicador. Por padrão, os aplicativos só são executados com a versão do assembly com que foram criados.
CA1017: Marcar assemblies com ComVisibleAttribute ComVisibleAttribute determina como clientes COM acessam código gerenciado. Um bom design determina que os assemblies indiquem explicitamente a visibilidade de COM. A visibilidade de COM pode ser definida para todo o assembly e, em seguida, substituída por tipos individuais e membros de tipo. Caso esse atributo não esteja presente, o conteúdo do assembly permanece visível aos clientes COM.
CA1018: Marcar atributos com AttributeUsageAttribute Ao definir um atributo personalizado, você o marca usando AttributeUsageAttribute para indicar onde o atributo personalizado pode ser aplicado no código-fonte. O significado e o uso desejado de um atributo determinarão seus locais válidos no código.
CA1019: Definir acessadores para argumentos de atributo Os atributos podem definir argumentos obrigatórios que devem ser especificados quando você aplica o atributo a um destino. Eles também são conhecidos como argumentos posicionais porque são fornecidos a construtores de atributos como parâmetros posicionais. Para cada argumento obrigatório, o atributo também deve fornecer uma propriedade somente leitura correspondente de forma que o valor do argumento possa ser recuperado no tempo de execução. Os atributos também podem definir argumentos opcionais, que também são conhecidos como argumentos nomeados. Esses argumentos são fornecidos a construtores de atributo por nome e devem ter uma propriedade de leitura/gravação correspondente.
CA1021: Evitar parâmetros out A passagem de tipos por referência (usando out ou ref) requer experiência com ponteiros, compreensão das diferenças entre tipos de valor e tipos de referência e os métodos de tratamento com vários valores de retorno. Além disso, a diferença entre parâmetros out e ref não é amplamente compreendida.
CA1024: Usar propriedades quando apropriado Um método público ou protegido tem um nome que começa com "Get", não utiliza parâmetros e retorna um valor que não é uma matriz. O método pode ser um bom candidato a se tornar uma propriedade.
CA1027: Marcar enumerações com FlagsAttribute 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 maneira significativa.
CA1028: O armazenamento de enumerações deve ser Int32 Uma enumeração é um tipo de valor que define um conjunto de constantes nomeadas relacionadas. Por padrão, o tipo de dados System.Int32 é usado para armazenar o valor constante. Embora seja possível alterar esse tipo subjacente, isso não é necessário ou recomendado na maioria dos cenários.
CA1030: Usar eventos quando apropriado Essa regra detecta métodos que têm nomes que seriam usados normalmente em eventos. Se um método for chamado em resposta a uma alteração de estado claramente definida, o método deverá ser invocado por um manipulador de eventos. Os objetos que chamam o método devem acionar eventos, em vez de chamar o método diretamente.
CA1031: Não capturar tipos de exceção geral As exceções gerais não devem ser capturadas. Capture uma exceção mais específica ou relance a exceção geral como a última instrução no bloco de captura.
CA1032: Implementar construtores de exceção padrão Deixar de fornecer o conjunto completo de construtores pode dificultar o tratamento correto das exceções.
CA1033: Métodos de interface devem ser chamados por tipos filho Um tipo visível externamente sem lacre fornece uma implementação de método explícita de uma interface pública e não fornece um método visível externamente alternativo com o mesmo nome.
CA1034: Tipos aninhados não devem ser visíveis Um tipo aninhado é um tipo declarado no escopo de outro tipo. Os tipos aninhados são úteis para encapsular detalhes de implementação privados do tipo de contenção. Usados para essa finalidade, os tipos aninhados não devem ser visíveis externamente.
CA1036: Substituir métodos em tipos comparáveis Um público ou um tipo protegido implementa a interface System.IComparable. Ele não substitui Object.Equals nem sobrecarrega o operador específico da linguagem para igualdade, desigualdade, menor que ou maior que.
CA1040: Evitar interfaces vazias As interfaces definem os membros que fornecem um contrato de comportamento ou de uso. A funcionalidade descrita pela interface pode ser adotada por qualquer tipo, independentemente de onde o tipo seja exibido na hierarquia de herança. Um tipo implementa uma interface fornecendo implementações para os membros da interface. Uma interface vazia não define membros; por isso, ela não define um contrato que pode ser implementado.
CA1041: Fornecer a mensagem ObsoleteAttribute Um tipo ou um membro é marcado usando-se um atributo System.ObsoleteAttribute que não tem sua propriedade ObsoleteAttribute.Message especificada. Quando um tipo ou membro marcado pelo uso de ObsoleteAttribute é compilado, a propriedade Message do atributo é exibida, o que fornece ao usuário informações sobre o tipo obsoleto ou membro.
CA1043: Usar argumento integral ou de cadeia de caracteres para indexadores Os indicadores (ou seja, propriedades indexadas) devem usar tipos integrais ou de cadeia de caracteres no índice. Esses tipos normalmente são usados na indexação de estruturas de dados e aumentam a usabilidade da biblioteca. O uso do tipo Object deve ser restrito a esses casos em que o tipo integral ou de cadeia de caracteres específico não pode ser especificado no tempo de design.
CA1044: Propriedades não devem ser somente gravação Embora seja aceitável e normalmente necessário ter uma propriedade somente leitura, as diretrizes de design proíbem o uso de propriedades somente gravação. Isso é porque a permissão para que um usuário defina um valor e o impedimento posterior para ele exiba esse valor não dão nenhuma segurança. Além disso, sem acesso de leitura, o estado de objetos compartilhados não pode ser exibido, o que limita sua utilidade.
CA1045: Não passar tipos por referência A passagem de tipos por referência (usando out ou ref) requer experiência com ponteiros, compreensão das diferenças entre tipos de valor e tipos de referência e os métodos de tratamento com vários valores de retorno. Os arquitetos de bibliotecas com designs que visam um público geral não devem esperar que os usuários se tornem proficientes em trabalhar com parâmetros out ou ref.
CA1046: Não sobrecarregar o operador equals em tipos de referência Para tipos de referência, a implementação padrão do operador de igualdade está quase sempre correta. Por padrão, duas referências só serão iguais se apontarem para o mesmo objeto.
CA1047: Não declarar membros protegidos em tipos selados Os tipos declaram membros protegidos de forma que a herança de tipos possa acessar ou substituir o membro. Por definição, os tipos vedados não podem ser lacrados, o que significa que os métodos protegidos em tipos lacrados não podem ser chamados.
CA1050: Declarar tipos em namespaces Tipos são declarados em namespaces para evitar conflitos de nome e são uma maneira de organizar tipos relacionados em uma hierarquia de objetos.
CA1051: Não declarar campos de instância visíveis O principal uso de um campo deve ser um como um detalhe da implementação. Os campos devem ser privados ou internos e devem ser expostos usando-se propriedades.
CA1052: Tipos de suporte estático devem ser selados Um tipo público ou protegido contém apenas membros estáticos e não é declarado usando o modificador selado (C#) ou NotInheritable (Visual Basic). Um tipo que não é deve ser herdado deve ser marcado usando-se o modificador lacrado para evitar seu uso como um tipo de base.
CA1053: Tipos de suporte estático não devem ter construtores Um tipo público ou público aninhado declara apenas membros estáticos e tem um construtor padrão público ou protegido. O construtor é desnecessário porque chamar membros estáticos não exige uma instância do tipo. A sobrecarga de cadeia de caracteres deve chamar a sobrecarga do URI (Uniform Resource Identifier) usando-se o argumento de cadeia de caracteres por questões de segurança.
CA1054: Parâmetros de URI não devem ser cadeias de caracteres Se um método utilizar uma representação de cadeia de caracteres de um URI, uma sobrecarga correspondente deverá ser fornecida utilizando uma instância da classe do URI, que oferece esses serviços de maneira segura e protegida.
CA1055: Valores de retorno de URI não devem ser cadeias de caracteres Esta regra pressupõe que o método retorne um URI. Uma representação de cadeia de caracteres de um URI está propensa a erros de análise e de codificação, e pode resultar em vulnerabilidades de segurança. A classe System.Uri fornece esses serviços de maneira segura.
CA1056: Propriedades de URI não devem ser cadeias de caracteres Esta regra pressupõe que a propriedade represente o URI. Uma representação de cadeia de caracteres de um URI está propensa a erros de análise e de codificação, e pode resultar em vulnerabilidades de segurança. A classe System.Uri fornece esses serviços de maneira segura.
CA1058: Tipos não devem estender determinados tipos base Um tipo visível externamente estende determinados tipos de base. Use uma das alternativas.
CA1060: mover P/Invokes para a classe NativeMethods Os métodos de invocação de plataforma, como aqueles marcados com System.Runtime.InteropServices.DllImportAttribute ou os métodos definidos usando a palavra-chave Declare no Visual Basic, acessam código não gerenciado. Esses métodos devem ser da classe NativeMethods, SafeNativeMethods ou UnsafeNativeMethods.
CA1061: Não ocultar métodos de classe base Um método em um tipo de base permanece oculto por um método nomeado identicamente em um tipo derivado, quando a assinatura do parâmetro do método derivado difere apenas pelos tipos derivados de maneira mais fraca do que os tipos correspondentes na assinatura do parâmetro do método de base.
CA1062: Validar argumentos de métodos públicos Todos os argumentos de referência passados para os métodos visíveis externamente devem ser verificados em relação que serão nulos.
CA1063: Implementar IDisposable corretamente Todos os tipos IDisposable devem implementar o padrão Dispose corretamente.
CA1064: Exceções devem ser públicas Uma exceção interna só permanece visível dentro do próprio escopo interno. Depois que a exceção falha fora do escopo interno, somente a exceção de base pode ser usada para capturar a exceção. Se a exceção interna for herdada de System.Exception, System.SystemException ou System.ApplicationException, o código externo não terá informações suficientes para saber o que fazer com a exceção.
CA1065: Não acionar exceções em locais inesperados Um método que não deve acionar exceções aciona uma exceção.
CA1066: Implementar IEquatable ao substituir Equals Um tipo de valor substitui o método Equals, mas não implementa IEquatable<T>.
CA1067: Substituir Equals ao implementar IEquatable Um tipo implementa IEquatable<T>, mas não substitui o método Equals.
CA1068: Os parâmetros CancellationToken devem vir por último Um método tem um parâmetro CancellationToken que não é o último parâmetro.
CA1069: Enumerações não devem ter valores duplicados Uma enumeração tem diversos membros explicitamente atribuídos ao mesmo valor de constante.
CA1070: Não declarar os campos de evento como virtuais Um evento do tipo campo foi declarado como virtual.