Multicasting of custom attributes

The multicasting feature enables to apply the same custom attribute to many elements using a single declaration of the custom attribute. The benefit is obvious: write one line of code where you should write one hundred.

Let's see how it works.

Using a custom attribute

A basic example

Let's take inspiration from the sample PostSharp.Sample.Trace, which is shipped with PostSharp. We have a custom attribute [Trace] that allows to write something to the console. We can set up the trace category.

The most natural way is to add the [Trace] attribute to each method:

namespace BusinessLayer
{
  public class CustomerProcesses
  {
   [Trace("Business")]
   public Customer CreateCustomer(string firstName, string lastName) { ... }

   [Trace("Business")]
   public void DeleteCustomer(long customerId) { ... }
  }

  public class LoanProcesses
  {
   [Trace("Business")]
   public Loan CreateLoan(long customerId, decimal amount, int periods, DateTime firstPaymentDate ) { ... }

   [Trace("Business")]
   public void DeleteLoan(long loanId) { ... }
  }
}

This seems classical but it forces us to duplicate code. And what if each class has tenths of methods? We can do the same with less code. The following snippet is exactly equivalent to the previous one:

namespace BusinessLayer
{
  
  [Trace("Business")]
  public class CustomerProcesses
  {
   public Customer CreateCustomer(string firstName, string lastName) { ... }
   public void DeleteCustomer(long customerId) { ... }
  }

  [Trace("Business")]
  public class LoanProcesses
  {
   public Loan CreateLoan(long customerId, decimal amount, int periods, DateTime firstPaymentDate ) { ... }
   public void DeleteLoan(long loanId) { ... }
  }
}

Why does it work? Because PostSharp 'knows' that the trace attribute applies to method.

When the custom attribute is applied to a container (a type, in this case, is a container of methods), the custom attribute is multicasted recursively to all methods it contains.

So why not applying the custom attribute to the assembly? The assembly is a container of types, which are containers of methods, so all methods would be traced. But it's not what we want: we want to trace only the business layer. Fortunately, we can use wildcards to solve this problem.

Again, the following snipset is equivalent to the ones above:

[assembly: Trace("Business", AttributeTargetTypes="BusinessLayer.*")]

namespace BusinessLayer
{
  public class CustomerProcesses
  {
   public Customer CreateCustomer(string firstName, string lastName) { ... }
   public void DeleteCustomer(long customerId) { ... }
  }

  public class LoanProcesses
  {
   public Loan CreateLoan(long customerId, decimal amount, int periods, DateTime firstPaymentDate ) { ... }
   public void DeleteLoan(long loanId) { ... }
  }
}

We have used the AttributeTargetTypes property to limit the set of methods to which the custom attribute is applied. Without this property, the custom attribute would have been applied to each method of the whole assembly.

Thanks to the properties AttributeTargetTypes, AttributeTargetMembers and AttributeTargetElements and AttributeTargetMemberAttributes you can restrict the set of elements to which custom attributes are multicasted. When they are not specified, a 'match all' is assumed.

Priority of attributes

Now say that our business process classes implement the interface IDisposable. We do not want to trace the Dispose method.

We can use the following code:

[assembly: Trace("Business", AttributeTargetTypes="BusinessLayer.*", AttributePriority = 1)]
[assembly: Trace(AttributeTargetMembers="Dispose", AttributeExclude = true, AttributePriority = 2)]

The first line includes all types and methods of the business layer, the second line excludes the methods named "Dispose".

The AttributeExclude property tells that set of custom attributes multicasted on an element should be cleared. So it actually removes custom attributes.

Note the AttributePriority property in both lines. It tells that the first line should be processed first, then the second one. So first we include all, then we exclude. If you think it's stupid to add it, you are right (it would be so nicer without!), but the C# compiler does not guaranty that the custom attributes are written (into the binary) in the same order as in the source file. That is, the order between lines could (and will) be lost during compilation. So if you have to make an inclusion-exclusion and not an exclusion-inclusion, you have to specify the AttributePriority property.

The AttributePriority property determines in which order the custom attributes are processed by the multicasting engine, and nothing else.

If you do not like to use named methods (there are good reasons for this), another way to perform the same is to apply the exclusion attribute directly on Dispose methods:

[assembly: Trace("Business", AttributeTargetTypes="BusinessLayer.*")]

