14.4 Predefined Attributes

The .NET Framework makes extensive use of attributes for purposes ranging from simple documentation to advanced support for threading, remoting, serialization, and COM interop. These attributes are all defined in the FCL, and can be used, extended, and retrieved by your own code.

However, certain attributes are treated specially by the compiler and the runtime. Three attributes considered general enough to be defined in the C# specification are AttributeUsage, Conditional, and Obsolete. Other attributes, such as CLSCompliant, Serializable, and NonSerialized, are also treated specially.

14.4.1 The AttributeUsage Attribute

[AttributeUsage(target-enum

   [, AllowMultiple=[true|false]]?
   [, Inherited=[true|false]]?
   ] (for classes)

The AttributeUsage attribute is applied to a new attribute class declaration. It controls how the new attribute should be treated by the compiler—specifically, which set of targets (classes, interfaces, properties, methods, parameters, etc.) the new attribute can be specified on. This is true whether multiple instances of this attribute may be applied to the same target, and whether this attribute propagates to subtypes of the target.

target-enum is a bitwise mask of values from the System.AttributeTargets enum, which looks like this:

namespace System {
  [Flags]
  public enum AttributeTargets {
    Assembly     = 0x0001,
    Module       = 0x0002,
    Class        = 0x0004,
    Struct       = 0x0008,
    Enum         = 0x0010,
    Constructor  = 0x0020,
    Method       = 0x0040,
    Property     = 0x0080,
    Field        = 0x0100,
    Event        = 0x0200,
    Interface    = 0x0400,
    Parameter    = 0x0800,
    Delegate     = 0x1000,
    ReturnValue  = 0x2000,
    All          = 0x3fff,
  }
}

14.4.2 The Conditional Attribute

[Conditional(symbol)] (for methods)

The Conditional attribute can be applied to any method with a void return type. The presence of this attribute tells the compiler to conditionally omit calls to the method unless symbol is defined in the calling code. This is similar to wrapping every call to the method with #if and #endif preprocessor directives, but Conditional has the advantage of needing to be specified only in one place.

14.4.3 The Obsolete Attribute

[Obsolete([Message=]? message
   IsError= [true|false]]
 ] (for all attribute targets)

Applied to any valid attribute target, the Obsolete attribute indicates that the target is obsolete. Obsolete can include a message that explains which alternative types or members to use and a flag that tells the compiler to treat the use of this type or member as an error instead of a warning.

For example, referencing type Bar in the following example causes the compiler to display an error message and halts compilation:

[Obsolete("Don't try this at home", IsError=true)]
class Bar { ... }

14.4.4 The CLSCompliant Attribute

[CLSCompliant(true|false)]
(for all attribute targets)

Applied to an assembly, the CLSCompliant attribute tells the compiler whether to validate CLS compliance for all the exported types in the assembly. Applied to any other attribute target, this attribute allows the target to declare if it should be considered CLS-compliant. In order to mark a target as CLS-compliant, the entire assembly needs to be considered as such.

In the following example, the CLSCompliant attribute is used to specify an assembly as CLS-compliant and a class within it as not CLS-compliant:

[assembly:CLSCompliant(true)]
  
[CLSCompliant(false)]
public class Bar { 
  public ushort Answer { get {return 42;} } 
}

14.4.5 The Serializable Attribute

[Serializable] 
(for classes, structs, enums, delegates)

Applied to a class, struct, enum, or delegate, the Serializable attribute marks it as being serializable. This attribute is a pseudocustom attribute and is represented specially in the metadata.

14.4.6 The NonSerialized attribute

[NonSerialized] (for fields)

Applied to a field, the NonSerialized attribute prevents it from being serialized along with its containing class or struct. This attribute is a pseudocustom attribute and is represented specially in the metadata.