Event Handler Nodes in the AOT

Article
05/18/2015

Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

You can subscribe methods as event handlers in two locations in the Application Object Tree (AOT):

Under a delegate node
Under a method node

Under a Delegate Node

A class node, such as AOT > Classes > MyClass, can have delegate nodes directly underneath it.

The following rules apply to delegates in the AOT:

A delegate declaration can have the same type of parameters as a method.
A delegate declaration must return void.
A delegate declaration cannot include any modifiers, such as public, protected, private, or static.
A delegate cannot contain code.

The following code shows an example of a delegate declaration.

    delegate void myDelegateReportBalanceEvent(utcDateTime _when, str _name)
    {
        // There is never any code here inside a delegate.
    }

For more information, see Walkthrough: Subscribing an Event Handler to a Delegate in the AOT.

Under a Method Node

In the AOT, you can assign a method as an event handler for the pre-method event or the post-method event of another method. We say the event handler subscribes to an event of the host method.

The nodes that represent the subscription of an event handler to a host method are underneath the node for the host method. AOT elements such as classes, tables, and forms can have methods.

Note

Event handlers cannot subscribe to the classDeclaration, new, and finalize nodes under a class.

All event handlers that subscribe to a method must return void.

Event handlers for host methods can use one of two parameter signatures:

One parameter of the type XppPrePostArgs
The same parameters that are on the host method that the event handler subscribes to

The following code shows an example of an event handler that has the XppPrePostArgs class as the only parameter.

    static public void myEventHandler(XppPrePostArgs _ppArgs)
    {
        // Add useful code here.
    }

Note

In Microsoft Dynamics AX 2012 R2, the parameter signature changed for the constructor of the XppPrePostArgs class. The signature now is a specifier that is generated by the system. You should not try to construct your own instance of the XppPrePostArgs class. For more information, see new Method.

Pre-Event Handlers and Post-Event Handlers

An event handler that is underneath a method node can run either before or after the method runs. You control the timing by setting the CalledWhen property on the event handler node. The CalledWhen property has two values:

Pre – The event handler runs before the method starts.
Post – The event handler runs after the method ends.

For more information, including code samples, see How to: Modify Parameter Values in a Pre-Method Event Handler and How to: Modify the Return Value in an Post-Method Event Handler.

The XppPrePostArgs Class Parameter

A pre-method event handler that has only an XppPrePostArgs parameter can inspect and change the values of the parameters. The changes take effect before the parameters are passed to the host method that is being called. See the getArg and setArg methods.

A post-method event handler that has only an XppPrePostArgs parameter can inspect and change the return value from the method. The change takes effect before the value is returned to the caller method. See the getReturnValue and setReturnValue methods.

When an XppPrePostArgs object is used, the values of the parameters and the return type can be changed by the event handler. The values can be changed even if the parameters and return type are value types, such as an integer or string. If a parameter or a return type is a reference to an object, the event handler can call methods on the object and could change the state of the object.

Matched Parameters Without XppPrePostArgs

A pre-method or post-method event handler can have the same parameter signature as the host method that it subscribes to. This is the alternative to the event handlers having just one parameter of type XppPrePostArgs.

There are two types of parameters that are treated differently by event handlers:

Value types, such as an integer or string
Reference types, such as an instance of a class

A pre-method event handler receives the same parameter values that the host method receives. However, this event handler cannot modify the value of any value type parameters that go to the host method.

A pre-method event handler that receives a reference type parameter can call methods on the referenced object. If those calls cause a state change for the object, the change is visible to the host method after the event handler ends.

A post-method event handler receives the same parameter values that the host method received. However, this event handler does not receive the return value from the host method. This event handler can only log that the host method was completed without suffering an uncaught exception.

Event Handler Considerations

The methods that you subscribe as event handlers must have the static modifier. This section provides more details about event handlers.

Each event handler for a delegate must have the same parameter signature as the delegate.

Event Handlers and .NET Interop

An event handler can also be a .NET Framework method that is written in C# or Visual Basic. For more information, see Walkthrough: Creating an Event Handler in Visual Studio.

X++ delegates can have the following parameter types:

Primitive types such as str and int.
Starting in Microsoft Dynamics AX 2012 R2, complex types in X++:
- Classes.
- Tables.
- Enums.
.NET Framework types, such as System.Random.

An event handler method that is written in C# can have a parameter that is a proxy for an X++ class, table, or enum.

Event Handler Sequence

When an event causes a set of event handlers to run, the following rules apply:

The system runs the event handlers in series. Therefore, the second event handler runs after the first event handler ends.
The system does not run event handlers in any particular sequence. Therefore, do not write code that depends on a particular event handler sequence.

If you need the methods for the event handlers to run in a particular sequence, you can have one event handler that calls the other methods in the desired sequence. The other methods do not have to be formal event handlers.

An event handler can be subscribed to by other event handlers. You can chain event handlers together to force them to run in a particular sequence. However, if you use this chain design, you risk recursion. The chain design is unnecessary, and it is difficult to visualize and understand in the AOT.

Subscriber and Publisher Must Run on Same Tier

Event handlers can run only on the same tier as the publisher class of the delegate runs on. For example, if the publisher class has its RunOn property set to Server, its delegate cannot call a subscribed event handler method that is declared with the client keyword of X++.

Tip

If your application must make calls across a tier boundary, you should use regular X++ method invocation.

In This Section

How to: Modify Parameter Values in a Pre-Method Event Handler

How to: Modify the Return Value in an Post-Method Event Handler

Walkthrough: Subscribing an Event Handler to a Delegate in the AOT