The complex, component-style development that businesses expect out of modern software developers requires greater design flexibility than the design methodologies of the past.

Microsoft's .NET Framework makes extensive use of attributes to provide added functionality through what is known as “declarative” programming. Attributes enhance flexibility in software systems because they promote loose coupling of functionality. Because you can create your own custom attribute classes and then act upon them, you can leverage the loose coupling power of attributes for your own purposes.

The .NET Framework makes many aspects of Windows programming much simpler. In many cases, the Framework's use of metadata that .NET compilers bind to assemblies at compile time makes tricky programming easier. Indeed, the use of intrinsic metadata makes it possible for .NET to relieve us from “DLL Hell.”

Lucky for us, the designers of the .NET framework did not choose to keep these metadata “goodies” hidden away under the covers. The designers gave us the Reflection API through which a .NET application can programmatically investigate this metadata. An application can “reflect” upon any imaginable aspect of a given assembly or on its contained types and their members.

Binding the metadata to the executable provides many advantages. It makes the assemblies in .NET fully self-describing. This allows developers to share components across languages and eliminates the need for header files. (They can become out-of-date relative to the implementation code.)

With all this positive news about .NET metadata it seems hard to believe there could be anything more to the story?but there is. You can create your own application-specific metadata in .NET and then use that metadata for any purpose you can imagine.

Developers define their own application-specific metadata through the use of Custom Attributes. Because these attribute values become just another part of the metadata bound into an assembly, the custom attribute values are available for examination by the Reflection API.

We commonly refer to properties of a class and their values as “attributes.” So what really is the difference between properties and custom attributes?

In this article, you'll learn how to define custom attribute classes, how to apply attributes to classes and methods in your source code, and you'll learn how to use the Reflection API to retrieve and act upon these values.

How Does .NET Use Attributes in the Common Language Runtime?

Before you start to consider what you can accomplish with your own custom attribute classes, let's examine some of the standard attributes that the Common Language Runtime already makes available.

The [WebService] attribute provides a simple example?it lets you turn any public method of a WebService subclass into a method that you can expose as part of the Web Service merely by attaching the [WebMethod] attribute to the method definition.

public class SomeWebService : 
   System.Web.Services.WebService 
{

   [WebMethod]
   public DataSet GetDailySales( ) 
   {
      // code to process the request...
   }
}

You simply attach the [WebMethod] attribute to the method and .NET handles everything else for you behind the scenes.

Using the [Conditional] attribute allows you to make a given method conditional based on the presence or absence of the specified preprocessing symbol. For example, the following code:

public class SomeClass
{
   [Conditional( "DEBUG" )]
   public void UnitTest( ) 
   {
      // code to do unit testing...
   }
}

indicates that the UnitTest( ) method of this class is “conditional” based on the presence of the preprocessing symbol “DEBUG”. The really interesting part is what actually happens. The compiler stubs out all calls to the method when the condition fails rather than attempt to nullify the behavior of the method the way an #if…#endif pre-processing directive does. This is a much cleaner approach, and again we didn't have to do much of anything to utilize this functionality.

Attributes utilize positional and/or named parameters. In the example using the [Conditional] attribute, the symbol specification is a positional parameter. You must always supply positional parameters.

To look at named parameters, let's return to the [WebMethod] attribute example. This attribute has a named parameter called Description. To use it you would change the line to read:

[WebMethod(
Description = "Sales volume" )]

Named parameters are optional and you write them using the name of the parameter followed by the assignment of a value. Named parameters follow after you've specified all positional parameters.

I will talk more about named and positional parameters later in this article when I show you how to create and apply your own Attribute class.

Run-Time, Design-Time

The examples I provide in this article are involved in run-time activities. But Binaries (assemblies) aren't just for run-time. In .NET, the metadata you describe isn't limited to being available only at runtime. You can query the metadata at any time after you've compiled an assembly.

Think about some design-time possibilities. The open nature of the IDE in Visual Studio.NET allows you to create tools (using .NET languages) that facilitate development and design (wizards, builders, etc.) Thus, one module's run-time environment (the IDE tool) is another module's design-time environment (the source code being developed). This presents a fine opportunity to implement some custom attributes. You could allow the IDE tool to reflect and then act upon the source classes/types you develop. Unfortunately, due to the additional subject of the IDE tool code, exploring such an example is beyond the scope of a single article.

