Metadata (CLI) - Attributes

Developers can add metadata to their code through attributes. There are two types of attributes, custom and pseudo custom attributes, and to the developer these have the same syntax. Attributes in code are messages to the compiler to generate metadata. In CIL, metadata such as inheritance modifiers, scope modifiers, and almost anything that isn't either opcodes or streams, are also referred to as attributes.

A custom attribute is a regular class that inherits from the Attribute class. A custom attribute can be used on any method, property, class or entire assembly with the syntax: as in:

Custom attributes are used by CLI extensively. Windows Communication Framework uses attributes to define service contracts, ASP.NET uses these to expose methods as web services, LINQ to SQL uses them to define the mapping of classes to the underlying relational schema, Visual Studio uses them to group together properties of an object, the class developer indicates the category for the object's class by applying the custom attribute. Custom attributes are interpreted by application code and not the CLR. When the compiler sees a custom attribute it will generate custom metadata that is not recognised by the CLR. The developer has to provide code to read the metadata and act on it. As an example, the attribute shown in the example can be handled by the code:

class CustomAttribute : Attribute { private int paramNumber = 0; private string comment = ""; public CustomAttribute { } public CustomAttribute(int num) { paramNumber = num; } public String Comment { set { comment = value; } } }

The name of the class is mapped to the attribute name. The Visual C# compiler automatically adds the string "Attribute" at the end of any attribute name. Consequently every attribute class name should end with this string, but it is legal to define an attribute without the Attribute-suffix. When affixing an attribute to an item, the compiler will look for both the literal name and the name with Attribute added to the end, i.e. if you were to write the compiler would look for both Custom and CustomAttribute. If both exist, the compiler fails. The attribute can be prefixed with "@" if you don't want to risk ambiguity, so writing will not match CustomAttribute. Using the attribute invokes the constructor of the class. Overloaded constructors are supported. Name-Value pairs are mapped to properties, the name denotes the name of the property and the value supplied is set by the property.

Sometimes there is ambiguity concerning to what you are affixing the attribute. Consider the following code:

public int ExampleMethod(string input) { //method body goes here }

What has been marked as orange? Is it the ExampleMethod, its return value, or perhaps the entire assembly? In this case, the compiler will default, and treat the attribute as being affixed to the method. If this is not what was intended, or if the author wishes to clarify their code, an attribute target may be specified. Writing will mark the return value as orange, will mark the entire assembly. The valid targets are assembly, field, event, method, module, param, property, return and type.

A pseudo-custom attribute is used just like regular custom attributes but they do not have a custom handler; rather the compiler has intrinsic awareness of the attributes and handles the code marked with such attributes differently. Attributes such as Serializable and Obsolete are implemented as pseudo-custom attributes. Pseudo-custom attributes should never be used by ILASM, as it has adequate syntax to describe the metadata.