Microsoft Basic Design Guideline Rules Code Analysis Rule Set

You can use the Microsoft Basic Design Guideline Rules rule set to focus on making your code easier to understand and use. You should include this rule set if your project includes library code or if you want to enforce best practices for code that is easy to maintain.

The Basic Design Guideline Rules include all the rules in the Microsoft Minimum Recommeded Rules rule set. For a list of the minimum rules, see Microsoft Minimum Recommended Rules Code Analysis Rule Set.

The following table describes all of the rules in the Microsoft Basic Design Guideline Rules rule set.

Rule

Description

CA1000: Do not declare static members on generic types

When a static member of a generic type is called, the type argument must be specified for the type. When a generic instance member that does not support inference is called, the type argument must be specified for the member. In these two cases, the syntax for specifying the type argument is different and easily confused.

CA1002: Do not expose generic lists

System.Collections.Generic.List<(Of <(T>)>) is a generic collection designed for performance, not inheritance. Therefore, List does not contain any virtual members. The generic collections that are designed for inheritance should be exposed instead.

CA1003: Use generic event handler instances

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.

CA1004: Generic methods should provide type parameter

Inference is how the type argument of a generic method is determined by the type of argument passed to the method, instead of by the explicit specification of the type argument. To enable inference, the parameter signature of a generic method must include a parameter that is of the same type as the type parameter for the method. In this case, the type argument does not have to be specified. When using inference for all type parameters, the syntax for calling generic and non-generic instance methods is identical; this simplifies the usability of generic methods.

CA1005: Avoid excessive parameters on generic types

The more type parameters a generic type contains, the more difficult it is to know and remember what each type parameter represents. 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>. However, if there are more than two type parameters, the difficulty becomes too great for most users.

CA1006: Do not nest generic types in member signatures

A nested type argument is a type argument that is also a generic type. To call a member whose signature contains a nested type argument, the user must instantiate one generic type and pass this type to the constructor of a second generic type. The required procedure and syntax is complex and should be avoided.

CA1007: Use generics where appropriate

An externally visible method contains a reference parameter of type System.Object. Use of a generic method enables all types, subject to constraints, to be passed to the method without first casting the type to the reference parameter type.

CA1008: Enums should have zero value

The default value of an un-initialized enumeration, just as other value types, is zero. A non-flags attributed enumeration should define a member with the value of zero so that the default value is a valid value of the enumeration. 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: Collections should implement generic interface

To broaden the usability of a collection, implement one of the generic collection interfaces. Then the collection can be used to populate generic collection types.

CA1011: Consider passing base types as parameters

When a base type is specified as a parameter in a method declaration, any type derived from the base type can be passed as the corresponding argument to the method. If the additional functionality provided by the derived parameter type is not required, use of the base type enables the method to be more widely used.

CA1012: Abstract types should not have constructors

Constructors on abstract types can only be called by derived types. Because public constructors create instances of a type, and you cannot create instances of an abstract type, an abstract type with a public constructor is incorrectly designed.

CA1013: Overload operator equals on overloading add and subtract

A public or protected type implements the addition or subtraction operators without implementing the equality operator.

CA1014: Mark assemblies with CLSCompliantAttribute

The Common Language Specification (CLS) defines naming restrictions, data types, and rules to which assemblies must conform if they are to be used across programming languages. Good design dictates that all assemblies explicitly indicate CLS compliance with CLSCompliantAttribute. If this attribute is not present on an assembly, the assembly is not compliant.

CA1017: Mark assemblies with ComVisibleAttribute

ComVisibleAttribute determines how COM clients access managed code. Good design dictates that assemblies explicitly indicate COM visibility. COM visibility can be set for the whole assembly and then overridden for individual types and type members. If this attribute is not present, the contents of the assembly are visible to COM clients.

CA1018: Mark attributes with AttributeUsageAttribute

When defining a custom attribute, mark it by using AttributeUsageAttribute to indicate where in the source code the custom attribute can be applied. An attribute's meaning and intended usage will determine its valid locations in code.

CA1019: Define accessors for attribute arguments