The standard .NET attributes contain a similar example. When a developer creates custom controls to include in the Toolbox of the Visual Studio .NET IDE, they have attributes available to them to indicate how to handle the control in the property sheet. Table 1 lists and describes the four standard .NET attributes that the property sheet uses.

These property sheet-related attributes make it clear that you can use attributes and their values in the design-time as well as in the run-time environment.

Custom Attributes vs. Class Properties

Obvious similarities exist between attributes and regular member properties of a class. This can make it difficult to decide when and where you might want to utilize a custom attribute class. Developers commonly refer to properties of a class and their values as being “attributes” themselves, so what really is the difference between properties and attributes?

An attribute takes the same “shape and form” as a property when you define it, but you can attach it to all manner of different assembly level types?not just Classes. Table 2 lists all the assembly level types that you can apply attributes to.

Let's pick one item from the list as an example. You can apply an attribute to a parameter, which is a little bit like adding a property to a parameter?a very novel and powerful idea indeed, because you just can't do that with class member properties. This emphasizes the biggest way in which attributes and properties are different, because properties are simply always going to be members of a class?they can't be associated with a parameter or any number of other types listed in Table 2 other than Class.

Assemblies aren't just for run-time anymore?one module's run-time environment (IDE tool) is another module's design-time environment (source code being developed).

Member properties of a class are also limited in another way in which attributes are not. By definition, a member property is tied to a specific class. That member property can only ever be used through an instance or subclass instance of the class on which the property was defined. On the other hand, you can attach/apply attributes anywhere! The only requirement is that the assembly type the attribute is being attached to matches the validon definition in the custom attribute. I'll talk more about the validon property of custom attribute classes in the next section. This characteristic of attributes helps to promote the loose coupling that is so helpful in component-style development.

Another difference between properties and attributes relates to the values you can store in each of them. The values of member properties are instance values and can be changed at run-time. However, in the case of attributes, you set values at design time (in source code) and then compile the attributes (and their values) directly into the metadata contained in an assembly. After that point you cannot change the values of the attributes?you've essentially turned the values of the attributes into hard-coded, real-only data.

Consider this when you attach an attribute. If you attach an attribute to a class definition for example, every instance of the class will have the same values assigned to the attribute regardless of how many objects of this class type you instantiate. You cannot attach an attribute to an instance of a class. You may only attach an attribute to a Type/Class definition.

Creating a Custom Attribute Class

Now we'll create a more realistic implementation of the ideas presented above. Let's create a custom attribute class. This will allow us to store some tracking information about code modifications that you would typically record as comments in source code. For the example we'll record just a few items: defect id, developer id, the date of the change, the origin of the defect, and a comment about the fix. To keep the example simple we'll focus on creating a custom attribute class (DefectTrackAttribute) designated for use only with classes and methods.

Listing 1 shows the source code for the DefectTrackAttribute class. You can identify some important lines of code.

If you haven't used attributes before, the following line of code might look a bit strange.

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

This line attaches an [AttributeUsage] attribute to the attribute class definition. Square bracket syntax identifies the construct as an attribute. So, Attributes classes can have their own attributes. This may seem a bit confusing at first, but it should become clearer as I show you what you'll use it for.

The [AttributeUsage] attribute has one positional parameter and two named parameters. The positional parameter **validon **specifies which of the various assembly types you can attach this attribute to. The value for this parameter uses a combination of values from the AttributeTargets enumeration. In my example I allow only classes and methods so I get the proper specification by OR'ing the two AttributeTargets values together.

The first named parameter of the [AttributeUsage] attribute (and the only one specified in the example) is the AllowMultiple parameter, which indicates whether you can apply this type of attribute multiple times to the same type. The default value is false. However, you want to apply the AllowMultiple parameter of the Attribute more than once on a single type because that represents what the example will model. A given method or class potentially goes through many revisions during its lifetime and you need to be able to denote each of these changes with an individual [DefectTrack] attribute.

