Chapter 24 Attributes

1• Keep the following information for run-time instantiation of the attribute: the attribute class T, the

2instance constructor C on T, the positional-argument-list P and the named-argument-list N, with the

3values resolved completely at compile-time.

424.3.2 Run-time retrieval of an attribute instance

5Compilation of an attribute yields an attribute class T, an instance constructor C on T, a positional-argument-

6list P, and a named-argument-list N. Given this information, an attribute instance can be retrieved at run-time

7using the following steps:

8• Follow the run-time processing steps for executing an object-creation-expression of the form

9new T(P), using the instance constructor C and values as determined at compile-time. These steps

10either result in an exception, or produce an instance of T. Call this instance O.

11• For each named-argument Arg in N, in order:

12o Let Name be the identifier of the named-argument Arg. If Name does not identify a non-static public

13read-write field or property on O, then an exception is thrown.

14o Let Value be the result of evaluating the attribute-argument-expression of Arg.

15o If Name identifies a field on O, then set this field to the value Value.

16o Otherwise, Name identifies a property on O. Set this property to the value Value.

17o The result is O, an instance of the attribute class T that has been initialized with the positional-

18argument-list P and the named-argument-list N.

1924.4 Reserved attributes

20The following attributes affect the language, as stated:

21• System.AttributeUsageAttribute (§24.4.1), which is used to describe the ways in which an

22attribute class can be used.

23• System.ConditionalAttribute (§24.4.2), which is used to define conditional methods and

24attributes.

25• System.ObsoleteAttribute (§24.4.3), which is used to mark a member as obsolete.

2624.4.1 The AttributeUsage attribute

27The attribute AttributeUsage is used to describe the manner in which the attribute class can be used.

28A class that is decorated with the AttributeUsage attribute shall derive from System.Attribute, either

29directly or indirectly. Otherwise, a compile-time error occurs.

30[Note: For an example of using this attribute, see §24.1.1. end note]

3124.4.2 The Conditional attribute

32The attribute Conditional enables the definition of conditional methods and conditional attribute

33classes.

3424.4.2.1 Conditional Methods

35A method decorated with the Conditional attribute is said to be a conditional method.The Conditional

36attribute indicates a condition by testing a conditional compilation symbol. Calls to a conditional method are

37either included or omitted depending on whether this symbol is defined at the point of the call. If the symbol

38is defined, the call is included; otherwise, the call is omitted.

39A conditional method is subject to the following restrictions:

373

C# LANGUAGE SPECIFICATION

1• The conditional method shall be a method in a class-declaration or struct-declaration. A compile-time

2error occurs if the Conditional attribute is specified on an interface method.

3• The conditional method shall have a return type of void.

4• The conditional method shall not be marked with the override modifier. A conditional method can be

5marked with the virtual modifier, however. Overrides of such a method are implicitly conditional,

6and shall not be explicitly marked with a Conditional attribute.

7• The conditional method shall not be an implementation of an interface method. Otherwise, a compile-

8time error occurs.

9In addition, a compile-time error occurs if a conditional method is used in a delegate-creation-expression.

10[Example: The example

11#define DEBUG

12using System;

13using System.Diagnostics;

14class Class1

15{

19}

20}

21class Class2

22{

25}

26}

27declares Class1.M as a conditional method. Class2's Test method calls this method. Since the

28conditional compilation symbol DEBUG is defined, if Class2.Test is called, it will call M. If the symbol

29DEBUG had not been defined, then Class2.Test would not call Class1.M. end example]

30It is important to understand that the inclusion or exclusion of a call to a conditional method is controlled by

31the conditional compilation symbols at the point of the call. [Example: In the following code

32// Begin class1.cs

41}

42// End class1.cs

43

51}

52// End class2.cs

374

9}

10// End class3.cs

11the classes Class2 and Class3 each contain calls to the conditional method Class1.F, which is

12conditional based on whether or not DEBUG is defined. Since this symbol is defined in the context of Class2

13but not Class3, the call to F in Class2 is included, while the call to F in Class3 is omitted. end example]

14The use of conditional methods in an inheritance chain can be confusing. Calls made to a conditional

15method through base, of the form base.M, are subject to the normal conditional method call rules.

16[Example: In the following code

17// Begin class1.cs

26}

27// End class1.cs

28

37}

38// End class2.cs

39

49}

50// End class3.cs

51Class2 includes a call to the M defined in its base class. This call is omitted because the base method is

52conditional based on the presence of the symbol DEBUG, which is undefined. Thus, the method writes to the

375