Chapter 24 Attributes

1defines an attribute class named HelpAttribute that has one positional parameter (string url) and one

2named parameter (string Topic). Although it is non-static and public, the property Url does not define a

3named parameter, since it is not read-write.

4This attribute class might be used as follows:

5[Help("http://www.mycompany.com/…/Class1.htm")]

6class Class1

7{

8}

9[Help("http://www.mycompany.com/…/Misc.htm", Topic ="Class2")]

10class Class2

11{

12}

13end example]

1424.1.3 Attribute parameter types

15The types of positional and named parameters for an attribute class are limited to the attribute parameter

16types, which are:

17• One of the following types: bool, byte, char, double, float, int, long, short, string.

18• The type object.

19• The type System.Type.

20• An enum type, provided it has public accessibility and the types in which it is nested (if any) also have

21public accessibility.

22• Single-dimensional arrays of the above types.

2324.2 Attribute specification

24Attribute specification is the application of a previously defined attribute to a declaration. An attribute is a

25piece of additional declarative information that is specified for a declaration. Attributes can be specified at

26global scope (to specify attributes on the containing assembly) and for type-declarations (§16.6), class-

27member-declarations (§17.1.4), struct-member-declarations (§18.2), interface-member-declarations

28(§20.2), enum-member-declarations (§21.1), accessor-declarations (§17.6.2), event-accessor-declarations

29(§17.7), elements of formal-parameter-lists (§17.5.1), and elements of type-parameter-lists (§26.1.1).

30Attributes are specified in attribute sections. An attribute section consists of a pair of square brackets, which

31surround a comma-separated list of one or more attributes. The order in which attributes are specified in

32such a list, and the order in which sections attached to the same program entity are arranged, is not

33significant. For instance, the attribute specifications [A][B], [B][A], [A, B], and [B, A] are equivalent.

34global-attributes:

367

23( named-argument-list )

24positional-argument-list:

36An attribute consists of an attribute-name and an optional list of positional and named arguments. The

37positional arguments (if any) precede the named arguments. A positional argument consists of an attribute-

38argument-expression; a named argument consists of a name, followed by an equal sign, followed by an

39attribute-argument-expression, which, together, are constrained by the same rules as simple assignment. The

40order of named arguments is not significant.

41[Note: For convenience, a trailing comma is allowed in a global-attribute-section and an attribute-section,

42just as one is allowed in an array-initializer (§19.6). end note]

43The attribute-name identifies an attribute class. type-name shall refer to an attribute class. Otherwise, a

44compile-time error occurs. [Example: The example

45class Class1 {}

368

Chapter 24 Attributes

1results in a compile-time error because it attempts to use Class1 as an attribute class when Class1 is not

2an attribute class. end example]

3When an attribute is placed at the global level, a global-attribute-target-specifier is required. The only

4standardized global-attribute-target name is assembly. This target name shall only be used in the context

5of an assembly.

6The only standardized attribute-target names are event, field, method, param, property, return, and

7type. These target names shall only be used in the following contexts:

8• event — an event.

9• field — a field. A field-like event (i.e., one without accessors) can also have an attribute with this

10target.

11• method — a constructor, destructor, method, operator, property get and set accessors, and event add and

12remove accessors. A field-like event (i.e., one without accessors) can also have an attribute with this

13target.

14• param — a property set accessor, event add and remove accessors, and a parameter in a constructor,

15method, and operator.

16• property — a property.

17• return — a delegate, method, operator, and property get accessor.

18• type — a delegate, class, struct, and interface.

19• typevar — a type parameter.

20Certain contexts permit the specification of an attribute on more than one target. A program can explicitly

21specify the target by including an attribute-target-specifier. In the absence of an attribute-target-specifier, a

22reasonable default is applied, but an attribute-target-specifier can be used to affirm or override the default in

23certain ambiguous cases (or to just affirm the default in non-ambiguous cases). Thus, typically, attribute-

24target-specifiers can be omitted. The potentially ambiguous contexts are resolved as follows (using equality

25as defined in §9.4.2):

26• An attribute specified on a delegate declaration can apply either to the delegate being declared or to its

27return value. In the absence of an attribute-target-specifier, the attribute applies to the delegate. An

28attribute-target equal to type indicates that the attribute applies to the delegate; an attribute-target

29equal to return indicates that the attribute applies to the return value.

30• An attribute specified on a method declaration can apply either to the method being declared or to its

31return value. In the absence of an attribute-target-specifier, the attribute applies to the method. An

32attribute-target equal to method indicates that the attribute applies to the method; an attribute-target

33equal to return indicates that the attribute applies to the return value.

34• An attribute specified on an operator declaration can apply either to the operator being declared or to its

35return value. In the absence of an attribute-target-specifier, the attribute applies to the operator. An

36attribute-target equal to method indicates that the attribute applies to the operator; an attribute-target

37equal to return indicates that the attribute applies to the return value.

38• An attribute specified on a get accessor declaration for a property or indexer declaration can apply either

39to the associated method or to its return value. In the absence of an attribute-target-specifier, the

40attribute applies to the method. An attribute-target equal to method indicates that the attribute applies to

41the method; an attribute-target equal to return indicates that the attribute applies to the return value.

42• An attribute specified on a set accessor for a property or indexer declaration can apply either to the

43associated method or to its lone implicit parameter. In the absence of an attribute-target-specifier, the

44attribute applies to the method. An attribute-target equal to method indicates that the attribute applies to

45the method; the presence of an attribute-target equal to param indicates that the attribute applies to the

46parameter.

369

Chapter 24 Attributes

1an attribute class named XAttributeAttribute!). If the declaration for class X is removed, then both

2attributes refer to the attribute class named XAttribute, as follows:

3using System;

4[AttributeUsage(AttributeTargets.All)]

5public class XAttribute: Attribute

6{}

12class Class3 {}

13end example]

14It is a compile-time error to use a single-use attribute class more than once on the same entity. [Example:

15The example

16using System;

17[AttributeUsage(AttributeTargets.Class)]

18public class HelpStringAttribute: Attribute

19{

24public string Value { get {…} }

25}

26[HelpString("Description of Class1")]

27[HelpString("Another description of Class1")]

28public class Class1 {}

29results in a compile-time error because it attempts to use HelpString, which is a single-use attribute class,

30more than once on the declaration of Class1. end example]

31An expression E is an attribute-argument-expression if all of the following statements are true:

32• The type of E is an attribute parameter type (§24.1.3).

33• At compile-time, the value of E can be resolved to one of the following:

34o A constant value.

35o Atypeof-expression (§14.5.11) specifying a non-generic type, a closed constructed type (§26.5.2), or

36an unbound generic type (§26.5).

37o A one-dimensional array of attribute-argument-expressions.

38[Example:

39using System;

40[AttributeUsage(AttributeTargets.Class)]

41public class MyAttribute: Attribute

42{

371