CHAPTER 24 REFLECTION AND ATTRIBUTES

Restricting the Usage of an Attribute

You’ve seen that you can apply attributes to classes. But attributes themselves are classes, and there is one important predefined attribute that you can apply to your custom attributes. It's the AttributeUsage attribute. You can use it to restrict the usage of an attribute to a specific set of target types.

For example, if you want your custom attribute MyAttribute to be applied only to methods, you could use the following form of AttributeUsage:

Only to methods

↓

[ AttributeUsage( AttributeTarget.Method ) ]

public sealed class MyAttributeAttribute : System.Attribute { ...

AttributeUsage has three important public properties, which are listed in Table 24-4. The table shows the names of the properties and their meanings. For the second two properties, it also shows their default values.

Table 24-4. Public Properties of AttributeUsage

658

CHAPTER 24 REFLECTION AND ATTRIBUTES

The Constructor for AttributeUsage

The constructor for AttributeUsage takes a single, positional parameter that specifies which target types are allowed for the attribute. It uses this parameter to set the ValidOn property. The acceptable target types are members of the AttributeTarget enumeration. Table 24-5 shows the complete set of the members of the AttributeTarget enumeration.

You can combine the usage types by using the bitwise OR operator. For example, the attribute declared in the following code can be applied only to methods and constructors.

Targets

↓

[ AttributeUsage( AttributeTarget.Method | AttributeTarget.Constructor ) ] public sealed class MyAttributeAttribute : System.Attribute

{ ...

Table 24-5. Members of Enum AttributeTarget

When you apply AttributeUsage to an attribute declaration, the constructor will have at least the one required parameter, which contains the target types to be stored in ValidOn. You can also optionally set the Inherited and AllowMultiple properties by using named parameters. If you don't set them, they'll have their default values, as shown in Table 24-4.

As an example, the next code block specifies the following about MyAttribute:

•MyAttribute must be applied only to classes.

•MyAttribute is not inherited by classes derived from classes to which it is applied.

•There cannot be multiple instances of MyAttribute applied to the same target.

public sealed class MyAttributeAttribute : System.Attribute

{ ...

659

e

CHAPTER 24 REFLECTION AND ATTRIBUTES

Suggested Practices for Custom Attributes

The following practices are strongly suggested when writing custom attributes:

•The attribute class should represent some state of the target construct.

•If the attribute requires certain fields, include a constructor with positional parameters to collect that data, and let optional fields be initialized with named parameters, as needed.

•Don’t implement public methods or other function members other than properties.

•For additional security, declare the attribute class as sealed.

•Use the AttributeUsage attribute on your attribute declaration to explicitly specify the set of attribute targets.

The following code illustrates these guidelines:

[AttributeUsage( AttributeTargets.Class )]

public sealed class ReviewCommentAttribute : System.Attribute

public ReviewCommentAttribute(string desc, string ver)

{

Description = desc; VersionNumber = ver;

}

}

660