Overview

This post gives an overview of C# attributes; what they are, the different flavours, when they should be used and finishing up with some examples.

What are C# Attributes?

Attributes in C# provide a mechanism of associating Metadata with code entities such as types, methods, properties etc. Once defined you can then retrieve the Metadata at run time using Reflection.

What flavours do they come in?

Two flavours of attributes are available:

1. Predefined which are the ones provided by the .NET base class library
2. Custom which are created by the developer to fill in any gaps in the required Metadata.

Attributes can be defined on many different targets; such as the assembly, type (Struct, class interface), methods etc. Please refer to the table here for the full list of targets available.

When should I use them?

Reviewing the official .NET guide on Attributes for this post, the docs give a verbose introduction to Attributes. Myself I prefer the following quote that is taken from an blog post by Eric Lippert which succinctly explains the reason for using attributes

use attributes to describe your mechanisms

Example 1: The Obsolete Predefined Attribute

This first example shows how to use the Obsolete Predefined attribute.

The class Foo has a method that is now obsolete and should no longer be used.

using System;

namespace ObsoleteAttributeGeekOut
{
  class Foo
  {
    [Obsolete(message:"Use NewBar() instead")]
    public void OldBar()
    {
      Console.WriteLine("Calling OldBar");
    }

    public void NewBar()
    {
      Console.WriteLine("Calling NewBar");
    }
  }
}

I have added the Obsolete Attribute to the OldFoo method along with a message to help developers identify which method should be used instead.

If I then try to use OldBar, as in the code below

namespace ObsoleteAttributeGeekOut
{
  class Program
  {
    static void Main(string[] args)
    {
      Foo f = new Foo();
      f.OldBar();
    }
  }
}

Visual Studio displays a helpful message.

When compiling the program, you will see the following warning:

ObsoleteAttributeGeekOutProgram.cs(10,13,10,23): warning CS0618: ‘Foo.OldBar()’ is obsolete: ‘Use NewBar() instead’

The code for this example can be found here.

Example 2: Creating a Custom Class Attribute & Using Reflection to examine the data at run time

The first step to create a Custom Attribute is to create a new class deriving from System.Attribute as the code below demonstrates.

using System;

namespace ClassLevelAttributes
{
  [AttributeUsage(AttributeTargets.Class)]
  public sealed class UsefulClassMessageAttribute : Attribute
  {
    private string s;

    public string S
    {
      get
      {
        return s;
      }
    }

    public UsefulClassMessageAttribute(string s)
    {
      this.s = s;
    }
  }
}

There are several items of note that are worthy of further explanation about this class.

1. I use a Predefined attribute to define the level that the Custom attribute should be used at.
2. The class is sealed. Rather than sidetrack the example if you are interested in reading more on why you should seal your attribute classes take a look at this StackOverflow question.
3. The name of the class ends with Attribute. This is a convention rather than a rule and is recommended for readability. As you will see when the attribute is applied the word Attribute is optional.

With the Custom Attribute, UsefulClassMessageAttribute defined I can now go ahead and use it as in the code below.

using System;

namespace ClassLevelAttributes
{
  [UsefulClassMessage(s:"This is something useful")]
  class Example
  {
    public void Foo()
    {
      Console.WriteLine("Called Foo");
    }
  }
}

Here you can see the Custom Attribute applied to the class Example. Note that the name used is UsefulClassMessage and not UsefulClassMessageAttribute.

A Custom attribute is worthless until you can see the information. So for the final code in this example I use the following method to obtain the Custom Attribute information.

using System;

namespace ClassLevelAttributes
{
  class Program
  {
    static void Main(string[] args)
    {
      GetAttribute(typeof(Example));
    }

    public static void GetAttribute(Type t)
    {
      UsefulClassMessageAttribute theAttribute = (UsefulClassMessageAttribute)Attribute.GetCustomAttribute(t, typeof(UsefulClassMessageAttribute));

      if(theAttribute == null)
      {
        Console.WriteLine("The attribute was not found");
      }
      else
      {
        Console.WriteLine($"The attribute value is: {theAttribute.S}");
      }
    }
  }
}

Running this, you would see the following in the console window:

The attribute value is: This is something useful

The code for this example can be found here.

Example 3: Creating a Custom Method Attribute & Using Reflection to examine the data at run time

As shown in Example 2, the first step in creating a Custom Method is to create a class that derives from System.Attribute.

using System;

namespace MethodLevelAttributes
{
  [AttributeUsage(AttributeTargets.Method)]
  public sealed class UsefulMethodMessageAttribute : Attribute
  {
    string s;
    public string S
    {
      get
      {
        return s;
      }
    }

    public UsefulMethodMessageAttribute(string s)
    {
      this.s = s;
    }
  }
}

With the exception of it’s name and that the AttributeUsage which is now set to Method, this class is identical to the one shown in Example 2.

With the Custom Attribute, UsefulMethodMessageAttribute defined I can now go ahead and use it as in the code below.

using System;
namespace MethodLevelAttributes
{
  class Example
  {
    [UsefulMethodMessage(s: "Some pertinent information about the method")]
    public void Foo()
    {
      Console.WriteLine("Calling Foo");
    }
  }
}

Here you can see that the Custom Attribute has been applied to the method Foo.

In the final code example I use reflection to obtain information about the attribute.

using System;
using System.Reflection;

namespace MethodLevelAttributes
{
  class Program
  {
    static void Main(string[] args)
    {
      GetAttribute();
    }

    public static void GetAttribute()
    {
      foreach(MethodInfo mi in typeof(Example).GetMethods())
      {
        UsefulMethodMessageAttribute theAttribute = (UsefulMethodMessageAttribute)Attribute.GetCustomAttribute(mi, typeof(UsefulMethodMessageAttribute));

        if (theAttribute != null)
        {
          Console.WriteLine($"The attribute value is: {theAttribute.S}");
        }
      }
    }
  }
}

Running this you would see the following in the console:

The attribute value is: Some pertinent information about the method

The code for this example can be found here.

Acknowledgements

Eric Lippert 

C# 6.0 and the .NET 4.6 Framework

Writing Custom Attributes