Attributes can define mandatory arguments that must be specified when you apply the attribute to a target. These are also known as positional arguments because they are supplied to attribute constructors as positional parameters. 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. Attributes can also define optional arguments, which are also known as named arguments. These arguments are supplied to attribute constructors by name and should have a corresponding read/write property.

CA1023: Indexers should not be multidimensional

Indexers (that is, indexed properties) should use a single index. Multidimensional indexers can significantly reduce the usability of the library.

CA1024: Use properties where appropriate

A public or protected method has a name that starts with "Get", takes no parameters, and returns a value that is not an array. The method might be a good candidate for becoming a property.

CA1025: Replace repetitive arguments with params array

Use a parameter array instead of repeated arguments when the exact number of arguments is unknown and when the variable arguments are the same type or can be passed as the same type.

CA1026: Default parameters should not be used

Methods that use default parameters are allowed under the Common Language Specification (CLS); however, the CLS allows compilers to ignore the values assigned to these parameters. To maintain the behavior that you want across programming languages, methods that use default parameters should be replaced with method overloads that provide the default parameters.

CA1027: Mark enums with FlagsAttribute

An enumeration is a value type that defines a set of related named constants. Apply FlagsAttribute to an enumeration when its named constants can be meaningfully combined.

CA1028: Enum storage should be Int32

An enumeration is a value type that defines a set of related named constants. By default, the System.Int32 data type is used to store the constant value. Even though you can change this underlying type, it is not required or recommended for most scenarios.

CA1030: Use events where appropriate

This rule detects methods that have names that ordinarily would be used for events. If a method is called in response to a clearly defined state change, the method should be invoked by an event handler. Objects that call the method should raise events instead of calling the method directly.

CA1031: Do not catch general exception types

General exceptions should not be caught. Catch a more-specific exception, or re-throw the general exception as the last statement in the catch block.

CA1032: Implement standard exception constructors

Failure to provide the full set of constructors can make it difficult to correctly handle exceptions.

CA1034: Nested types should not be visible

A nested type is a type declared in the scope of another type. Nested types are useful for encapsulating private implementation details of the containing type. Used for this purpose, nested types should not be externally visible.

CA1035: ICollection implementations have strongly typed members

This rule requires ICollection implementations to provide strongly typed members so that users are not required to cast arguments to the Object type when they use the functionality provided by the interface. This rule assumes that the type that implements ICollection does so to manage a collection of instances of a type that is stronger than Object.

CA1036: Override methods on comparable types

A public or protected type implements the System.IComparable interface. It does not override Object.Equals nor does it overload the language-specific operator for equality, inequality, less than, or greater than.

CA1038: Enumerators should be strongly typed

This rule requires IEnumerator implementations to also provide a strongly typed version of the Current property so that users are not required to cast the return value to the strong type when they use the functionality provided by the interface.

CA1039: Lists are strongly typed

This rule requires IList implementations to provide strongly typed members so that users are not required to cast arguments to the System.Object type when they use the functionality provided by the interface.

CA1041: Provide ObsoleteAttribute message

A type or member is marked with a System.ObsoleteAttribute attribute that does not have its ObsoleteAttribute.Message property specified. When a type or member marked with ObsoleteAttribute is compiled, the Message property of the attribute is displayed, giving the user information about the obsolete type or member.

CA1043: Use integral or string argument for indexers

Indexers (that is, indexed properties) should use integral or string types for the index. These types are typically used for indexing data structures and they increase the usability of the library. 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: Properties should not be write only

While it is acceptable and often necessary to have a read-only property, the design guidelines prohibit using write-only properties because allowing a user to set a value, and then preventing the user from viewing that value, does not provide any security. Also, without read access, the state of shared objects cannot be viewed, which limits their usefulness.

CA1046: Do not overload operator equals on reference types

For reference types, the default implementation of the equality operator is almost always correct. By default, two references are equal only if they point to the same object.

CA1047: Do not declare protected members in sealed types

Types declare protected members so that inheriting types can access or override the member. By definition, sealed types can not be inherited, which means that protected methods on sealed types cannot be called.

CA1048: Do not declare virtual members in sealed types

