PostSharp6.4/Developing Custom Aspects/Aspect Configuration

Aspect Configuration

Configuration settings of aspects determine how they should be processed by their weaver. Configuration settings are always evaluated at build time. Most aspects have one or many of them. For instance, the aspect type OnExceptionAspect has a configuration setting determining the type of exceptions handled with this aspect.

There are two ways to configure an aspect: declarative and imperative.

Declarative Configuration

You can configure an aspect declaratively by applying the appropriate custom attribute on the aspect class. Aspect configuration attributes are in the namespace PostSharp.Aspects.Configuration. Every aspect type has its corresponding type of configuration attribute. The name of the custom attribute starts with the name of the aspect and has the suffix ConfigurationAttribute. For instance, the configuration attribute of the aspect class OnExceptionAspect is OnExceptionAspectConfigurationAttribute.

Declarative configuration has always precedence over imperative configuration: if some property of the configuration custom attribute is set on the aspect class, or on any parent, the corresponding imperative semantic will not be evaluated.

Once a configuration property has been set in a parent class, it cannot be overwritten in a child class.

Note that these restrictions are enforced at the level of properties. If a property of a configuration custom attribute is not set in a parent class, it can still be overwritten in a child class or by an imperative semantic.

Imperative Configuration

A second way to configure an aspect class is to override its configuration methods or set its configuration property.

Note Note

Imperative configuration is only available when you target the full .NET Framework. It is not available for Silverlight or the Compact Framework.

Benefits of Imperative Configuration

The advantage of imperative configuration is that it can be arbitrarily complex (since the code of the configuration method is executed inside the weaver). Specifically, it allows the configuration to be dependent on how the aspect is actually used, for instance the configuration can depend on the value of a property of the aspect custom attribute.

Implementation Note

Under the hood, aspects implement the method IAspectBuildSemantics.GetAspectConfiguration(Object). This method should return a configuration object, derived from the class AspectConfiguration. Every aspect class has its own aspect configuration class. For instance, the configuration attribute of the aspect class OnExceptionAspect is OnExceptionAspectConfiguration. The aspect type OnExceptionAspect implements IAspectBuildSemantics.GetAspectConfiguration(Object) by creating an instance of OnExceptionAspectConfiguration, then it invokes the method OnExceptionAspect.GetExceptionType(MethodBase) and copies the return value of this method to the property OnExceptionAspectConfiguration.ExceptionType. Therefore, there are two ways to configure an aspect: either by overriding configuration methods and setting configuration properties (these methods and properties are provided by the framework for convenience only), or by implementing the method IAspectBuildSemantics.GetAspectConfiguration(Object). If your aspect does not derive from the aspect class OnExceptionAspect, but directly implements the aspect interface IOnExceptionAspect, you can use only the later method.