The second named parameter of the [AttributeUsage] attribute is the Inherited parameter, which indicates whether or not derived classes inherit the attribute. I've made the default value for this parameter false. I opted to take the default value so I did not specify this named parameter. Why? The source code modification information I want to capture is always related to each class and method individually. It would confuse the developer for a class to inherit the [DefectTrack] attribute(s) from its parent class?the developer couldn't distinguish which [DefectTrack] attributes came from the parent and which were specified directly.

Listing1 then lists the class declaration. Attribute classed are subclassed from System.Attribute. You will directly or indirectly subclass all custom Attribute classes from System.Attribute.

Next, Listing 1 shows that I've defined five private fields to hold the values for the attribute.

The first method in our Attribute class is the class constructor, which has a call signature with three parameters. The parameters of a constructor for an Attribute class represent the positional parameters for that attribute, which makes these required parameters. If you choose, you can create overloaded constructors and have more than one allowable positional / required parameter configuration.

The remainder of the Attribute class is a series of public property declarations that correspond to the private fields of the class. You'll use these properties to access the values of the attribute when you get to the example that examines the metadata. Note that the properties that correspond to the positional parameters only have a get clause and do not have a set clause. This makes these properties read-only and corresponds with the fact that these are meant to be positional and not named parameters.

Applying the Custom Attribute

You've already seen that you can attach an attribute to a target item in your C# code by putting the attribute name and its parameters in square brackets immediately before the item's declaration statement.

In Listing 2 you attach the [DefectTrack] attribute to a couple of methods and a couple of classes.

You need to ensure that you have access to the class definition for your custom attribute so you start by including this line.

using MyAttributeClasses ;

Beyond that you're simply “adorning” or “decorating” your class declarations and some of your methods with the [DefectTrack] custom attribute.

SomeCustomPricingClass has two uses of the [DefectTrack] attribute attached. The first [DefectTrack] attribute uses only the three positional parameters whereas the second [DefectTrack] attribute also includes a specification for the named parameter Origin.

[DefectTrack( "1377", "12/15/02", 
  "David Tansey" ) ]
[DefectTrack( "1363", "12/12/02", 
  "Toni Feltman", 
  Origin = 
    "Coding: Unhandled Exception")]
public class SomeCustomPricingClass 
{ ... }

The PriceIsValid( ) method also uses the [DefectTrack] custom attribute, and it includes a specification for both of the named parameters, Origin and FixComment. Listing 2 contains a couple of additional uses of the [DefectTrack] attribute that you can examine on you own.

Some readers might wonder if you could rely on the old fashioned approach of using comments for this sort of source modification information. .NET does make tools available for using XML blocks within comments to give them some structure and form.

You can easily see a comment in your source code right at the relevant place. You could process such information by text parsing the comments in the source, but its tedious and potentially error prone. .NET provides tools to process XML blocks in comments that practically eliminate this issue.

The open nature of custom attributes makes it likely that some of their most novel and powerful uses have yet to be conceived of.

Using a custom attribute for the same purpose also provides you a structured approach to recording and processing the information, but it has an added advantage. Consider that after you compile source code into a binary, you lose your comments?forever removed from the byproduct executable code. By comparison, the values of the attributes become a part of the metadata that you've forever bound to the assembly?you have still have access to the information even without any source code.

Additionally, the way an attribute “reads” in source code allows it to still fill the same valuable design-time function that the original comment did.

Retrieving the Values of the Custom Attributes

At this point, even though you've applied your custom attribute to some classes and methods, you haven't really seen it in action. It seems as if nothing really occurs whether you attach the attributes or not. But something does occur and you don't have to take my word for it. You can use the MSIL Disassembler to open an EXE or DLL that contains types you've decorated with your custom attributes. The MSIL Disassembler lets you see that .NET included your attributes and their values right there in the IL code. Figure 1 shows an example of ILDASM form with the EXE from the sample code in this article opened.

Figure 1: C# attributes.

Despite seeing the attribute values in the disassembly as proof of their existence, you still haven't seen any action related to them. Now you'll use the Reflection API to traverse the types/objects of an assembly, query for your custom attribute, and retrieve the attribute values when you find types that have your custom attribute attached to them.

Consider the general structure and intent of the test program in Listing 3. The program loads the specified assembly, gets an array of all members of the assembly, and iterates through each member looking for classes that have the [DefectTrack] attribute attached. For classes that have the attribute, the test program outputs the values of the attribute to the console. The program then performs the same steps and iteration for methods. These loops “walk” their way through the entire assembly.

