C# 0 The Complete Reference

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

Inter face

Method

Module

Parameter

Proper ty

ReturnValue

Struct

Two or more of these value 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.

www.freepdf-books.com

---

492

 

P a r t   I :  

T h e   C #   L a n g u a g e

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.");

  }

  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 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

. Second, they 

must be members of a class or structure, not an interface. Third, they cannot be preceded 

with the 

override

 keyword.

www.freepdf-books.com

---