OnExceptionAspect Class - PostSharp 4.3 Documentation

System.Object
  System.Attribute
    PostSharp.Extensibility.MulticastAttribute
      PostSharp.Aspects.Aspect
        PostSharp.Aspects.MethodLevelAspect
          PostSharp.Aspects.OnExceptionAspect

C#

Copy

[SerializableAttribute]
public abstract class OnExceptionAspect : MethodLevelAspect, 
	IOnExceptionAspect, IMethodLevelAspect, IAspect

	Name	Description
	OnExceptionAspect	Initializes a new instance of the OnExceptionAspect class

	Name	Description
	ApplyToStateMachine	Determines how the aspect should behave when it is applied to an iterator or async methods, which are compiled into state machines.
	AspectPriority	Gets or sets the weaving priority of the aspect. (Inherited from Aspect.)
	AttributeExclude	If true, indicates that this attribute removes all other instances of the same attribute type from the set of elements defined by the current instance. (Inherited from MulticastAttribute.)
	AttributeInheritance	Determines whether this attribute is inherited (Inherited from MulticastAttribute.)
	AttributePriority	Gets or sets the priority of the current attribute in case that multiple instances are defined on the same element (lower values are processed before). (Inherited from MulticastAttribute.)
	AttributeReplace	Determines whether this attribute replaces other attributes found on the target declarations. (Inherited from MulticastAttribute.)
	AttributeTargetAssemblies	Gets or sets the assemblies to which the current attribute apply. (Inherited from MulticastAttribute.)
	AttributeTargetElements	Gets or sets the kind of elements to which this custom attributes applies. (Inherited from MulticastAttribute.)
	AttributeTargetExternalMemberAttributes	Gets or sets the visibilities, scopes, virtualities, and implementation of members to which this attribute applies, when the member is external to the current module. (Inherited from MulticastAttribute.)
	AttributeTargetExternalTypeAttributes	Gets or sets the visibilities of types to which this attribute applies, when this type is external to the current module. (Inherited from MulticastAttribute.)
	AttributeTargetMemberAttributes	Gets or sets the visibilities, scopes, virtualities, and implementation of members to which this attribute applies. (Inherited from MulticastAttribute.)
	AttributeTargetMembers	Gets or sets the expression specifying to which members this instance applies. (Inherited from MulticastAttribute.)
	AttributeTargetParameterAttributes	Gets or sets the passing style (by value, out or ref) of parameters to which this attribute applies. (Inherited from MulticastAttribute.)
	AttributeTargetParameters	Gets or sets the expression specifying to which parameters this instance applies. (Inherited from MulticastAttribute.)
	AttributeTargetTypeAttributes	Gets or sets the visibilities of types to which this attribute applies. (Inherited from MulticastAttribute.)
	AttributeTargetTypes	Gets or sets the expression specifying to which types this instance applies. (Inherited from MulticastAttribute.)
	SerializerType	Gets or sets the Type of the serializer (a type derived from AspectSerializer) used to serialize the aspect instance at build time and deserialize it at runtime. (Inherited from Aspect.)

	Name	Description
	CompileTimeInitialize	Method invoked at build time to initialize the instance fields of the current aspect. This method is invoked before any other build-time method. (Inherited from MethodLevelAspect.)
	CompileTimeValidate(Object)	Method invoked at build time to ensure that the aspect has been applied to the right target. (Inherited from MethodLevelAspect.)
	CompileTimeValidate(MethodBase)	Method invoked at build time to ensure that the aspect has been applied to the right target. (Inherited from MethodLevelAspect.)
	CreateAspectConfiguration	Method invoked at build time to create a concrete AspectConfiguration instance specifically for the current Aspect type. (Overrides Aspect.CreateAspectConfiguration().)
	GetAspectConfiguration	Method invoked at build tome to get the imperative configuration of the current Aspect. (Inherited from Aspect.)
	GetExceptionType	Gets the type of exception handled by this aspect.
	OnException	Method executed after the body of methods to which this aspect is applied, in case that the method resulted with an exception (i.e., in a catch block).
	RuntimeInitialize	Initializes the current aspect. (Inherited from MethodLevelAspect.)
	SetAspectConfiguration(AspectConfiguration, Object)	Method invoked at build time to set up an AspectConfiguration object according to the current Aspect instance and a specified target element of the current aspect. (Inherited from MethodLevelAspect.)
	SetAspectConfiguration(AspectConfiguration, MethodBase)	Method invoked at build time to set up an AspectConfiguration object according to the current Aspect instance and a specified target element of the current aspect. (Overrides MethodLevelAspect.SetAspectConfiguration(AspectConfiguration, MethodBase).)

	Name	Description
	QueryInterface<T>	Gets the implementation of a specified interface for the specified object. (Defined by QueryInterfaceExtensions.)

The OnExceptionAspect aspect adds an exception handler to the method to which it is applied. It allows you to easily encapsulate exception handling policies as a custom attribute.

The most important method is OnException(MethodExecutionArgs). It is the exception handler in itself.

The current exception is available from the Exception property of the MethodExecutionArgs> object. This property is read-only. If you need to replace the current exception by another one, you should throw a new exception from the handler. If you need to ignore the exception, set the FlowBehavior property to Continue.

An object of type MethodExecutionArgs is passed to every advice of this aspect. This object allows you to:

Get or set arguments . Input and output arguments are available on the property Arguments . You can change output ( out ) and by-reference ( ref ) arguments, but not input arguments. If you need to modify arguments passed by value, consider using a MethodInterceptionAspect . (see property );
Get the current exception . The current exception is available on property Exception , but from the OnException(MethodExecutionArgs) advice. You cannot replace the exception by setting this property. Throw a new exception from the aspect if you need to replace the current exception.
Get or set the return value . The return value is available on the ReturnValue property.
Change the method control flow . You can change the value of the FlowBehavior property to specify whether the target method should execute after the execution of the current advice. This may be useful to implement a caching aspect or an exception handler.
Share state between advices . You can use the MethodExecutionTag property to store state between the execution of different advices related to the same execution of a method. For instance, you can store a cache key in OnEntry(MethodExecutionArgs) and find it back on OnSuccess(MethodExecutionArgs) . Using MethodExecutionTag is the only way to share state that is both thread-safe and reentrant. All other implementations are buggy.

Note
All classes implementing IAspect should typically be marked as serializable using the custom attribute SerializableAttribute . Fields that are only used at runtime (and unknown at compile-time) should be carefully marked with the custom attribute NonSerializedAttribute . When PostSharp is used on a platform that does not support aspect serialization (such as .NET Compact Framework, Silverlight, or Windows Phone), or when another aspect serializer is used, it is not necessary to mark the aspect class as serializable. For more information, see Aspect Serialization .

Note

All classes implementing IAspect should typically be marked as serializable using the custom attribute SerializableAttribute . Fields that are only used at runtime (and unknown at compile-time) should be carefully marked with the custom attribute NonSerializedAttribute . When PostSharp is used on a platform that does not support aspect serialization (such as .NET Compact Framework, Silverlight, or Windows Phone), or when another aspect serializer is used, it is not necessary to mark the aspect class as serializable. For more information, see Aspect Serialization .

Reference

PostSharp.Aspects Namespace

PostSharp.Aspects.Configuration.OnExceptionAspectConfigurationAttribute

Other Resources

Conceptual Documentation: Aspect Serialization