AxBuild.exe for Parallel Compile on AOS of X++ to p-code

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

AxBuild.exe can accomplish a full compile of all X++ code, into AX p-code, many times faster than the traditional compile that you start from the MorphX client menu. AxBuild.exe is run on the Application Object Server (AOS) tier at a cmd.exe command prompt. This topic explains what AxBuild.exe does and how to use it.

The AxBuild.exe utility program involves compiles to p-code only, and it does not go further by compiling to .NET Framework CIL.

AxBuild.exe became available in cumulative update 7 for Microsoft Dynamics AX 2012 R2.

A.  General Architecture

A.1  Compiling on the Server Tier

AxBuild.exe is installed in the same directory with ax32serv.exe, which is the program name for the AOS. Despite the 32 in its name, ax32serv.exe is a 64 bit program. As a 64 bit program, ax32serv.exe can address much more active memory than the 32 bit client ax32.exe can. The larger amount of active memory might be important for full X++ compiles that involve an extremely large amount of X++ source code.

AxBuild.exe starts several new but temporary instances of the AOS. From the Registry, each temporary AOS uses the same configuration information that is used by a permanent AOS that you identify with the /aos parameter. This is one reason why AxBuild.exe must be run by an account that has no less security authority than the account that runs the permanent AOS has.

Server configuration displays the AOS instance number for the /aos parameter

AxBuild.exe coordinates the work of every temporary AOS that it starts. It tells each AOS which pieces of the full X++ compile to accomplish. It gathers the results from each AOS and reports them to the console and a log file.

Architecture of the X++ compile on the AOS tier

An earlier compile option involved new but temporary instances of ax32serv.exe to which you could pass a now obsolete parameter. The obsolete parameter is shown in the following command line:
 ax32serv.exe -startupcmd=CompileAll.

A.2  Contrast with Compiling on the Client

In the past to accomplish a full X++ compile you had to click a menu in the MorphX client, such as Build > Compile. This is a three tier operation which is burdened with transferring data between the client and the AOS. In contrast, the AxBuild.exe approach is only a two tier operation. One reason the AxBuild.exe approach is faster is that it eliminates the data transfers over the network, or over local RPCs, between the AOS and the client.

Compiling on the client does not provide any way to share the workload among several applications. In contrast, AxBuild.exe starts several AOS applications which all run concurrently, which all accomplish parts of the full compile.

As a matter of common practice, the AOS host computer hardware is often more powerful than client computers are. The AOS host typically has more active memory, and has more cores for parallel processing.

Architecture of the X++ compile on the client tier

The MorphX client you can quickly compile an individual X++ method. These partial compilations are extremely efficient for the developer who is adding and fixing a method through cycles of coding then testing. In contrast, AxBuild.exe cannot compile any mere subset of the X++ code on the system.

The MorphX client remains the only option for compiling AX p-code to .NET CIL.

B.  Performance Gain

In this section we present performance data for AxBuild.exe. Every environment is different, and the performance speeds we see in our tests probably differ from what you see.

In our performance test of AxBuild.exe, we measured a 92% reduction in the wall clock time that was necessary to complete a full X++ compilation. Stated another way, AxBuild.exe completed the compilation 13 times faster than the MorphX client did on the same hardware. The software and hardware specifications for our test were as follows:

• One server computer that had both AX client and AOS installed, and had SQL installed:

  • Microsoft Dynamics AX 2012 R2 with cumulative update 7.

  • Microsoft SQL Server 2012 SP1 Enterprise (no limit on memory).

  • Microsoft Windows Server 2012.

• The computer hardware had the following specifications:

  • 4 processor cores, at 3.7 gigahertz.

  • Hyper-threading enabled, which logically doubles the number of cores.

  • 32 gigabytes of active memory.

  • 6.0 gigabits SATA controller.

  • Virtual page caching disabled.

Given the hardware available, AxBuild.exe decided to start 9 temporary AOS workers.

The wall clock time for AxBuild.exe was compared to the time for a legacy client-side full X++ compile. The results were as follows:

• AxBuild.exe:    10.7 minutes.

• MorphX client:    146.0 minutes.

• 146.0  /  10.7  =  13.6

From another measurement we took, a single AOS worker runs 28% faster for not having to transfer information to the MorphX client and back during the full compile.

C.  How to Run AxBuild.exe

Preparations

The following preparations are necessary before you can run AxBuild.exe:

