Design Warnings
Note
This article applies to Visual Studio 2015. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here
Design warnings support adherence to the .NET Framework Design Guidelines.
In This Section
| 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. |
| CA1001: Types that own disposable fields should be disposable | A class declares and implements an instance field that is a System.IDisposable type and the class does not implement IDisposable. A class that declares an IDisposable field indirectly owns an unmanaged resource and should implement the IDisposable interface. |
| CA1002: Do not expose generic lists | System.Collections.Generic.List<(Of <(T>)>) is a generic collection that is 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 that is 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 you use inference for all type parameters, the syntax for calling generic and nongeneric 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 more than two type parameters exist, 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 are 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 uninitialized enumeration, just as other value types, is zero. 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. 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. |
| CA1009: Declare event handlers correctly | Event handler methods take two parameters. The first is of type System.Object and is named "sender". This is the object that raised the event. The second parameter is of type System.EventArgs and is named "e". This is the data that is associated with the event. Event handler methods should not return a value; in the C# programming language, this is indicated by the return type void. |
| 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 that is derived from the base type can be passed as the corresponding argument to the method. If the additional functionality that is provided by the derived parameter type is not required, use of the base type enables wider use of the method. |
| CA1012: Abstract types should not have constructors | Constructors on abstract types can be called only by derived types. 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. |
| 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 will be used across programming languages. Good design dictates that all assemblies explicitly indicate CLS compliance by using CLSCompliantAttribute. If this attribute is not present on an assembly, the assembly is not compliant. |
| CA1016: Mark assemblies with AssemblyVersionAttribute | The .NET Framework uses the version number to uniquely identify an assembly, and to bind to types in strongly named assemblies. The version number is used together with version and publisher policy. By default, applications run only with the assembly version with which they were built. |
| 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 you define a custom attribute, mark it by using AttributeUsageAttribute to indicate where in the source code the custom attribute can be applied. The meaning and intended usage of an attribute 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. |
| CA1020: Avoid namespaces with few types | Make sure that each of your namespaces has a logical organization, and that you have a valid reason to put types in a sparsely populated namespace. |
| CA1021: Avoid out parameters | 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. Also, the difference between out and ref parameters is not widely understood. |
| 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 to become 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 CLS; however, the CLS lets compilers ignore the values that are assigned to these parameters. To maintain the behavior that you want across programming languages, methods that use default parameters should be replaced by 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 rethrow 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. |
| CA1033: Interface methods should be callable by child types | 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: Nested types should not be visible | A nested type is a type that is declared in the scope of another type. Nested types are useful to encapsulate 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 that is 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 that is 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 that is provided by the interface. |
| CA1040: Avoid empty interfaces | Interfaces define members that provide a behavior or usage contract. The functionality that is described by the interface can be adopted by any type, regardless of where the type appears in the inheritance hierarchy. A type implements an interface by providing implementations for the members of the interface. An empty interface does not define any members; therefore, it does not define a contract that can be implemented. |
| CA1041: Provide ObsoleteAttribute message | A type or member is marked by using a System.ObsoleteAttribute attribute that does not have its ObsoleteAttribute.Message property specified. 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: 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 | Although it is acceptable and often necessary to have a read-only property, the design guidelines prohibit the use of write-only properties. This is because letting a user 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. |
| CA1045: Do not pass types by reference | 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. Library architects who design for a general audience should not expect users to master working with out or ref parameters. |
| 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 cannot 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. |
| CA1049: Types that own native resources should be disposable | Types that allocate unmanaged resources should implement IDisposable to enable callers to release those resources on demand and to shorten the lifetimes of the objects that hold the resources. |
| CA1050: Declare types in namespaces | Types are declared in 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 by using the sealed (C#) or NotInheritable (Visual Basic) modifier. 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: 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 uniform resource identifier (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 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 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 by using the suggested interface. |
| CA1060: Move P/Invokes to NativeMethods class | 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. These methods should be of the NativeMethods, SafeNativeMethods, or UnsafeNativeMethods class. |
| CA1061: Do not hide base class methods | 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: Validate arguments of public methods | All reference arguments that are passed to externally visible methods should be checked against null. |
| CA1063: Implement IDisposable correctly | All IDisposable types should implement the Dispose pattern correctly. |
| CA1064: Exceptions should be public | An internal exception is visible only 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 System.Exception, System.SystemException, or System.ApplicationException, the external code will not have sufficient information to know what to do with the exception. |
| CA1065: Do not raise exceptions in unexpected locations | A method that is not expected to throw exceptions throws an exception. |
| CA2210: Assemblies should have valid strong names | The strong name protects clients from unknowingly loading an assembly that has been tampered with. Assemblies without strong names should not be deployed outside very limited scenarios. If you share or distribute assemblies that are not correctly signed, the assembly can be tampered with, the common language runtime might not load the assembly, or the user might have to disable verification on his or her computer. |