Event-Handling in Dynamics AX 2012

Eine wichtige Neuerung von AX 2012 sind die sogenannten Event-Handler. Diese Event-Handler sind eine elegante Möglichkeit, die Funktionalität von AX 2012 zu erweitern, ohne dabei den Standardcode zu verändern. Dies soll vor allem spätere Releaseupdates von Dynamics AX 2012 erheblich erleichtern.

Prinzipiell unterscheidet man dabei zwischen Event-Handler die vor (PRE) bzw. nach (POST) dem Originalcode ausgeführt werden sollen, wobei jede der beiden Varianten ihre eigenen Möglichkeiten bieten. Pre-Event-Handler können die Original-Parameter der auslösenden Methode verändern wogegen Post-Event-Handler den Rückgabewert der auslösenden Methode verändern können.

Die folgenden drei Beispiele sollen die Verwendung dieser Event-Handler verdeutlichen.

Beispiel 1: Es soll der Inhalt des Feldes Suchbegriff der Artikeldetails dahingehend geprüft werden, daß zumindest 5 Zeichen eingegeben wurden.

In früheren Versionen von Dynamics AX hätte man für eine solche Prüfung üblicherweise die validateWrite der Tabelle inventTable verändert - in AX 2012 erstellen wir statt dessen eine Klasse MyInventTableEventHandler mit einer Methode inventTableValidateWritePostEventHandler und verknüpfen die Methode mit der validateWrite.

Schritt 1: Erstellen der Klasse und Methode

class MyInventTableEventHandler
{
}

public static void inventTableValidateWritePostEventHandler(XppPrePostArgs _args)
{
    inventTable inventTable;

    inventTable = _args.getThis();

    if (strLen(inventTable.NameAlias) < 5)
    {
        warning(strFmt('Field "%1" should contain at least 5 characters.', fieldPName(inventTable, NameAlias)));

        // Set return value of the original method
        _args.setReturnValue(false);
    }
}

Schritt 2: Verknüpfen der Methode mit der Tabelle

Per Drag & Drop ziehen wir die Methode inventTableValidateWritePostEventHandler auf die validateWrite der inventTable.

Nun müssen wir noch festlegen, wann dieses Event ausgeführt werden soll, in unserem Fall wählen wir die Variante Post.

Beispiel 2: Auch in diesem Beispiel soll der Inhalt des Feldes Suchbegriff der Artikeldetails geprüft werden, allerdings nicht erst beim Speichern des Datensatzes sondern gleich nach der Eingabe.

In früheren Versionen von Dynamics AX hätten wir hierfür die Methode validateField entspechend angepasst, in meinem Beispiel verwende ich die Methode validateField als Auslöser des Events.

Im Gegensatz zum Beispiel 1 verfügt die Methode validateField über zwei Paramter, die selbstverständlich auch durch Event-Handler genutzt werden können. Auch dieses Mal handelt es sich um einen Post-Event-Handler.

Schritt 1: Erstellen der Klasse und Methode

class MyInventTableEventHandler
{
}

public static void inventTableValidateFieldPostEventHandler(XppPrePostArgs _args)
{
    inventTable inventTable;
    FieldName fieldName;
    int arrayIndex;

    if(_args.getCalledWhen() != XppEventHandlerCalledWhen::Post)
        throw error(error::wrongUseOfFunction(funcName()));

    inventTable = _args.getThis();

    // First parm _fieldName of the original method
    fieldName = _args.args().valueIndex(1);

    // Second parm _arrayIndex of the original method
    arrayIndex = _args.args().valueIndex(2);

    switch(fieldName)
    {
        case fieldStr(InventTable, NameAlias):
            if (strLen(inventTable.NameAlias) < 5)
            {
                warning(strFmt('Field "%1" should contain at least 5 characters.', fieldPName(inventTable, NameAlias)));

                // Set return value of the original method
                _args.setReturnValue(false);
            }
            break;
    }
}

Schritt 2: Verknüpfen der Methode mit der Tabelle

Per Drag & Drop ziehen wir die Methode inventTableValidateFieldPostEventHandler auf die validateField der inventTable. Nun müssen wir noch festlegen, wann dieses Event ausgeführt werden soll, in unserem Fall wählen wir die Variante Post.

Hinweis: Alternativ zu _args.args().valueIndex() kann man die Parameter der Original-Methode auch wie folgt abfragen:

    // First parm _fieldName of the original method
    fieldName = _args.getArg(identifierStr(_fieldName));
    // Second parm _arrayIndex of the original method
    arrayIndex = _args.getArg(identifierStr(_ArrayIndex));

Beispiel 3: Bei Aktualisieren eines Datensatzes in den Artikeldetails soll das Feld Suchbegriff mit der Artikelnummer gefüllt werden, wenn das Feld Suchbegriff leer ist.

In Versionen vor Dynamics AX 2012 hätten wir gewohnterweise die update-Methode verändert, in dieser Version verwenden wir Sie als Auslöser des Events.

Schritt 1: Erstellen der Klasse und Methode

class MyInventTableEventHandler
{
}

public static void inventTableUpdatePreEventHandler(XppPrePostArgs _args)
{
    inventTable inventTable;

    if(_args.getCalledWhen() != XppEventHandlerCalledWhen::Pre)
        throw error(error::wrongUseOfFunction(funcName()));

    inventTable = _args.getThis();

    if( !inventTable.NameAlias)
    {
        inventTable.NameAlias = inventTable.ItemId;
    }
}

Schritt 2: Verknüpfen der Methode mit der Tabelle

Per Drag & Drop ziehen wir die Methode inventTableUpdatePreEventHandler auf die update der inventTable. Nun müssen wir noch festlegen, wann dieses Event ausgeführt werden soll, in unserem Fall wählen wir die Variante Pre.

Weitere Hinweise

Selbstverständlich kann eine Klasse mehrere Methoden enthalten die als Event-Handler benutzt werden, so könnten wir also alle drei oben beschriebenen Methoden in nur einer Klasse kombinieren.

Weiters ist es natürlich auch möglich, eine Event-Handler-Methode derart zu programmieren, als daß sie sowohl als Pre- als auch als Post-Event-Handler verwendet werden kann. Abgefragt werden kann dies - wie in den obigen Beispielen ansatzweise dargestellt über die Abfrage von getCalledWhen der XppPrePostArgs.
Auch können wir mehrere Event-Handler mit eine Methode verknüpfen, die Reihenfolge der Ausführung ist allerdings nicht steuerbar.