• You must have completed the installation of cumulative update 7 for Microsoft Dynamics AX 2012 R2. This must include a re-initialization of the model store database that you run manually, by using either axutil.exe schema or the newer PowerShell equivalent. For more information, see Apply updates to database, AOS, and clients or How to: Create, Drop, or Reinitialize a Model Store.

• You must ensure that the account which will run AxBuild.exe has no less authority than has the account that runs the permanent AOS.

• You must ensure that the option for the hot-swapping of .NET assemblies is turned off in the AOS configuration you choose to use. See the /aos parameter on AxBuild.exe.

• You must establish and populate the directory that will be referred to by the /altbin parameter.

Example Command Line

Here is an example command line for AxBuild.exe that might match the command line you need in your particular environment. The line is artificially wrapped here for better display.

axbuild.exe  xppcompileall  /s=01 
     /altbin="C:\Program Files (x86)\Microsoft Dynamics AX\6.0\Client\Bin"

D.  Outputs from AxBuild.exe

D.1  Outputs to the Console

AxBuild.exe reports its progress to the console through the stdout handle. The stderr handle is not used.

Each AOT element is reported at the moment it is compiled. Some elements can be reported repeatedly at different times before they successfully compile. These repetitions are sometimes necessary because full metadata is not always available to satisfy all dependencies until later phases of the compilation.

D.2  Output Log Files

AxBuild.exe generates two log files. You can control where the log files are written by using the /log parameter. By default the files are written to the Server\...\Log\ subdirectory under the installation directory of the AOS. Here is a common example of what the specific default path might be:
 
 C:\Program Files\Microsoft Dynamics AX\60\Server\MicrosoftDynamicsAX\Log\

The following table describes the two log files.

D.3  Temporary Files

AxBuild.exe writes temporary files to the %TEMP% directory. These files include many details about the process. By default these files are deleted by AxBuild.exe shortly before it ends. However, you can keep the files by using the /nocleanup parameter.

E.  Parameters for AxBuild.exe

The parameter names are not case-sensitive.

In all cases where the parameter name takes an accompanying value, an = sign is used to join them together, as for example /aos=01.

AxBuild.exe always returns 0.

E.1  Description of Each Parameter

The following table describes the parameters that you can or must pass into AxBuild.exe.

F.  Constraints of Compiling on the AOS

F.1  .NET Objects Cannot be Instantiated

When the X++ compiler starts, it performs special compiles on a few special classes. These classes include Application, Infolog, and ClassFactory. When these special classes are compiled during a compile on the AOS tier, they fail if any custom code has been added to them that makes interop calls to the .NET Framework.

We generally recommend that you not customize the methods in these special classes.

F.2  Calls to COM Objects Cannot be Chained

In X++ you can sometimes chain together a series of method calls by using the following syntax:
 
 myThing.method8().method9(); 
 
This chaining syntax is valid only if the return type from method8 has a method named method9.

When you compile by using AxBuild.exe, the syntax of method chaining cannot be used with COM objects. The compiler cannot ascertain whether the COM object that is returned by method8 has a method named method9.

The simple solution is to use another common syntax that explicitly gives the compiler the type information it needs to validate the call to method9. The situation is explained in the following table.

void methodXpp()
{
    COM comInstanceA = new COM("MyCOMType_A");
    comInstanceA.method1().method2();
}

void methodXpp()
{
    COM comInstanceA = new COM("MyCOMType_A");
    COM comInstanceB;
    comInstanceB = comInstanceA.method1();
    comInstanceB.method2();
}

G.  Screenshots during Execution of AxBuild.exe

This section contains screenshots that were taken during a test run of AxBuild.exe. The run was to test for correct functional behavior on a minimal virtual machine that has only one processor. For the test we specified /workers=2 to tell AxBuild.exe to start two temporary AOS workers. Therefore, for this test we expected the compilation to take a long time.

The following screenshot shows the cmd.exe console in which AxBuild.exe was started, including its output which mentions each phase.

The next screenshot shows the cmd.exe console that was started for a temporary AOS worker.

The next screenshot shows the AxBuild.exe and temporary AOS processes in Task Manager.

The next screenshot shows the browser that displays the contents of the AxCompileAll.html log file, which reported two warnings.

The next screenshot shows a list of the temporary files that AxBuild.exe created in the %TEMP% directory. These *.tmp files were kept only because the /nocleanup parameter was specified.

H.  MorphX Client Menus for Compiling

AxBuild.exe adds one more mechanism that you can use to compile X++ code. In the MorphX client there are several menus that you can use to compile X++. The following table describes these menus.

Announcements: New book: "Inside Microsoft Dynamics AX 2012 R3" now available. Get your copy at the MS Press Store.