3.13 Create a Custom Attribute

Problem

You need to create a custom attribute.

Solution

Create a class that derives from the abstract base class System.Attribute . Implement constructors, fields, and properties to allow users to configure the attribute. Use System.AttributeUsageAttribute to define the following:

• Which program elements are valid targets of the attribute

• Whether you can apply more than one instance of the attribute to a program element

• Whether the attribute is inherited by derived types

Discussion

Attributes provide a generic mechanism for associating declarative information (metadata) with program elements. This metadata is contained in the compiled assembly allowing programs to retrieve it through reflection at run time. (See recipe 3.14.) Other programs, particularly the CLR, use this information to determine how they should interact with and manage program elements.

To create a custom attribute, derive a class from the abstract base class System.Attribute . Custom attribute classes must be public and by convention should have a name ending in "Attribute". A custom attribute must have at least one public constructor. The constructor parameters become the attribute's positional parameters. As with any other class, you can declare more than one constructor, giving users of the attribute the option of using different sets of positional parameters when applying the attribute. Any public read/write fields and properties declared by an attribute are automatically exposed as named parameters.

To control how and where a user can apply your attribute, apply the attribute AttributeUsageAttribute to your custom attribute. AttributeUsageAttribute supports the one positional and two named parameters described in Table 3.3. The default values specify the value that's applied to your custom attribute if you don't apply AttributeUsageAttribute or don't specify a value for that particular parameter.

Table 3.3: Members of the AttributeUsage Enumeration

Parameter	Type	Description	Default
ValidOn	positional	A member of the System.AttributeTargets enumeration that identifies the program elements on which the attribute is valid	AttributeTargets.All
AllowMultiple	named	Whether the attribute can be specified more than once for a single element	false
Inherited	named	Whether the attribute is inherited by derived classes or overridden members	true

The following example shows a custom attribute named AuthorAttribute , which you can use to identify the name and company of the person who created an assembly or a class. AuthorAttribute declares a single public constructor that takes a string containing the author's name. This means that users of AuthorAttribute must always provide a positional string parameter containing the author's name. The Company property is public , making it an optional named parameter, but the Name property is read only ”no set accessor is declared ”meaning that it isn't exposed as a named parameter.

 using System; [AttributeUsage(AttributeTargets.Class  AttributeTargets.Assembly,      AllowMultiple = true, Inherited = false)] public class AuthorAttribute : System.Attribute {     private string company; // creator's company     private string name;    // creator's name     // Declare a public constructor     public AuthorAttribute(string name) {         this.name = name;         company = "";     }     // Declare a property to get/set the company field     public string Company {         get { return company; }         set { company = value; }     }     // Declare a property to get the internal field     public string Name{         get { return name;}     } } 

The following example demonstrates some uses of AuthorAttribute :

 // Declare Allen as the assembly author [assembly:Author("Allen", Company = "Principal Objective Ltd.")] // Declare a class authored by Allen [Author("Allen", Company = "Principal Objective Ltd.")] public class SomeClass {      } // Declare a class authored by Lena [Author("Lena")] public class SomeOtherClass {      }