28.4 Custom attributes in depth

The following sections are intended for advanced developers who want to fully unleash the powers of custom attribute classes.

28.4.1 Named and positional parameters

Attribute classes can have named and positional parameters. So far, you have only written positional parameters which correspond to the parameters of a constructor in the attribute class. Figure 28.1 shows the attribute class with two overloaded constructors, hence allowing the Author attribute specification to be structured in either way as shown. No other attribute specification format is allowed. Something like [Author()] will give a compilation error because there is no corresponding constructor in the AuthorAttribute class which does not take in any parameter.

Figure 28.1. Attribute specifications must match one of the constructors of the attribute class.

If the attribute class has public fields or public properties, ^[4] it is possible to use named parameters in the attribute specification. A named parameter looks like an assignment expression. In the following attribute specification:

^[4] See Chapter 20. A property is a special C# class member that is often used in place of accessor and mutator methods for a private field.

 [Author("Mok", "21 Dec 02", AuthorId=999)] 

AuthorId is the named parameter and "Mok" and "21 Dec 02" are the positional parameters. If you look at the attribute specification, there shouldn't be any difficulty differentiating a named parameter from a positional one! (Named parameters have this = <value> thing, such as = 999 for the AuthorId parameter.)

What this means is that during instantiation of the attribute class:

• a constructor in the AuthorAttribute class which takes in two strings is searched for and executed;

• a public field or public property in the AuthorAttribute class by the name of AuthorId is searched for, and assigned the value of 999 .

If such a constructor cannot be found, or if the attribute class does not have a public field or property with a matching identifier, a compilation error occurs.

In the attribute class in Figure 28.2 I have inserted an additional public property AuthorId (which controls access to private field authorId ) for demonstration purposes.

Figure 28.2. Named parameters must match existing public fields or properties, while positional parameters must match one of the constructors.

You can have multiple named parameters, separated by commas, in the same attribute specification as long as there are matching public fields or properties. This is shown in Figure 28.2. In this case, the attribute specification has one positional parameter, and two named parameters (which matches the public field AuthorName and public property AuthorId ). The constructor which is invoked is constructor 2.

Figure 28.3 shows another example of using the Author attribute. In this there are two positional parameters and one named parameter (which corresponds to the public field AuthorId ). Constructor 1 is invoked instead of constructor 2 in this case.

Figure 28.3. A final example showing how named and positional parameters correspond to public fields/properties and constructors, respectively, in the attribute class.

Before moving to the next section, there are two more points to make about named parameters.

• If you have multiple named parameters, their order does not matter.

   [Author("22 Dec 02", AuthorName="Cheryl", AuthorId=123)] 

  and

   [Author("22 Dec 02", AuthorId=123, AuthorName="Cheryl")] 

  are equivalent.

• All positional parameters must come before any named parameter. This attribute specification:

   [Author(AuthorName="Cheryl", AuthorId=123, "22 Dec 02")] 

  causes a compilation error because of a violation of this rule.

There is one other important rule concerning attribute parameters, be they named or positional “ the types of an attribute parameter must be:

• object

• System.Type

• an enum type

• any of the following simple types: bool , byte , char , double , float , int , long , short , string or

• a 1-dimensional array of any of the above mentioned types.