Three Built-in Attributes

C# defines several built-in attributes, but three are especially important because they apply to a wide variety of situations: AttributeUsage, Conditional, and Obsolete. They are examined here.

AttributeUsage

As mentioned earlier, the AttributeUsage attribute specifies the types of items to which an attribute can be applied. AttributeUsage is another name for the System.AttributeUsageAttribute class. AttributeUsage has the following constructor:

 AttributeUsage(AttributeTargets item)

Here, item specifies the item or items upon which the attribute can be used. AttributeTargets is an enumeration that defines the following values:

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

Two or more of these values can be ORed together. For example, to specify an attribute that can be applied only to fields and properties, use

 AttributeTargets.Field | AttributeTargets.Property

AttributeUsage supports two named parameters. The first is AllowMultiple, which is a bool value. If this value is true, then the attribute can be applied more than one time to a single item. The second is Inherited, which is also a bool value. If this value is true, then the attribute is inherited by derived classes. Otherwise, it is not inherited. The default setting is false for AllowMultiple and true for Inherited.

AttributeUsage also specifies a read-only property called ValidOn, which returns a value of type AttributeTargets, which specifies what types of items the attribute can be used on. The default is AttributeTargets.All.

The Conditional Attribute

The attribute Conditional is perhaps C#’s most interesting built-in attribute. It allows you to create conditional methods. A conditional method is invoked only when a specific symbol has been defined via #define. Otherwise, the method is bypassed. Thus, a conditional method offers an alternative to conditional compilation using #if.

Conditional is another name for System.Diagnostics.ConditionalAttribute. To use the Conditional attribute, you must include the System.Diagnostics namespace.

Let’s begin with an example:

 // Demonstrate the Conditional attribute. #define TRIAL using System; using System.Diagnostics; class Test {   [Conditional("TRIAL")]   void trial() {     Console.WriteLine("Trial version, not for distribution.");   }   [Conditional("RELEASE")]   void release() {     Console.WriteLine("Final release version.");   }   public static void Main() {     Test t = new Test();     t.trial(); // called only if TRIAL is defined     t.release(); // called only if RELEASE is defined   } }

The output from this program is shown here:

 Trial version, not for distribution.

Let’s look closely at this program to understand why this output is produced. First, notice that the program defines the symbol TRIAL. Next, notice how the methods trial( ) and release( ) are coded. They are both preceded with the Conditional attribute, which has this general form:

 [Conditional (symbol )]

where symbol is the symbol that determines whether the method will be executed. This attribute can be used only on methods. If the symbol is defined, then when the method is called, it will be executed. If the symbol is not defined, then the method is not executed.

Inside Main( ), both trial( ) and release( ) are called. However, only TRIAL is defined. Thus, trial( ) is executed. The call to release( ) is ignored. If you define RELEASE, then release( ) will also be called. If you remove the definition for TRIAL, then trial( ) will not be called.

Conditional methods have a few restrictions: First, they must return void. They must be members of a class or structure, not an interface. They cannot be preceded with the override keyword.

The Obsolete Attribute

The Obsolete attribute, which is short for System.ObsoleteAttribute, lets you mark a program element as obsolete. It has this general form:

 [Obsolete(“message”)]

Here, message is displayed when that program element is compiled. Here is a short example:

 // Demonstrate the Obsolete attribute. using System; class Test {   [Obsolete("Use myMeth2, instead.")]   static int myMeth(int a, int b) {     return a / b;   }   // Improved version of myMeth.   static int myMeth2(int a, int b) {     return b == 0 ? 0 : a /b;   }   public static void Main() {    // warning displayed for this     Console.WriteLine("4 / 3 is " + Test.myMeth(4, 3));    // no warning here     Console.WriteLine("4 / 3 is " + Test.myMeth2(4, 3));   } } 

When the call to myMeth( ) is encountered in Main( ) when this program is compiled, a warning will be generated that tells the user to use myMeth2( ) instead.

A second form of Obsolete is shown here:

 [Obsolete(“message”, error)]

Here, error is a Boolean value. If it is true, then use of the obsolete item generates a compilation error rather than a warning. The difference is, of course, that a program containing an error cannot be compiled into an executable program.