Now examine some of the more important lines of code. The first line and second line of the DisplayDefectTrack( ) method retrieve a reference to an Assembly object by loading the specified Assembly and then retrieves an array containing all of the types in the assembly.

Assembly loAssembly = 
  Assembly.Load( lcAssembly ) ;
Type[ ] laTypes = 
  loAssembly.GetTypes( ) ;

A FOR...EACH loop iterates through each of the types of the assembly. The program outputs the name of the current type to the console and then the following line of code queries the current type for an array containing [DefectTrack] attributes.

object[ ] laAttributes = 
  loType.GetCustomAttributes( 
    typeof( DefectTrackAttribute ), 
    false ) ;

You specify the parameter typeof(DefectTrackingAttribute) on the GetCustomAttributes() method so that you can limit the returned custom attributes to be only of the type that you created in the example. The second parameter of false indicates that you do not want to include the type's inheritance chain when trying to find your attributes.

A FOR...EACH loop iterates through each of the custom attributes and outputs its values to the console. You should recognize that the first line of the FOR...EACH block creates a new variable and does a typecast against the current attribute.

DefectTrackAttribute loDefectTrack = 
  (DefectTrackAttribute)loAtt ;

Why is this necessary? The GetCustomAttributes() method returned an array that contains references that get cast to the generic type Object. You want to gain access to the values from your custom attribute class, and to do so you must recast these references to their true concrete type, DefectTrackAttribute. Once you've completed this you can use the attributes and the program can output the attribute values to the console.

Because you can apply your attribute to either classes or methods, the program then calls the GetMethods() method of the current type object from the assembly.

MethodInfo[ ] laMethods = 
  loType.GetMethods( 
    BindingFlags.Public | 
    BindingFlags.Instance |   
    BindingFlags.DeclaredOnly ) ;

For an example I chose to pass some values from the BindingFlags enumeration to GetMethods*().* These three BindingFlags, when used in combination, limit the methods returned to ones that you defined directly in the current class. I wanted to limit the amount of output in the example, but you probably would not do this in practice because a developer might apply the [DefectTrackAttribute] to an overridden method. My implementation would not catch those attributes.

The remaining code does essentially the same processing for each of the methods that it did for each of the classes?the code queries each method for custom attributes of the [DefectTrack] type and then outputs the values for the ones it finds to the console.

Conclusion

I've just presented the implementation as just one example of how a developer might use .NET attributes to enhance their development process. Custom attributes are a bit like XML in that the big benefits aren't really related to “what it does.” Custom attributes' real benefits lie in “what you can do with it.” The possibilities are truly limitless and the open nature of custom attributes makes it likely that some of their most novel and powerful uses have yet to be conceived of.

using System ;

namespace MyAttributeClasses
{
  [AttributeUsage( AttributeTargets.Class |
    AttributeTargets.Method,
    AllowMultiple = true)]
  public class DefectTrackAttribute : System.Attribute
  {
    private string cDefectID ;
    private DateTime dModificationDate ;
    private string cDeveloperID ;
    private string cDefectOrigin ;
    private string cFixComment ;

    public DefectTrackAttribute( 
      string lcDefectID, 
      string lcModificationDate, 
      string lcDeveloperID )
    { this.cDefectID = lcDefectID ;
      this.dModificationDate = 
        System.DateTime.Parse( lcModificationDate ) ;
      this.cDeveloperID = lcDeveloperID ; }

      public string DefectID
      { get { return cDefectID ; } }

      public DateTime ModificationDate
      { get { return 
        dModificationDate.ToShortDateString( ) ; } }

      public string DeveloperID
      { get { return cDeveloperID ; } }

      public string Origin
      { get { return cDefectOrigin ; }
        set { cDefectOrigin = value ; } }

      public string FixComment
      { get { return cFixComment ; }
        set { cFixComment = value ; } }
    }
}

using System ;
using MyAttributeClasses ;

namespace SomeClassesToTest
{
  [DefectTrack( "1377", "12/15/02", "David Tansey" ) ]
  [DefectTrack( "1363", "12/12/02", "Toni Feltman", 
    Origin = "Coding: Unhandled Exception" ) ]
  public class SomeCustomPricingClass
  {
    public double GetAdjustedPrice( 
      double tnPrice,
      double tnPctAdjust )
    { return tnPrice + ( tnPrice * tnPctAdjust ) ; }
 
