Class OnMethodBoundaryAspect

The OnMethodBoundaryAspect aspect results in the target method being wrapped in a try ... catch ... finally block. You can implement four advices: OnEntry(MethodExecutionArgs), executed at the beginning of the block; OnSuccess(MethodExecutionArgs), executed only when the method succeeds (that is, when it does not result in an exception); OnException(MethodExecutionArgs), invoked when the method results in an exception; and OnExit(MethodExecutionArgs), always executed after method execution (whether the method resulted in an exception or not).

Schematically, the aspect transforms the original method as follows:

int MyMethod(object arg0, int arg1)
{
OnEntry();
try
{
// Original method body.
OnSuccess();
return returnValue;
}
catch ( Exception e )
{
OnException();
}
finally
{
OnExit();
}
}

Note that this code is only schematic. The generated instructions are more complex because they have to cope with parameter boxing and control flow modification, among others.

On async and iterator methods, the aspect is applied by default to the code of the method as written in the source, not to the compiler-generated code that creates the state machine (see SemanticallyAdvisedMethodKinds). Two more advices are then available: OnYield(MethodExecutionArgs), invoked when the method is suspended by an await or yield return statement, and OnResume(MethodExecutionArgs), invoked when it resumes.

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.

You can apply a method boundary aspect to a method that is outside your assembly. If you do, all calls to that method are intercepted and replaced with calls to a new method, in your assembly, that calls the original method. When this happens, by-reference parameters (ref) undergo special treatment similar to what happens in MethodInterceptionAspect.