Regras de designDesign rules

As regras de design dão suporte à adesão às diretrizes de design de .NET Framework.Design rules support adherence to the .NET Framework design guidelines.

Nesta seçãoIn this section

RegraRule DescriptionDescription
CA1000: Não declarar membros estáticos em tipos genéricosCA1000: Do not declare static members on generic types Quando um membro estático de um tipo genérico é chamado, o argumento de tipo deve ser especificado para o tipo.When a static member of a generic type is called, the type argument must be specified for the type. 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.When a generic instance member that does not support inference is called, the type argument must be specified for the member. Nesses dois casos, a sintaxe para especificar o argumento de tipo é diferente e facilmente confundida.In these two cases, the syntax for specifying the type argument is different and easily confused.
CA1001: Tipos com campos descartáveis devem ser descartáveisCA1001: Types that own disposable fields should be disposable Uma classe declara e implementa um campo de instância que é um tipo System. IDisposable e a classe não implementa IDisposable.A class declares and implements an instance field that is a System.IDisposable type and the class does not implement IDisposable. Uma classe que declara um campo IDisposable indiretamente possui um recurso não gerenciado e deve implementar a interface IDisposable.A class that declares an IDisposable field indirectly owns an unmanaged resource and should implement the IDisposable interface.
CA1002: Não expor listas genéricasCA1002: Do not expose generic lists System. Collections. Generic. List< (Of <(T> ) >) é uma coleção genérica projetada para desempenho, não herança.System.Collections.Generic.List<(Of <(T>)>) is a generic collection that is designed for performance, not inheritance. Por isso, List não contém membros virtuais.Therefore, List does not contain any virtual members. As coleções genéricas projetadas para herança devem ser expostas em seu lugar.The generic collections that are designed for inheritance should be exposed instead.
CA1003: Usar instâncias do manipulador de eventos genéricoCA1003: Use generic event handler instances Um tipo contém um delegado que retorna void, cuja assinatura contém dois parâmetros (o primeiro objeto e o segundo um tipo que pode ser atribuído a EventArgs) e o assembly de destinos que o contém .NET Framework 2,0.A type contains a delegate that returns void, whose signature contains two parameters (the first an object and the second a type that is assignable to EventArgs), and the containing assembly targets .NET Framework 2.0.
CA1005: Evitar parâmetros excessivos em tipos genéricosCA1005: Avoid excessive parameters on generic types 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.The more type parameters a generic type contains, the more difficult it is to know and remember what each type parameter represents. Normalmente, é óbvio com um parâmetro de tipo, como na lista <T> e, em certos casos, com dois parâmetros de tipo, como no dicionário <TKey, TValue> .It is usually obvious with one type parameter, as in List<T>, and in certain cases with two type parameters, as in 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.However, if more than two type parameters exist, the difficulty becomes too great for most users.
CA1008: Enumerações devem ter valor zeroCA1008: Enums should have zero value O valor padrão de uma enumeração não inicializada, assim como o de outros tipos de valor, é zero.The default value of an uninitialized enumeration, just as other value types, is zero. Uma enumeração atribuída não sinalizações deve definir um membro usando o valor de zero para que o valor padrão seja um valor válido da enumeração.A nonflags attributed enumeration should define a member by using the value of zero so that the default value is a valid value of the enumeration. 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.If an enumeration that has the FlagsAttribute attribute applied defines a zero-valued member, its name should be "None" to indicate that no values have been set in the enumeration.
CA1010: Coleções devem implementar uma interface genéricaCA1010: Collections should implement generic interface Para ampliar a usabilidade de uma coleção, implemente uma das interfaces da coleção genéricas.To broaden the usability of a collection, implement one of the generic collection interfaces. Em seguida, a coleção pode ser usada para popular tipos de coleção genéricos.Then the collection can be used to populate generic collection types.
CA1012: Tipos abstratos não devem ter construtoresCA1012: Abstract types should not have constructors Construtores em tipos abstratos só podem ser chamados por tipos derivados.Constructors on abstract types can be called only by derived types. 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.Because public constructors create instances of a type, and you cannot create instances of an abstract type, an abstract type that has a public constructor is incorrectly designed.
CA1014: Marcar assemblies com CLSCompliantAttributeCA1014: Mark assemblies with 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.The Common Language Specification (CLS) defines naming restrictions, data types, and rules to which assemblies must conform if they will be used across programming languages. Um bom design dita que todos os assemblies indicam explicitamente a conformidade com CLS usando o CLSCompliantAttribute.Good design dictates that all assemblies explicitly indicate CLS compliance by using CLSCompliantAttribute. Se esse atributo não estiver presente em um assembly, o assembly não será compatível.If this attribute is not present on an assembly, the assembly is not compliant.
CA1016: Marcar assemblies com AssemblyVersionAttributeCA1016: Mark assemblies with AssemblyVersionAttribute O .NET usa o número de versão para identificar exclusivamente um assembly e para associar a tipos em assemblies com nomes de alta segurança..NET uses the version number to uniquely identify an assembly, and to bind to types in strongly named assemblies. O número de versão é usado com a versão e a política do publicador.The version number is used together with version and publisher policy. Por padrão, os aplicativos só são executados com a versão do assembly com que foram criados.By default, applications run only with the assembly version with which they were built.
CA1017: Marcar assemblies com ComVisibleAttributeCA1017: Mark assemblies with ComVisibleAttribute ComVisibleAttribute determina como clientes COM acessam código gerenciado.ComVisibleAttribute determines how COM clients access managed code. Um bom design determina que os assemblies indiquem explicitamente a visibilidade de COM.Good design dictates that assemblies explicitly indicate COM visibility. A visibilidade de COM pode ser definida para todo o assembly e, em seguida, substituída por tipos individuais e membros de tipo.COM visibility can be set for the whole assembly and then overridden for individual types and type members. Caso esse atributo não esteja presente, o conteúdo do assembly permanece visível aos clientes COM.If this attribute is not present, the contents of the assembly are visible to COM clients.
CA1018: Marcar atributos com AttributeUsageAttributeCA1018: Mark attributes with AttributeUsageAttribute Ao definir um atributo personalizado, você o marca usando AttributeUsageAttribute para indicar onde o atributo personalizado pode ser aplicado no código-fonte.When you define a custom attribute, mark it by using AttributeUsageAttribute to indicate where in the source code the custom attribute can be applied. O significado e o uso desejado de um atributo determinarão seus locais válidos no código.The meaning and intended usage of an attribute will determine its valid locations in code.
CA1019: Definir acessadores para argumentos de atributoCA1019: Define accessors for attribute arguments Os atributos podem definir argumentos obrigatórios que devem ser especificados quando você aplica o atributo a um destino.Attributes can define mandatory arguments that must be specified when you apply the attribute to a target. Eles também são conhecidos como argumentos posicionais porque são fornecidos a construtores de atributos como parâmetros posicionais.These are also known as positional arguments because they are supplied to attribute constructors as positional parameters. 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.For every mandatory argument, the attribute should also provide a corresponding read-only property so that the value of the argument can be retrieved at execution time. Os atributos também podem definir argumentos opcionais, que também são conhecidos como argumentos nomeados.Attributes can also define optional arguments, which are also known as named arguments. Esses argumentos são fornecidos a construtores de atributo por nome e devem ter uma propriedade de leitura/gravação correspondente.These arguments are supplied to attribute constructors by name and should have a corresponding read/write property.
CA1021: Evitar parâmetros outCA1021: Avoid out parameters 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.Passing types by reference (using out or ref) requires experience with pointers, understanding how value types and reference types differ, and handling methods with multiple return values. Além disso, a diferença entre parâmetros out e ref não é amplamente compreendida.Also, the difference between out and ref parameters is not widely understood.
CA1024: Usar propriedades quando apropriadoCA1024: Use properties where appropriate 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.A public or protected method has a name that starts with "Get", takes no parameters, and returns a value that is not an array. O método pode ser um bom candidato a se tornar uma propriedade.The method might be a good candidate to become a property.
CA1027: Marcar enumerações com FlagsAttributeCA1027: Mark enums with FlagsAttribute Uma enumeração é um tipo de valor que define um conjunto de constantes nomeadas relacionadas.An enumeration is a value type that defines a set of related named constants. Aplique FlagsAttribute a uma enumeração quando suas constantes nomeadas puderem ser combinadas de maneira significativa.Apply FlagsAttribute to an enumeration when its named constants can be meaningfully combined.
CA1028: O armazenamento de enumerações deve ser Int32CA1028: Enum storage should be Int32 Uma enumeração é um tipo de valor que define um conjunto de constantes nomeadas relacionadas.An enumeration is a value type that defines a set of related named constants. Por padrão, o tipo de dados System.Int32 é usado para armazenar o valor constante.By default, the System.Int32 data type is used to store the constant value. Embora você possa alterar esse tipo subjacente, ele não é obrigatório ou recomendado para a maioria dos cenários.Even though you can change this underlying type, it is not required or recommended for most scenarios.
CA1030: Usar eventos quando apropriadoCA1030: Use events where appropriate Essa regra detecta métodos que têm nomes que seriam usados normalmente em eventos.This rule detects methods that have names that ordinarily would be used for events. 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.If a method is called in response to a clearly defined state change, the method should be invoked by an event handler. Os objetos que chamam o método devem acionar eventos, em vez de chamar o método diretamente.Objects that call the method should raise events instead of calling the method directly.
CA1031: Não capturar tipos de exceção geralCA1031: Do not catch general exception types As exceções gerais não devem ser capturadas.General exceptions should not be caught. Pegue uma exceção mais específica ou relance a exceção geral como a última instrução no bloco catch.Catch a more-specific exception, or rethrow the general exception as the last statement in the catch block.
CA1032: Implementar construtores de exceção padrãoCA1032: Implement standard exception constructors Deixar de fornecer o conjunto completo de construtores pode dificultar o tratamento correto das exceções.Failure to provide the full set of constructors can make it difficult to correctly handle exceptions.
CA1033: Métodos de interface devem ser chamados por tipos filhoCA1033: Interface methods should be callable by child types 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.An unsealed externally visible type provides an explicit method implementation of a public interface and does not provide an alternative externally visible method that has the same name.
CA1034: Tipos aninhados não devem ser visíveisCA1034: Nested types should not be visible Um tipo aninhado é um tipo declarado no escopo de outro tipo.A nested type is a type that is declared in the scope of another type. Os tipos aninhados são úteis para encapsular detalhes de implementação privados do tipo de contenção.Nested types are useful to encapsulate private implementation details of the containing type. Usados para essa finalidade, os tipos aninhados não devem ser visíveis externamente.Used for this purpose, nested types should not be externally visible.
CA1036: Substituir métodos em tipos comparáveisCA1036: Override methods on comparable types Um público ou um tipo protegido implementa a interface System.IComparable.A public or protected type implements the System.IComparable interface. Ele não substitui Object.Equals nem sobrecarrega o operador específico da linguagem para igualdade, desigualdade, menor que ou maior que.It does not override Object.Equals nor does it overload the language-specific operator for equality, inequality, less than, or greater than.
CA1040: Evitar interfaces vaziasCA1040: Avoid empty interfaces As interfaces definem os membros que fornecem um contrato de comportamento ou de uso.Interfaces define members that provide a behavior or usage contract. A funcionalidade descrita pela interface pode ser adotada por qualquer tipo, independentemente de onde o tipo seja exibido na hierarquia de herança.The functionality that is described by the interface can be adopted by any type, regardless of where the type appears in the inheritance hierarchy. Um tipo implementa uma interface fornecendo implementações para os membros da interface.A type implements an interface by providing implementations for the members of the interface. Uma interface vazia não define membros; por isso, ela não define um contrato que pode ser implementado.An empty interface does not define any members; therefore, it does not define a contract that can be implemented.
CA1041: Fornecer a mensagem ObsoleteAttributeCA1041: Provide ObsoleteAttribute message Um tipo ou um membro é marcado usando-se um atributo System.ObsoleteAttribute que não tem sua propriedade ObsoleteAttribute.Message especificada.A type or member is marked by using a System.ObsoleteAttribute attribute that does not have its ObsoleteAttribute.Message property specified. Quando um tipo ou membro que é marcado usando ObsoleteAttribute é compilado, a propriedade Message do atributo é exibida, o que fornece as informações do usuário sobre o tipo ou o membro obsoleto.When a type or member that is marked by using ObsoleteAttribute is compiled, the Message property of the attribute is displayed, which gives the user information about the obsolete type or member.
CA1043: Usar argumento integral ou de cadeia de caracteres para indexadoresCA1043: Use integral or string argument for indexers Os indicadores (ou seja, propriedades indexadas) devem usar tipos integrais ou de cadeia de caracteres no índice.Indexers (that is, indexed properties) should use integral or string types for the index. Esses tipos normalmente são usados na indexação de estruturas de dados e aumentam a usabilidade da biblioteca.These types are typically used for indexing data structures and they increase the usability of the library. 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.Use of the Object type should be restricted to those cases where the specific integral or string type cannot be specified at design time.
CA1044: Propriedades não devem ser somente gravaçãoCA1044: Properties should not be write only 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.Although it is acceptable and often necessary to have a read-only property, the design guidelines prohibit the use of write-only properties. 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.This is because letting a user set a value, and then preventing the user from viewing that value, does not provide any security. Além disso, sem acesso de leitura, o estado de objetos compartilhados não pode ser exibido, o que limita sua utilidade.Also, without read access, the state of shared objects cannot be viewed, which limits their usefulness.
CA1045: Não passar tipos por referênciaCA1045: Do not pass types by reference 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.Passing types by reference (using out or ref) requires experience with pointers, understanding how value types and reference types differ, and handling methods with multiple return values. Os arquitetos de bibliotecas que projetam para um público em geral não devem esperar que os usuários dominem o trabalho com parâmetros out ou ref.Library architects who design for a general audience should not expect users to master working with out or ref parameters.
CA1046: Não sobrecarregar o operador equals em tipos de referênciaCA1046: Do not overload operator equals on reference types Para tipos de referência, a implementação padrão do operador de igualdade está quase sempre correta.For reference types, the default implementation of the equality operator is almost always correct. Por padrão, duas referências só serão iguais se apontarem para o mesmo objeto.By default, two references are equal only if they point to the same object.
CA1047: Não declarar membros protegidos em tipos seladosCA1047: Do not declare protected members in sealed types Os tipos declaram membros protegidos de forma que a herança de tipos possa acessar ou substituir o membro.Types declare protected members so that inheriting types can access or override the member. 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.By definition, sealed types cannot be inherited, which means that protected methods on sealed types cannot be called.
CA1050: Declarar tipos em namespacesCA1050: Declare types in 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.Types are declared in namespaces to prevent name collisions and as a way to organize related types in an object hierarchy.
CA1051: Não declarar campos de instância visíveisCA1051: Do not declare visible instance fields O principal uso de um campo deve ser um como um detalhe da implementação.The primary use of a field should be as an implementation detail. Os campos devem ser privados ou internos e devem ser expostos usando-se propriedades.Fields should be private or internal and should be exposed by using properties.
CA1052: Tipos de suporte estático devem ser seladosCA1052: Static holder types should be sealed Um tipo público ou protegido contém apenas membros estáticos e não é declarado usando o modificador lacrado (C#) ou NotInheritable (Visual Basic).A public or protected type contains only static members and is not declared by using the sealed (C#) or NotInheritable (Visual Basic) modifier. 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.A type that is not meant to be inherited should be marked by using the sealed modifier to prevent its use as a base type.
CA1053: Tipos de suporte estático não devem ter construtoresCA1053: Static holder types should not have constructors Um tipo público ou público aninhado declara apenas membros estáticos e tem um construtor padrão público ou protegido.A public or nested public type declares only static members and has a public or protected default constructor. O construtor é desnecessário porque chamar membros estáticos não exige uma instância do tipo.The constructor is unnecessary because calling static members does not require an instance of the type. 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.The string overload should call the uniform resource identifier (URI) overload by using the string argument for safety and security.
CA1054: Parâmetros de URI não devem ser cadeias de caracteresCA1054: URI parameters should not be strings 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.If a method takes a string representation of a URI, a corresponding overload should be provided that takes an instance of the URI class, which provides these services in a safe and secure manner.
CA1055: Valores de retorno de URI não devem ser cadeias de caracteresCA1055: URI return values should not be strings Esta regra pressupõe que o método retorne um URI.This rule assumes that the method returns a 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 string representation of a URI is prone to parsing and encoding errors, and can lead to security vulnerabilities. A classe System.Uri fornece esses serviços de maneira segura.The System.Uri class provides these services in a safe and secure manner.
CA1056: Propriedades de URI não devem ser cadeias de caracteresCA1056: URI properties should not be strings Essa regra pressupõe que a propriedade representa um URI.This rule assumes that the property represents a 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 string representation of a URI is prone to parsing and encoding errors, and can lead to security vulnerabilities. A classe System.Uri fornece esses serviços de maneira segura.The System.Uri class provides these services in a safe and secure manner.
CA1058: Tipos não devem estender determinados tipos baseCA1058: Types should not extend certain base types Um tipo visível externamente estende determinados tipos de base.An externally visible type extends certain base types. Use uma das alternativas.Use one of the alternatives.
CA1060: mover P/Invokes para a classe NativeMethodsCA1060: Move P/Invokes to NativeMethods class Os métodos de invocação de plataforma, como aqueles marcados com os System.Runtime.InteropServices.DllImportAttribute métodos ou definidos usando a palavra-chave declare no Visual Basic, acessam o código não gerenciado.Platform Invocation methods, such as those marked with the System.Runtime.InteropServices.DllImportAttribute or methods defined by using the Declare keyword in Visual Basic, access unmanaged code. Esses métodos devem ser da classe NativeMethods, SafeNativeMethods ou UnsafeNativeMethods.These methods should be of the NativeMethods, SafeNativeMethods, or UnsafeNativeMethods class.
CA1061: Não ocultar métodos de classe baseCA1061: Do not hide base class methods 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.A method in a base type is hidden by an identically named method in a derived type, when the parameter signature of the derived method differs only by types that are more weakly derived than the corresponding types in the parameter signature of the base method.
CA1062: Validar argumentos de métodos públicosCA1062: Validate arguments of public methods Todos os argumentos de referência passados para os métodos visíveis externamente devem ser verificados em relação que serão nulos.All reference arguments that are passed to externally visible methods should be checked against null.
CA1063: Implementar IDisposable corretamenteCA1063: Implement IDisposable correctly Todos os tipos IDisposable devem implementar o padrão Dispose corretamente.All IDisposable types should implement the Dispose pattern correctly.
CA1064: Exceções devem ser públicasCA1064: Exceptions should be public Uma exceção interna só permanece visível dentro do próprio escopo interno.An internal exception is visible only inside its own internal scope. Depois que a exceção falha fora do escopo interno, somente a exceção de base pode ser usada para capturar a exceção.After the exception falls outside the internal scope, only the base exception can be used to catch the exception. 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.If the internal exception is inherited from System.Exception, System.SystemException, or System.ApplicationException, the external code will not have sufficient information to know what to do with the exception.
CA1065: Não acionar exceções em locais inesperadosCA1065: Do not raise exceptions in unexpected locations Um método que não deve acionar exceções aciona uma exceção.A method that is not expected to throw exceptions throws an exception.
CA1066: Implementar IEquatable ao substituir EqualsCA1066: Implement IEquatable when overriding Equals Um tipo de valor substitui o Equals método, mas não IEquatable<T> implementa.A value type overrides Equals method, but does not implement IEquatable<T>.
CA1067: Substituir Equals ao implementar IEquatableCA1067: Override Equals when implementing IEquatable Um tipo implementa IEquatable<T> , mas não substitui o Equals método.A type implements IEquatable<T>, but does not override Equals method.
CA1068: Os parâmetros CancellationToken devem vir por últimoCA1068: CancellationToken parameters must come last Um método tem um parâmetro CancellationToken que não é o último parâmetro.A method has a CancellationToken parameter that is not the last parameter.
CA1069: Enumerações não devem ter valores duplicadosCA1069: Enums should not have duplicate values Uma enumeração tem vários membros que são atribuídos explicitamente ao mesmo valor de constante.An enumeration has multiple members which are explicitly assigned the same constant value.
CA1070: Não declarar os campos de evento como virtuaisCA1070: Do not declare event fields as virtual Um evento do tipo campo foi declarado como virtual.A field-like event was declared as virtual.