    [DefectTrack( "1351", "12/10/02", "David Tansey", 
      Origin = "Specification: Missing Requirement", 
      FixComment = "Added PriceIsValid( ) function" ) ]
    public bool PriceIsValid( double tnPrice )
    { return tnPrice > 0.00 && tnPrice < 1000.00 ; }
  }
 
  [DefectTrack( "NEW", "12/12/02", "Mike Feltman" ) ]
  public class AnotherCustomClass
  {
    string cMyMessageString ;

    public AnotherCustomClass( ){ } 

    [DefectTrack( "1399", "12/17/02", "David Tansey", 
       Origin = "Analysis: Missing Requirement" ) ]
    public SetMessage( string lcMessageString )
    { this.cMyMessageString = lcMessageString ; }
  }
}

using System ;
using System.Reflection ;
using MyAttributeClasses ;

public class TestMyAttribute
{
  public static void Main( )
  { DisplayDefectTrack( "MyAttributes" ) ; } 

  public static void DisplayDefectTrack( 
    string lcAssembly )
  {
    Assembly loAssembly = 
      Assembly.Load( lcAssembly ) ;
    
    Type[ ] laTypes = loAssembly.GetTypes( ) ;

    foreach( Type loType in laTypes )
    {
      Console.WriteLine("*======================*" ) ;
      Console.WriteLine( "TYPE:\t" + 
        loType.ToString( ) ) ;
      Console.WriteLine( "*=====================*" ) ;
    
      object[ ] laAttributes = 
        loType.GetCustomAttributes( 
          typeof( DefectTrackAttribute ), 
          false ) ;

      if( laAttributes.Length > 0 )
        Console.WriteLine( "\nMod/Fix Log:" ) ;

      foreach( Attribute loAtt in laAttributes )
      {
        DefectTrackAttribute loDefectTrack = 
          (DefectTrackAttribute)loAtt ;

        Console.WriteLine( "----------------------" ) ;
        Console.WriteLine( "Defect ID:\t" + 
          loDefectTrack.DefectID ) ;
        Console.WriteLine( "Date:\t\t" + 
          loDefectTrack.ModificationDate ) ;
        Console.WriteLine( "Developer ID:\t" + 
          loDefectTrack.DeveloperID ) ;
        Console.WriteLine( "Origin:\t\t" + 
          loDefectTrack.Origin ) ;     
        Console.WriteLine( "Comment:\n" + 
          loDefectTrack.FixComment ) ;      
      }

      MethodInfo[ ] laMethods = 
        loType.GetMethods( 
          BindingFlags.Public | 
          BindingFlags.Instance |   
          BindingFlags.DeclaredOnly ) ;

      if( laMethods.Length > 0 )
      {
        Console.WriteLine( "\nMethods: " ) ;
        Console.WriteLine( "----------------------" ) ;
      }

      foreach( MethodInfo loMethod in laMethods )
      {
        Console.WriteLine( "\n\t" + 
          loMethod.ToString( ) ) ;
        
        object[ ] laMethodAttributes =   
          loMethod.GetCustomAttributes( 
            typeof( DefectTrackAttribute ), 
            false ) ;
        
        if( laMethodAttributes.Length > 0 )
          Console.WriteLine( "\n\t\tMod/Fix Log:" ) ;
    
        foreach( Attribute loAtt in laMthAttributes )
        {
          DefectTrackAttribute loDefectTrack = 
            (DefectTrackAttribute)loAtt ;
          Console.WriteLine( "\t\t----------------" ) ;
          Console.WriteLine( "\t\tDefect ID:\t" + 
            loDefectTrack.DefectID ) ;
          Console.WriteLine( "\t\tDeveloper ID:\t" +
            loDefectTrack.DeveloperID ) ;
          Console.WriteLine( "\t\tOrigin:\t\t" +  
            loDefectTrack.Origin ) ;     
          Console.WriteLine( "\t\tComment:\n\t\t" + 
            loDefectTrack.FixComment ) ;      
        }
      }
      Console.WriteLine( "\n\n" ) ;
    }
  }
}