The Obsolete attribute allows you to mark a program construct as obsolete and to display a helpful warning message when the code is compiled. The following code shows an example of its use:

Notice that method Main calls PrintOut even though it's marked as obsolete. In spite of this, the code compiles and runs fine, and produces the following output:

Start of Main

During compilation, though, the compiler produces the following CS0618 warning message to inform you that you are using an obsolete construct:

'AttrObs.Program.PrintOut(string)' is obsolete: 'Use method SuperPrintOut'

Another overload of the Obsolete attribute takes a second parameter of type bool. This parameter specifies whether use of the target should be flagged as an error instead of just a warning. The following code specifies that it should be flagged as an error:

The Conditional attribute allows you to either include or exclude all the invocations of a particular method. To use the Conditional attribute, apply it to the method declaration, along with a compilation symbol as a parameter.

The CIL code defining the method itself is always included in the assembly. It is just the invocations that are either inserted or omitted.

For example, in the following code, the Conditional attribute is applied to the declaration of a method called TraceMessage. The attribute has a single parameter, which in this case is the string DoTrace.

#define DoTrace
using System;
using System.Diagnostics;

namespace AttributesConditional
{
   class Program
   {
      [Conditional( "DoTrace" )]
      static void TraceMessage(string str)
      { Console.WriteLine(str); }

      static void Main( )
      {
         TraceMessage("Start of Main");
         Console.WriteLine("Doing work in Main.");
         TraceMessage("End of Main");
      }
   }
}

Start of Main
Doing work in Main.
End of Main

Doing work in Main.

The .NET Framework predefines a number of attributes that are understood and interpreted by the compiler and the CLR. Table 24-2 lists some of these. The table uses the short names, without the "Attribute" suffix. For example, the full name of CLSCompliant is CLSCompliantAttribute.

You can apply multiple attributes to a single construct.

For example, the following two sections of code show the two ways of applying multiple attributes. The sections of codeare equivalent.

Besides classes, you can also apply attributes to other program constructs such as fields and properties. The following declaration shows an attribute on a field, and multiple attributes on a method:

