Aspect that, when applied to a method, defines an exception handler around the whole method and calls a custom method in this exception handler.
Implements
Namespace: PostSharp.Aspects
Assembly: PostSharp.dll
Syntax
[AttributeUsage(AttributeTargets.Assembly|AttributeTargets.Class|AttributeTargets.Struct|AttributeTargets.Constructor|AttributeTargets.Method|AttributeTargets.Property|AttributeTargets.Event|AttributeTargets.Interface, AllowMultiple = true, Inherited = false)]
[MulticastAttributeUsage(MulticastTargets.Method|MulticastTargets.InstanceConstructor|MulticastTargets.StaticConstructor, TargetMemberAttributes = MulticastAttributes.AnyVisibility|MulticastAttributes.AnyScope|MulticastAttributes.NonAbstract|MulticastAttributes.Managed, AllowMultiple = true)]
[HasInheritedAttribute]
[AspectConfigurationAttributeType(typeof(OnExceptionAspectConfigurationAttribute))]
[Serializer(null)]
public abstract class OnExceptionAspect : MethodLevelAspect, IMethodLevelAspectBuildSemantics, IAspectBuildSemantics, IValidableAnnotation, IOnExceptionAspect, IMethodLevelAspect, IAspectRemarks
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. To replace the current exception by another one, set this property to the new exception and set the FlowBehavior property to ThrowException, or throw a new exception from the handler. If you need to ignore the exception, set the FlowBehavior property to Continue.
By default, the aspect handles exceptions of any type. To handle only one type of exception, override GetExceptionType(MethodBase).
If you also need to execute logic before the method or when it succeeds, use OnMethodBoundaryAspect, whose OnException(MethodExecutionArgs) advice handles exceptions in the same way.
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 Arguments). - Get the current exception. The current exception is available in the property Exception (only from the OnException(MethodExecutionArgs) advice). You can also replace the exception (see Exception for details).
- Get or set the return value. The return value is available in the ReturnValue property. You can also modify it.
- Change the method control flow. You can change the value of the FlowBehavior property to specify whether the target method should continue to 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 retrieve it in OnSuccess(MethodExecutionArgs). Using MethodExecutionTag is the only way to share state that is both thread-safe and reentrant.
note
All classes implementing IAspect should typically be marked as serializable using the SerializableAttribute or PSerializableAttribute custom attribute. Fields that are only used at runtime (and unknown at compile-time) should be carefully marked with the NonSerializedAttribute or PNonSerializedAttribute custom attribute. When another aspect serializer (such as MsilAspectSerializer) is used, it is not necessary to mark the aspect class as serializable. For more information, see Understanding Aspect Serialization.
Constructors
| Name | Description |
|---|---|
| OnExceptionAspect() |
Properties
| Name | Description |
|---|---|
| SemanticallyAdvisedMethodKinds | Gets or sets which target methods are advised semantically. This affects the behavior of the aspect when it is applied to iterator or async methods, which are compiled into state machines. |
| UnsupportedTargetAction | Gets or sets the action to take when the aspect is applied to an unsupported target method. |
Methods
| Name | Description |
|---|---|
| CreateAspectConfiguration() | Method invoked at build time to create a concrete AspectConfiguration instance specifically for the current Aspect type. |
| GetExceptionType(MethodBase) | Gets the type of exception handled by this aspect. |
| OnException(MethodExecutionArgs) | Method executed after the body of the methods to which this aspect is applied,
when the method failed with an exception, that is, in a |
| 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. |