Types declare methods as virtual so that inheriting types can override the implementation of the virtual method. By definition, a sealed type cannot be inherited. This makes a virtual method on a sealed type meaningless.

CA1050: Declare types in namespaces

Types are declared within namespaces to prevent name collisions, and as a way to organize related types in an object hierarchy.

CA1051: Do not declare visible instance fields

The primary use of a field should be as an implementation detail. Fields should be private or internal and should be exposed by using properties.

CA1052: Static holder types should be sealed

A public or protected type contains only static members and is not declared with the sealed (C# Reference) (NotInheritable) modifier. A type that is not meant to be inherited should be marked with the sealed modifier to prevent its use as a base type.

CA1053: Static holder types should not have constructors

A public or nested public type declares only static members and has a public or protected default constructor. The constructor is unnecessary because calling static members does not require an instance of the type. The string overload should call the URI overload by using the string argument for safety and security.

CA1054: URI parameters should not be strings

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: URI return values should not be strings

This rule assumes that the method returns a Uniform Resource Identifier (URI). A string representation of a URI is prone to parsing and encoding errors, and can lead to security vulnerabilities. The System.Uri class provides these services in a safe and secure manner.

CA1056: URI properties should not be strings

This rule assumes that the property represents a Uniform Resource Identifier (URI). A string representation of a URI is prone to parsing and encoding errors, and can lead to security vulnerabilities. The System.Uri class provides these services in a safe and secure manner.

CA1057: String URI overloads call System.Uri overloads

A type declares method overloads that differ only by the replacement of a string parameter with a System.Uri parameter. The overload that takes the string parameter does not call the overload that takes the URI parameter.

CA1058: Types should not extend certain base types

An externally visible type extends certain base types. Use one of the alternatives.

CA1059: Members should not expose certain concrete types

A concrete type is a type that has a complete implementation and therefore can be instantiated. To enable widespread use of the member, replace the concrete type with the suggested interface.

CA1064: Exceptions should be public

An internal exception is only visible inside its own internal scope. After the exception falls outside the internal scope, only the base exception can be used to catch the exception. If the internal exception is inherited from T:System.Exception, T:System.SystemException, or T:System.ApplicationException, the external code will not have sufficient information to know what to do with the exception.

CA1500: Variable names should not match field names

An instance method declares a parameter or a local variable whose name matches an instance field of the declaring type, leading to errors.

CA1502: Avoid excessive complexity

This rule measures the number of linearly independent paths through the method, which is determined by the number and complexity of conditional branches.

CA1708: Identifiers should differ by more than case

Identifiers for namespaces, types, members, and parameters cannot differ only by case because languages that target the common language runtime are not required to be case-sensitive.

CA1716: Identifiers should not match keywords

A namespace name or a type name matches a reserved keyword in a programming language. Identifiers for namespaces and types should not match keywords defined by languages that target the common language runtime.

CA1801: Review unused parameters

A method signature includes a parameter that is not used in the method body.

CA1804: Remove unused locals

Unused local variables and unnecessary assignments increase the size of an assembly and decrease performance.

CA1809: Avoid excessive locals

A common performance optimization is to store a value in a processor register instead of memory, which is referred to as "enregistering the value". To increase the possibility that all local variables are enregistered, limit the number of local variables to 64.

CA1810: Initialize reference type static fields inline

When a type declares an explicit static constructor, the just-in-time (JIT) compiler adds a check to each static method and instance constructor of the type, to make sure that the static constructor was previously called. Static constructor checks can decrease performance.

CA1811: Avoid uncalled private code

A private or internal (assembly-level) member does not have callers in the assembly, it is not invoked by the common language runtime, and it is not invoked by a delegate.

CA1812: Avoid uninstantiated internal classes

An instance of an assembly-level type is not created by code in the assembly.

CA1813: Avoid unsealed attributes

The .NET Framework class library provides methods for retrieving custom attributes. By default, these methods search the attribute inheritance hierarchy. Sealing the attribute eliminates the search through the inheritance hierarchy and can improve performance.

CA1814: Prefer jagged arrays over multidimensional

A jagged array is an array whose elements are arrays. The arrays that make up the elements can be of different sizes, leading to less wasted space for some sets of data.

CA1815: Override equals and operator equals on value types

For value types, the inherited implementation of Equals uses the Reflection library and compares the contents of all fields. Reflection is computationally expensive, and comparing every field for equality might be unnecessary. If you expect users to compare or sort instances, or use instances as hash table keys, your value type should implement Equals.

CA1819: Properties should not return arrays

Arrays returned by properties are not write-protected, even if the property is read-only. To keep the array tamper-proof, the property must return a copy of the array. Typically, users will not understand the adverse performance implications of calling such a property.

CA1820: Test for empty strings using string length

Comparing strings by using the String.Length property or the String.IsNullOrEmpty method is significantly faster than using Equals.

CA1821: Remove empty finalizers

Whenever you can, avoid finalizers because of the additional performance overhead involved in tracking object lifetime. An empty finalizer incurs added overhead without any benefit.

CA1822: Mark members as static

Members that do not access instance data or call instance methods can be marked as static (Shared in Visual Basic). After you mark the methods as static, the compiler will emit non-virtual call sites to these members. This can give you a measurable performance gain for performance-sensitive code.

CA1823: Avoid unused private fields

Private fields were detected that do not appear to be accessed in the assembly.

CA2201: Do not raise reserved exception types

This makes the original error hard to detect and debug.

CA2205: Use managed equivalents of Win32 API

A platform invoke method is defined and a method with the equivalent functionality exists in the .NET Framework class library.

CA2208: Instantiate argument exceptions correctly

A call is made to the default (parameterless) constructor of an exception type that is or derives from ArgumentException, or an incorrect string argument is passed to a parameterized constructor of an exception type that is or derives from ArgumentException.

CA2211: Non-constant fields should not be visible

Static fields that are neither constants nor read-only are not thread-safe. Access to such a field must be carefully controlled and requires advanced programming techniques for synchronizing access to the class object.

CA2217: Do not mark enums with FlagsAttribute

An externally visible enumeration is marked with FlagsAttribute, and it has one or more values that are not powers of two or a combination of the other defined values on the enumeration.

CA2219: Do not raise exceptions in exception clauses

When an exception is raised in a finally or fault clause, the new exception hides the active exception. When an exception is raised in a filter clause, the run time silently catches the exception. This makes the original error hard to detect and debug.

CA2221: Finalizers should be protected

Finalizers must use the family access modifier.

CA2222: Do not decrease inherited member visibility

You should not change the access modifier for inherited members. Changing an inherited member to private does not prevent callers from accessing the base class implementation of the method.

CA2223: Members should differ by more than return type

Although the common language runtime allows the use of return types to differentiate between otherwise identical members, this feature is not in the Common Language Specification, nor is it a common feature of .NET programming languages.

CA2224: Override equals on overloading operator equals

A public type implements the equality operator, but does not override Object.Equals.

CA2225: Operator overloads have named alternates

An operator overload was detected, and the expected named alternative method was not found. The named alternative member provides access to the same functionality as the operator, and is provided for developers who program in languages that do not support overloaded operators.

CA2226: Operators should have symmetrical overloads

A type implements the equality or inequality operator, and does not implement the opposite operator.

CA2227: Collection properties should be read only

A writable collection property allows a user to replace the collection with a different collection. A read-only property stops the collection from being replaced but still allows the individual members to be set.

CA2230: Use params for variable arguments

A public or protected type contains a public or protected method that uses the VarArgs calling convention instead of the params keyword.

CA2231: Overload operator equals on overriding ValueType.Equals

A value type overrides Object.Equals but does not implement the equality operator.

CA2234: Pass System.Uri objects instead of strings

A call is made to a method that has a string parameter whose name contains "uri", "URI", "urn", "URN", "url", or "URL". The declaring type of the method contains a corresponding method overload that has a System.Uri parameter.

CA2239: Provide deserialization methods for optional fields

A type has a field that is marked with the System.Runtime.Serialization.OptionalFieldAttribute attribute, and the type does not provide de-serialization event handling methods.