[MyAttribute("Holds a value", "Version 3.2")]                // On a field
   public int MyField;


   [Obsolete]                                                   // On a method
   [MyAttribute("Prints out a message.", "Version 3.6")]
   public void PrintOut()
   {
      ...

You can also explicitly label attributes to apply to a particular target construct. To use an explicit target, place the target type, followed by a colon, at the beginning of the attribute section. For example, the following code decorates the method with an attribute, and also applies an attribute to the return value.

The C# language defines ten standard attribute targets, which are listed in Table 24-3. Most of the target names are self-explanatory, but type covers classes, structs, delegates, enums, and interfaces. The typevar target name specifies type parameters to constructs that use generics.

You can also use an explicit target to set attributes at the assembly and module level, by using the assembly and module target names. (Assemblies and modules were explained in Chapter 10.) Some important points about assembly-level attributes are the following:

The following are lines from an AssemblyInfo.cs file:

[assembly: AssemblyTitle("SuperWidget")]
   [assembly: AssemblyDescription("Implements the SuperWidget product.")]
   [assembly: AssemblyConfiguration("")]
   [assembly: AssemblyCompany("McArthur Widgets, Inc.")]
   [assembly: AssemblyProduct("Super Widget Deluxe")]
   [assembly: AssemblyCopyright("Copyright © McArthur Widgets 2008")]
   [assembly: AssemblyTrademark("")]
   [assembly: AssemblyCulture("")]

Declaring an attribute class is, for the most part, the same as declaring any other class. There are, however, several things to be aware of:

For example, the following code shows the beginning of the declaration of attribute MyAttributeAttribute:

Since an attribute holds information about the target, the public members of an attribute class generally consist only of the following:

Attributes, like other classes, have constructors. Every attribute must have at least one public constructor.

For example, with the following constructor, the compiler would produce an error message if the name did not includethe suffix:

When you apply an attribute to a target, you are specifying which constructor should be used to create the instance of the attribute. The parameters listed in the attribute application are the actual parameters for the constructor.

For example, in the following code, MyAttribute is applied to a field and to a method. For the field, the declaration specifies a constructor with a single string parameter. For the method, it specifies a constructor with two string parameters.

[MyAttribute("Holds a value")]                 // Constructor with one string
   public int MyField;

   [MyAttribute("Version 1.3", "Sal Martin")]     // Constructor with two strings
   public void MyMethod()
   { ...

Other important points about attribute constructors are the following:

[MyAttr]
class SomeClass ...


[MyAttr()]
class OtherClass ...

As with other classes, you cannot call the constructor explicitly. An instance of an attribute is created, and a constructor called, only when an attribute consumer accesses the attribute. This is very different from other class instances, which are created at the position where you use an object-creation expression. Applying an attribute is a declarative statement that does not determine when an object of the attribute class should be constructed.

Figure 24-4 compares the use of a constructor for a regular class and the use of a constructor with attributes.

Figure 24-4. Comparing the use of constructors

So far, the parameters you've seen with attribute constructors have been like the parameters for regular class constructors. As with regular constructors, the actual parameters of attribute constructors must be placed in the correct order, matching the formal parameters in the class declaration. These are called positional parameters, because the compiler knows which actual parameter goes with which formal parameter by its position in the parameter list.

But attribute constructors can also have another type of actual parameter, called a named parameter.

Named parameters are actual parameters. There is nothing different in the declaration of the formal parameters of the constructor. The only difference is in the list of actual parameters that is supplied when the attribute is applied.

The following code shows the application of an attribute using a positional parameter and two named parameters:

The following code shows the declaration of the attribute class, as well as its application on class MyClass. Notice that the constructor declaration lists only a single formal parameter. And yet, by using named parameters, you can give the constructor three actual parameters. The two named parameters set the values of fields Ver and Reviewer.

You've seen that you can apply attributes to classes. But attributes themselves are classes, and there is one important predefined attribute that you can apply to your custom attributes. It is the AttributeUsage attribute. You can use it to restrict the usage of an attribute to a specific set of target types.

For example, if you want your custom attribute MyAttribute to be applied only to methods, you could use the following form of AttributeUsage:

AttributeUsage has three important public properties, which are listed in Table 24-4. The table shows the names of the properties and their meanings. For the second two properties, it also shows their default values.

The Constructor for AttributeUsage

The constructor for AttributeUsage takes a single, positional parameter that specifies which target types are allowed for the attribute. It uses this parameter to set the ValidOn property. The acceptable target types are members of the AttributeTarget enumeration. The complete set of the members of the AttributeTarget enumeration is shown in Table 24-5.

You can combine the usage types by using the bitwise OR operator. For example, the attribute declared in the following code can be applied only to methods and constructors.

Table 24-5. Members of Enum AttributeTarget

All	Assembly	Class	Constructor
Delegate	Enum	Event	Field
GenericParameter	Interface	Method	Module
Parameter	Property	ReturnValue	Struct

When you apply AttributeUsage to an attribute declaration, the constructor will have at least the one required parameter, which contains the target types to be stored in ValidOn. You can also optionally set the Inherited and AllowMultiple properties by using named parameters. If you do not set them, they will have their default values, as shown in Table 24-4.

As an example, the next code block specifies the following about MyAttribute:

• MyAttribute must be applied only to classes.

• MyAttribute is not inherited by classes derived from classes to which it is applied.

• There cannot be multiple instances of MyAttribute applied tothe same target.

[ AttributeUsage( AttributeTarget.Class,          // Required, positional
                  Inherited = false,              // Optional, named
                  AllowMultiple = false ) ]       // Optional, named
public sealed class MyAttributeAttribute : System.Attribute
{ ...

The following practices are strongly suggested when writing custom attributes:

The following code illustrates these guidelines:

[AttributeUsage( AttributeTargets.Class )]
   public sealed class  MyAttributeAttribute : System.Attribute
   {
      private string _Description;
      private string _VersionNumber;
      private string _ReviewerID;

      public string Description
         { get { return _Description; }   set { _Description = value; } }

      public string VersionNumber
         { get { return _VersionNumber; } set { _VersionNumber = value; } }

      public string ReviewerID
         { get { return _ReviewerID; }    set { _ReviewerID = value; } }

      public MyAttributeAttribute(string desc, string ver)
      {
         Description   = desc;
         VersionNumber = ver;
      }
   }

You can use the IsDefined method of the Type object to determine whether a particular attribute is applied to a particular class.

For example, the following code declares an attributed class called MyClass, and also acts as its own attribute consumer by accessing an attribute declared and applied in the program itself. At the top of the code are declarations of the attribute MyAttribute and the class MyClass, to which it is applied. The code does the following:

[AttributeUsage(AttributeTargets.Class)]
public sealed class MyAttributeAttribute : System.Attribute
{ ... }
[MyAttribute("Check it out", "2.4")]
class MyClass {  }

class Program {
   static void Main() {
      MyClass mc = new MyClass(); // Create an instance of the class.
      Type t = mc.GetType();      // Get the Type object from the instance.
      bool isDefined =            // Check the Type for the attribute.
         t.IsDefined(typeof(MyAttributeAttribute), false);

      if( isDefined )
         Console.WriteLine("MyAttribute is applied to type {0}", t.Name);
   }
}

This code produces the following output:

MyAttribute is applied to type MyClass

The GetCustomAttributes method returns an array of the attributes applied to a construct.

The following code uses the same attribute and class declarations as the previous example. But in this case, it doesn't just determine whether an attribute is applied to the class. Instead, it retrieves an array of the attributes applied to the class and cycles through them, printing out their member values.

static void Main()
   {
      Type t = typeof(MyClass);
      object[] AttArr = t.GetCustomAttributes(false);

      foreach (Attribute a in AttArr)
      {
         MyAttributeAttribute attr = a as MyAttributeAttribute;
         if (null != attr)
         {
            Console.WriteLine("Description    : {0}", attr.Description);
            Console.WriteLine("Version Number : {0}", attr.VersionNumber);
            Console.WriteLine("Reviewer ID    : {0}", attr.ReviewerID);
         }
      }
   }

This code produces the following output:

Description    : Check it out
Version Number : 2.4
Reviewer ID    :