Chapter 24 Attributes

124. Attributes

2[Note: Much of the C# language enables the programmer to specify declarative information about the

3entities defined in the program. For example, the accessibility of a method in a class is specified by

4decorating it with the method-modifiers public, protected, internal, and private. end note]

5C# enables programmers to invent new kinds of declarative information, called attributes. Programmers can

6then attach attributes to various program entities, and retrieve attribute information in a run-time

7environment. [Note: For instance, a framework might define a HelpAttribute attribute that can be placed

8on certain program elements (such as classes and methods) to provide a mapping from those program

9elements to their documentation. end note]

10Attributes are defined through the declaration of attribute classes (§24.1), which can have positional and

11named parameters (§24.1.2). Attributes are attached to entities in a C# program using attribute specifications

12(§24.2), and can be retrieved at run-time as attribute instances (§24.3).

1324.1 Attribute classes

14A class that derives from the abstract class System.Attribute, whether directly or indirectly, is an

15attribute class. The declaration of an attribute class defines a new kind of attribute that can be placed on a

16declaration. By convention, attribute classes are named with a suffix of Attribute. Uses of an attribute can

17either include or omit this suffix.

18A generic class declaration shall not use System.Attribute as a direct or indirect base class. [Example:

19using System;

20public class B : Attribute {}

22end example]

2324.1.1 Attribute usage

24The attribute AttributeUsage (§24.4.1) is used to describe how an attribute class can be used.

25AttributeUsage has a positional parameter (§24.1.2) that enables an attribute class to specify the kinds of

26declarations on which it can be used. [Example: The example

27using System;

28[AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface)]

29public class SimpleAttribute: Attribute

30{}

31defines an attribute class named SimpleAttribute that can be placed on class-declarations and interface-

32declarations only. The example

33[Simple] class Class1 {…}

34[Simple] interface Interface1 {…}

35shows several uses of the Simple attribute. Although this attribute is defined with the name

36SimpleAttribute, when this attribute is used, the Attribute suffix can be omitted, resulting in the short

37name Simple. Thus, the example above is semantically equivalent to the following

38[SimpleAttribute] class Class1 {…}

39[SimpleAttribute] interface Interface1 {…}

40end example]

365

C# LANGUAGE SPECIFICATION

1AttributeUsage has a named parameter (§24.1.2), called AllowMultiple, which indicates whether the

2attribute can be specified more than once for a given entity. If AllowMultiple for an attribute class is true,

3then that class is a multi-use attribute class, and can be specified more than once on an entity. If

4AllowMultiple for an attribute class is false or it is unspecified, then that class is a single-use attribute

5class, and can be specified at most once on an entity.

6[Example: The example

7using System;

8[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]

9public class AuthorAttribute: Attribute

10{

15private string name;

16}

17defines a multi-use attribute class named AuthorAttribute. The example

18[Author("Brian Kernighan"), Author("Dennis Ritchie")]

19class Class1 {…}

20shows a class declaration with two uses of the Author attribute. end example]

21AttributeUsage has another named parameter (§24.1.2), called Inherited, which indicates whether the

22attribute, when specified on a base class, is also inherited by classes that derive from that base class. If

23Inherited for an attribute class is true, then that attribute is inherited. If Inherited for an attribute class

24is false then that attribute is not inherited. If it is unspecified, its default value is true.

25An attribute class X not having an AttributeUsage attribute attached to it, as in

26using System;

27class X: Attribute { … }

28is equivalent to the following:

29using System;

30[AttributeUsage(AttributeTargets.All, AllowMultiple = false, Inherited =

31true)]

32class X: Attribute { … }

3324.1.2 Positional and named parameters

34Attribute classes can have positional parameters and named parameters. Each public instance constructor

35for an attribute class defines a valid sequence of positional parameters for that attribute class. Each non-

36static public read-write field and property for an attribute class defines a named parameter for the attribute

37class. Both accessors of a property need to be public for the property to define a named parameter.

38[Example: The example

39using System;

40[AttributeUsage(AttributeTargets.Class)]

41public class HelpAttribute: Attribute

42{

50public string Url { get {…} }

51}

366