Microsoft Dynamic AX 2009 : Syntax (part 5) - Macros, Comments & XML Documentation

COM Interoperability

The following code example demonstrates COM interoperability with the XML document type in the Microsoft XML Core Services (MSXML) 6.0 COM component. The example assumes that you’ve installed MSXML. The MSXML document is first instantiated and wrapped in a Dynamics AX COM object wrapper. A COM variant wrapper is created for a COM string. The direction of the variant is into the COM component. The root element and head element variables are declared as COM objects. The example shows how to fill a string variant with an X++ string and then use the variant as an argument to a COM method, loadXml. The statement that creates the head element demonstrates how the Dynamics AX runtime automatically converts Dynamics AX primitive objects into COM variants.

static void Job2(Args _args)
{
    COM doc = new COM("Msxml2.DomDocument.6.0");
    COMVariant rootXml = new COMVariant(COMVariantInOut::In,COMVariantType::VT_BSTR);
    COM rootElement;
    COM headElement;
    ;
    rootXml.bStr("<Root></Root>");
    doc.loadXml(rootXml);
    rootElement = doc.documentElement();
    headElement = doc.createElement("Head");
    rootElement.appendChild(headElement);
    print doc.xml();
    pause;
}

					  

Macros

The macro capabilities in X++ enable you to define and use constants and perform conditional compilation. Macros are unstructured because they are not defined in the X++ syntax. Macros are handled before the source code is compiled. You can add macros anywhere you write source code: in methods and in class declarations.

Table 11 shows the supported macro directives.

#define.MyMacro(SomeValue)

#macro.MyMacro
   print "foo";
   print "bar";
#endmacro

#macrolib.MyMacroLibrary
#MyMacroLibrary

#define.MyMacro("Hello World")
print #MyMacro;

#defdec.MyIntMacro

#undef.MyMacro

#if.MyMacro
print "MyMacro is defined";
#endif

#if.MyMacro(SomeValue)
print "MyMacro is defined and has value: SomeValue";
#endif

#ifnot.MyMacro
print "MyMacro is not defined";
#endif

#ifnot.MyMacro(SomeValue)
print "MyMacro does not have value: SomeValue; or it is not
defined";
#endif

The following example shows a macro definition and reference.

void myMethod()
{
    #define.HelloWorld("Hello World")
;
    print #HelloWorld;
    pause;
}

As we noted in Table 11, a macro library is created under the Macros node in the AOT. The library is included in a class declaration header or class method, as shown in the following example.

class myClass
{
    #MyMacroLibrary1
}
public void myMethod()
{
    #MyMacroLibrary2
    ;
    #MacroFromMyMacroLibrary1
    #MacroFromMyMacroLibrary2
}

A macro can also use parameters. The compiler inserts the parameters at the positions of the placeholders. The following example shows a local macro using parameters.

void myMethod()
{
    #localmacro.add
        %1 + %2
    #endmacro

    print #add(1, 2);
    print #add("Hello", "World");
    pause;
}

When a macro library is included or a macro is defined in the class declaration of a class, the macro can be used in the class and in all classes derived from the class. A subclass can redefine the macro.

Comments

X++ allows single-line and multiple-line comments. Single-line comments start with // and end at the end of the line. Multiple-line comments start with /* and ended with */. You can’t nest multiple-line comments.

You can add reminders to yourself in comments that the compiler picks up and presents to you as tasks in its output window. To set up these tasks, start a single-line comment with the word TODO (all uppercase). Be aware that tasks occurring inside multiple-line comments are treated as commented out, so the compiler doesn’t pick them up.

Here is a code example with comments reminding the developer to add a new procedure while commenting out an existing procedure.

public void myMethod()
{
    //Declare variables
    int value;

//TODO Validate if calculation is really required
/*
    //Perform calculation
    value = this.calc();
*/
    ...
}

XML Documentation

You can document XML methods and classes directly in X++ by writing /// (triple slash) followed by structured documentation in XML format. The XML documentation must be above the actual code.

The contents of XML are strict and must align with the code. The Best Practices tool contains a set of rules that can validate the XML documentation. The supported tags are shown in Table 12.

You can extract the written XML documentation for an AOT project by using the Add-Ins menu option Extract XML Documentation. One XML file containing all the documentation written for the elements inside the project is produced. You can also use this XML file to publish the documentation.

Here is a code example in which XML documentation has been written for a static method on the Global class.

/// <summary>
/// Converts an X++ utcdatetime value to a .NET System.DateTime object.
/// </summary>
/// <param name="_utcDateTime">
/// The X++ utcdatetime to convert.
/// </param>
/// <returns>
/// A .NET System.DateTime object.
/// </returns>
static client server anytype utcDateTime2SystemDateTime(utcdatetime _utcDateTime)
{
    ;
    return CLRInterop::getObjectForAnyType(_utcDateTime);
}