In most programming languages, some information is expressed through declaration, and other information is expressed through code. For example, in the following class member declaration

public int Test;

the compiler and runtime will reserve space for an integer variable and set its accessibility so that it is visible everywhere. This is an example of declarative information; it’s nice because of the economy of expression and because the compiler handles the details for you.

Typically, the types of declarative information that can be used are predefined by the language designer and can’t be extended by users of the language. A user who wants to associate a specific database field with a field of a class, for example, must invent a way of expressing that relationship in the language, a way of storing the relationship, and a way of accessing the information at runtime. In a language like C++, a macro might be defined that stores the information in a field that is part of the object. Such schemes work, but they’re error-prone and not generalized. They’re also ugly.

The .NET Runtime supports attributes, which are merely annotations that are placed on elements of source code, such as classes, members, parameters, and so on. Attributes can be used to change the behavior of the runtime, provide transaction information about an object, or convey organizational information to a designer. The attribute information is stored with the metadata of the element and can be easily retrieved at runtime through a process known as reflection.

C# uses a conditional attribute to control when member functions are called. A usage of the conditional attribute would look like this:

using System.Diagnostics;
class Test
{
    [Conditional("DEBUG")]
    public void Validate()
    {
    }
}

While it is possible to write your own custom attributes, most programmers will use predefined attributes much more often than writing their own.

Using Attributes

Suppose it was important to keep track of the code reviews that had been performed on classes so that you could determine when code reviews were finished. The code review information could be stored in a database, which would allow easy queries about status, or it could be stored in comments, which would make it easy to look at the code and the information at the same time.

Or an attribute could be used, which would enable both kinds of access.

To do that, an attribute class is needed. An attribute class defines the name of an attribute, how it can be created, and the information that will be stored. The gritty details of defining attribute classes will be covered in the section “An Attribute of Your Own.”

The attribute class will look like this:

using System;
[AttributeUsage(AttributeTargets.Class)]
public class CodeReviewAttribute: System.Attribute
{
    public CodeReviewAttribute(string reviewer, string date)
    {
       m_reviewer = reviewer;
       m_date = date;
    }
    public string Comment
    {
       get { return(m_comment); }
       set { m_comment = value; }
    }
    public string Date
    {
       get { return(m_date); }
    }
    public string Reviewer
    {
       get { return(m_reviewer); }
    }
    string m_reviewer;
    string m_date;
    string m_comment;
}
[CodeReview("Eric", "01-12-2000", Comment = "Bitchin' Code")]
class Complex
{
}

The AttributeUsage attribute before the class specifies that this attribute can be placed only on classes. When an attribute is used on a program element, the compiler checks to see whether the use of that attribute on that program element is allowed.

The naming convention for attributes is to append Attribute to the end of the class name. This makes it easier to tell which classes are attribute classes and which classes are normal classes. All attributes must derive from System.Attribute.

The class defines a single constructor that takes a reviewer and a date as parameters, and it also has the public string property Comment.

When the compiler comes to the attribute use on class Complex, it first looks for a class derived from Attribute named CodeReview. It doesn’t find one, so it next looks for a class named CodeReviewAttribute, which it finds.

Next, it checks to see whether the attribute is allowed for this usage (on a class).

Then, it checks to see whether there is a constructor that matches the parameters you’ve specified in the attribute use. If it finds one, an instance of the object is created—the constructor is called with the specified values.

If there are named parameters, it matches the name of the parameter with a field or property in the attribute class, and then it sets the field or property to the specified value.

After this is done, the current state of the attribute class is saved to the metadata for the program element for which it was specified.

At least, that’s what happens logically. In actuality, it only looks like it happens that way; see the “Attribute Pickling” sidebar for a description of how it is implemented.

using System.Runtime.InteropServices;
class Test
{
    [return: MarshalAs(UnmanagedType.LPWStr)]
    public static extern string GetMessage();
}

using System.Runtime.InteropServices;
class Test
{
    [return: MarshalAs(UnmanagedType.LPWStr)]
    public static extern string GetMessage();
}

using System;
[assembly:CLSCompliant(true)]
class Test
{
    Test() {}
}

An Attribute of Your Own

To define attribute classes and reflect on them at runtime, there are a few more issues to consider. This section will discuss some things to consider when designing an attribute.

There are two major things to determine when writing an attribute. The first is the program elements that the attribute may be applied to, and the second is the information that will be stored by the attribute.

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Event, AllowMultiple = true)]

Fetching Attribute Values

Once attributes are defined on some code, it’s useful to be able to find the attribute values. This is done through reflection.

The following code shows an attribute class, the application of the attribute to a class, and the reflection on the class to retrieve the attribute:

using System;
using System.Reflection;
[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
public class CodeReviewAttribute: System.Attribute
{
    public CodeReviewAttribute(string reviewer, string date)
    {
       m_reviewer = reviewer;
       m_date = date;
    }
    public string Comment
    {
       get { return(m_comment); }
       set { m_comment = value; }
    }
    public string Date
    {
       get { return(m_date); }
    }
    public string Reviewer
    {
       get { return(m_reviewer); }
    }
    string m_reviewer;
    string m_date;
    string m_comment;
}
[CodeReview("Eric", "01-12-2000", Comment = "Bitchin' Code")]
[CodeReview("Gurn", "01-01-2000", Comment = "Revisit this section")]
class Complex
{
}
class Test
{
   public static void Main()
    {
       Type type = typeof(Complex);
       foreach (CodeReviewAttribute att in
                      type.GetCustomAttributes(typeof(CodeReviewAttribute), false))
       {
            Console.WriteLine("Reviewer: {0}", att.Reviewer);
            Console.WriteLine("Date: {0}", att.Date);
            Console.WriteLine("Comment: {0}", att.Comment);
       }
    }
}

The Main() function first gets the type object associated with the type Complex. It then iterates over all the CodeReviewAttribute attributes attached to the type and writes the values out.

Alternately, the code could get all the attributes by omitting the type in the call to GetCustomAttributes().

       foreach (object o in type.GetCustomAttributes(false))
       {
            CodeReviewAttribute att = o as CodeReviewAttribute;
            if (att != null)
            {
                // write values here...
            }
       }

This example produces the following output:

Reviewer: Eric
Date: 01-12-2000
Comment: Bitchin' Code
Reviewer: Gurn
Date: 01-01-2000
Comment: Revisit this section

The false value in the call to GetCustomAttributes tells the runtime to ignore any inherited attributes. In this case, that would ignore any attributes on the base class of Complex.

In the example, the type object for the Complex type is obtained using typeof. It can also be obtained in the following manner:

Complex c = new Complex();
Type t = c.GetType();
Type t2 = Type.GetType("Complex");

¹ The process is called pickling to differentiate it from serialization.