24.1 Attribute classes

A class that derives from the abstract class System.Attribute, whether
directly or indirectly, is an
attribute class. The declaration of an attribute class defines a new kind
of attribute that can be placed on a
declaration. By convention, attribute classes are named with a suffix of
Attribute. Uses of an attribute
may either include or omit this suffix.
24.1.1 Attribute usage
The attribute AttributeUsage (§24.4.1) is used to describe how an
attribute class can be used.
AttributeUsage has a positional parameter (§24.1.2) that enables an
attribute class to specify the kinds of
declarations on which it can be used. [Example: The example
using System;
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface)]
public class SimpleAttribute: Attribute
{}
defines an attribute class named SimpleAttribute that can be placed on
class-declarations and interfacedeclarations
only. The example
[Simple] class Class1 {?}
[Simple] interface Interface1 {?}
shows several uses of the Simple attribute. Although this attribute is
defined with the name
SimpleAttribute, when this attribute is used, the Attribute suffix may be
omitted, resulting in the
short name Simple. Thus, the example above is semantically equivalent to
the following
[SimpleAttribute] class Class1 {?}
[SimpleAttribute] interface Interface1 {?}
end example]
AttributeUsage has a named parameter (§24.1.2), called AllowMultiple,
which indicates whether the
attribute can be specified more than once for a given entity. If
AllowMultiple for an attribute class is true,
then that class is a multi-use attribute class, and can be specified more
than once on an entity. If
AllowMultiple for an attribute class is false or it is unspecified, then
that class is a single-use attribute
class, and can be specified at most once on an entity.
[Example: The example
C# LANGUAGE SPECIFICATION
306
using System;
[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
public class AuthorAttribute: Attribute
{
public AuthorAttribute(string name) {
this.name = name;
}
public string Name { get { return name;} }
private string name;
}
defines a multi-use attribute class named AuthorAttribute. The example
[Author("Brian Kernighan"), Author("Dennis Ritchie")]
class Class1 {?}
shows a class declaration with two uses of the Author attribute. end
example]
AttributeUsage has another named parameter (§24.1.2), called Inherited,
which indicates whether the
attribute, when specified on a base class, is also inherited by classes
that derive from that base class. If
Inherited for an attribute class is true, then that attribute is inherited.
If Inherited for an attribute class
is false then that attribute is not inherited. If it is unspecified, its
default value is true.
An attribute class X not having an AttributeUsage attribute attached to it,
as in
using System;
class X: Attribute { ? }
is equivalent to the following:
using System;
[AttributeUsage(AttributeTargets.All, AllowMultiple = false, Inherited =
true)]
class X: Attribute { ? }
24.1.2 Positional and named parameters
Attribute classes can have positional parameters and named parameters. Each
public instance constructor
for an attribute class defines a valid sequence of positional parameters
for that attribute class. Each nonstatic
public read-write field and property for an attribute class defines a named
parameter for the attribute
class.
[Example: The example
using System;
[AttributeUsage(AttributeTargets.Class)]
public class HelpAttribute: Attribute
{
public HelpAttribute(string url) { // url is a positional parameter
?
}
public string Topic { // Topic is a named parameter
get {?}
set {?}
}
public string Url { get {?} }
}
defines an attribute class named HelpAttribute that has one positional
parameter (string url) and one
named parameter (string Topic). Although it is non-static and public, the
property Url does not define a
named parameter, since it is not read-write.
This attribute class might be used as follows:
[Help(" http://www.mycompany.com/?/Class1.htm )]
class Class1
{
}
Chapter 24 Attributes
307
[Help(" http://www.mycompany.com/?/Misc.htm , Topic ="Class2")]
class Class2
{
}
end example]
24.1.3 Attribute parameter types
The types of positional and named parameters for an attribute class are
limited to the attribute parameter
types, which are:
? One of the following types: bool, byte, char, double, float, int, long,
short, string.
? The type object.
? The type System.Type.
? An enum type, provided it has public accessibility and the types in which
it is nested (if any) also have
public accessibility.
? Single-dimensional arrays of the above types.