namespace BusinessLayer
{
  public class CustomerProcesses : IDisposable
  {
   public Customer CreateCustomer(string firstName, string lastName) { ... }
   public void DeleteCustomer(long customerId) { ... }

   [Trace(AttributeExclude=true)]
   public void Dispose() { ... }
  }

  public class LoanProcesses : IDisposable
  {
   public Loan CreateLoan(long customerId, decimal amount, int periods, DateTime firstPaymentDate ) { ... }
   public void DeleteLoan(long loanId) { ... }

   [Trace(AttributeExclude=true)]
   public void Dispose() { ... }
  }
}

The rule is:

Custom attributes applied on innermost element have always greater priority (i.e. is always processed after and has greater force) than custom attributes applied on outer elements.

Suppose now that you want to assign a special trace category to the methods of the namespace BusinessLayer.Internals. You can achieve this with the following code:

[assembly: Trace("Business", AttributeTargetTypes="BusinessLayer.*", AttributePriority = 1)]
[assembly: Trace("BusinessInternals", AttributeTargetTypes="BusinessLayer.Internals.*", 
                   AttributeReplace = true, AttributePriority = 2)]

The AttributeReplace property clears the set of custom attributes applied to an element and add a new one. Without AttributeReplace, a new custom attribute instance would be added. AttributeReplace is automatically implied if the custom attribute does not allow multiple instances (see below [MulticastAttributeUsage]).

Developing a multicasting custom attribute

Now that you know how to use multicasting custom attributes, let's see how to develop them.

First, note it works only inside PostSharp and with custom attributes that are derived from MulticastAttribute. All abstract custom attributes defined in PostSharp Laos are derived from MulticastAttribute, so they inherit its compile-time behavior.

Just like normal custom attribute classes should be decorated with the [AttributeUsage] custom attribute, classes derived from MulticastAttribute should be decorated with [MulticastAttributeUsage]. When applied on the TraceAttribute class, the [MulticastAttributeUsage] custom attribute determines how the [Trace] attribute could be used. Since, say, we can trace only methods and constructors, we will use:

[MulticastAttributeUsage( MulticastTargets.Method | MulticastTargets.Constructor )]
public sealed class TraceAttribute : MulticastAttribute { ... }

Using [MulticastAttributeUsage], you can also specify:

• whether multiple instances are allowed on a single element (property AllowMultiple),
• whether it can be applied on elements defined in external assemblies (property AllowExternalAssemblies),
• whether a custom attribute should be emitted in the transformed assembly (after multicasting) -- this makes sense if the custom attribute is also used at runtime.

But this is only information for PostSharp. You should still tell the C# compiler that it is valid to apply the custom attribute at assembly-level, at type-level or at method-level, and that having many instances of the attribute is allowed.

In order to tell the C# compiler that the custom attribute may also be added on method containers (types, assembly, properties, events), you should use the standard [AttributeUsage] custom attribute. You should also tell the compiler that multiple instances of the custom attribute are allowed, even if you forbidded it using [MulticastAttributeUsage]. Why? Otherwise the user of your custom attribute could not use declare many custom attributes on assembly- or type-level, eventually using wildcards. What is important is uniqueness on the target element, and this is enforced by the [MulticastAttributeUsage] custom attribute.

So finally:

[AttributeUsage( AttributeTargets.Assembly | AttributeTargets.Module |
                 AttributeTargets.Class | AttributeTargets.Struct | 
                 AttributeTargets.Method | AttributeTargets.Constructor,
                 AllowMultiple = true, Inherited = false )]
[MulticastAttributeUsage( MulticastTargets.Method | MulticastTargets.Constructor, AllowMultiple=true )]
public sealed class TraceAttribute : MulticastAttribute { ... }

You should quality your own multicast custom attributes both by [AttributeUsage] and [MulticastAttributeUsage].

If the previous rule is correct, why is it optional to qualify the aspects we define using PostSharp Laos? Well, because Laos does it for you. Custom attributes are already defined in the base classes.

[MulticastAttributeUsage] is inherited from the base class to derived classes. Usage can be restricted, but not enlarged, in derived classed.

That's nearly all. Of course this mechanism could still be enhanced (it would be nice for instance to be able to specify its own filter). This will be for a further version :).

Happy multicasting!

Gael