Build Models, Sync DB and Deploy Reports Using CLI D365FO Tools

When automating installation, upgrade, compilation, and database synchronization of AX models via scripts, the following CLI D365FO tools are at your disposal:

  1. ModelUtil.exe: to import, replace or delete models. Learn more>>
  2. xppc.exe: to build models.
  3. LabelC.exe: to compile labels.
  4. reportsc.exe: to compile SSRS reports.
  5. DeployAllReportsToSsrs.ps1: to deploy compiled reports.
  6. SyncEngine.exe: to synchronize the database.

All the above .exe files are located in the AOSService\PackagesLocalDirectory\bin\ directory, e.g.:
C:\AOSService\PackagesLocalDirectory\bin\xppc.exe.

The script for report deployment is located in the Plugins directory:
AOSService\PackagesLocalDirectory\Plugins\
AxReportVmRoleStartupTask\DeployAllReportsToSsrs.ps1.

xppc.exe

A D365FO tool for building models.
xppc.exe [-parameters]

Most important parameters:

  • -metadata=”path”
    The path where the metadata is found. Most commonly, C:\AOSService\PackagesLocalDirectory.
  • -compilermetadata=”path”
    The path where the X++ compiler metadata is found. Usually, the same as the metadata path.
  • -xref
    If used this will update the cross-reference database as part of this build.
  • -xrefSqlServer=”hostName”
    Designates the server hosting the cross-reference information. If this switch is not provided, the local server is assumed.
  • -xrefDbName=”dbName”
    Designates the name of the database hosting the cross-reference information. If this switch is not provided, the database DYNAMICSXREFDB is assumed.
  • -appBase=”path”
    Explicitly specifies the application base for the resolution of external references. The application base defaults to the path from which the compiler was invoked. This base path is the first path that is probed for external references. Most commonly,C:\AOSService\PackagesLocalDirectory\bin.
  • -modelmodule=”moduleName”
    The name of the module to compile, for example DocentricAX. Note that this is NOT the same as the MODEL name, which in this case would be Docentric AX (with a space).
  • -referenceFolder=”path”
    The path of a folder containing modules referenced from X++ code. This option can be specified multiple times. Usually, the same as the metadata path.
  • -refPath=”path”
    Additional path for the resolution of external references. This option can be used multiple times. After the application base path is probed for external references, the additional paths are probed in the order they are specified. Usually, the bin directory inside the module directory, for example C:\AOSService\PackagesLocalDirectory\DocentricAX\bin.
  • -output=”path”
    The path where the assembly is written. Usually the same as -refPath.
  • -log=”path”
    The path to the log file containing the diagnostics as plain text. For example, C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric AX.BuildModelResult.log.
  • -xmllog=”path”
    The path to the XML log file. This can be used for tools processing the messages produced by the compiler. For example, C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric AX.BuildModelResult.xml.

Example of use: Build the DocentricAX module on a virtual machine called DevMachine01
C:\AOSService\PackagesLocalDirectory\bin\xppc.exe -metadata="C:\AOSService\PackagesLocalDirectory" -compilermetadata="C:\AOSService\PackagesLocalDirectory" -xref -xrefSqlServer="DevMachine01" -xrefDbName="DYNAMICSXREFDB" -appBase="C:\AOSService\PackagesLocalDirectory\bin" -modelmodule="DocentricAX" -referenceFolder="C:\AOSService\PackagesLocalDirectory" -refPath="C:\AOSService\PackagesLocalDirectory\DocentricAX\bin" -output="C:\AOSService\PackagesLocalDirectory\DocentricAX\bin" -log="C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric AX.BuildModelResult.log" -xmllog="C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric AX.BuildModelResult.xml"
In this example, if the build fails, we will need to check the created Docentric AX.BuildModelResult.log to analyze and fix the errors therein.

xcopy.exe

If your models contain custom controls, you will also need to copy static resources like: HTML, Images, Scripts and Styles. For this purpose, the xcopy tool is used as follows:
xcopy.exe [source] [destination] [/parameters]

Most important parameters:

  • [source]
    The path of the file(s) to copy.
  • [destination]
    The path of the destination to copy to.
  • /Y
    Suppresses prompting to confirm you want to overwrite a destination file.
  • /R
    Overwrites read-only files.
  • /H
    Copies hidden and system files also.
  • /I
    If destination does not exist and copying more than one file, assumes that destination must be a directory.

Example of use: Copy HTML resources for the Docentric AX model
xcopy.exe C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric AX\AxResource\ResoruceContent\Html C:\AosService\WebRoot /Y /R /H /I

xppbp.exe

A D365FO tool for running best practice checks.
xppbp.exe [-parameters]

Most important parameters:

  • -metadata=”path” OR -m=”path”
    The path where the metadata is found. Most commonly, C:\AOSService\PackagesLocalDirectory.
  • -all
    All element types and all best practice rules are checked within the specified model and module.
  • -module=”moduleName” OR -mu=”moduleName”
    The name of the module on which to run best practice checks on. For example, DocentricAx.
  • -model=”model name” OR -me=”model name”
    The name of the model on which to run best practice checks on. For example, Docentric Ax.
  • -packagesRoot=”path” OR -pr=”path”
    The path to the packages root containing binaries for modules. Usually, the same as the metadata path.
  • -log=”path” OR
  • -l=”path”
    The path to the output log file containing diagnostics as plain text. For example, C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric AX.BestPracticeCheckResult.log.
  • -xmlLog=”path” OR -x=”path”
    The path to the output xml log file. This can be used for tools processing the messages produced by the checker. For example, C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric AX.BestPracticeCheckResult.xml.

Example of use: Run best practice checks for the DocentricAX module
C:\AOSService\PackagesLocalDirectory\bin\Xppbp.exe -metadata="C:\AOSService\PackagesLocalDirectory" -all -module="DocentricAx" -model="Docentric Ax" -packagesRoot="C:\AOSService\PackagesLocalDirectory" -log="C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric AX.BestPracticeModelResult.log" -xmllog="C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric AX.BestPracticeModelResult.xml"
This will generate a .log file in the location specified in the -log parameter that contains all best practice warnings for the selected model and module. Any errors that occur will also be stored in the .log file.

LabelC.exe

A D365FO tool for compiling labels.
LabelC.exe [-parameters]

Most important parameters:

  • -metadata=”path”
    The Path where the metadata is found. Most commonly, C:\AOSService\PackagesLocalDirectory.
  • -modelmodule=”moduleName”
    The name of the module to compile, for example DocentricAX. Note that this is NOT the same as the MODEL name, which in this case would be Docentric AX (with a space).
  • -output=”path”
    The path to the compiled label files. Most commonly, the resources directory inside the module directory is used. For example, C:\AOSService\PackagesLocalDirectory\DocentricAX\Resources.
  • -outlog=”path”
    The path to the log file containing the diagnostics as plain text. For example, C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric Ax.CompileLabels.log.
  • -errlog=”path”
    The path to the output xml log file. This can be used for tools processing the messages produced by the compiler. For example, C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric Ax.CompileLabels.xml.

Example of use: Compile the labels for the DocentricAX module
C:\AOSService\PackagesLocalDirectory\bin\LabelC.exe -metadata="C:\AOSService\PackagesLocalDirectory" -modelmodule="DocentricAx" -output="C:\AOSService\PackagesLocalDirectory\DocentricAx\Resources" -outlog="C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric Ax.CompileLabels.log" -errlog="C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric Ax.CompileLabels.xml"
This will generate the compiled labels as .dll files in the location specified in the -output parameter. Any errors that occur will be stored in the .log file in the location specified by the -outlog parameter.

reportsc.exe

A D365FO tool for compiling SSRS reports.
reportsc.exe [-parameters]

Most important parameters:

  • -metadata=”path” OR -m=”path”
    The path where the metadata is found. Most commonly, C:\AOSService\PackagesLocalDirectory.
  • -modelmodule=”moduleName” OR -mod=”moduleName”
    The name of the module for which to compile reports, for example, DocentricAX. Note that this is NOT the same as the MODEL name, which in this case would be Docentric AX (with a space).
  • -output=”path” OR -o=”path”
    The path to where the generated .rdl files are written. By default, reports are compiled to the Reports directory inside the module directory. For example, C:\AOSService\PackagesLocalDirectory\DocentricAx\Reports.
  • -log=”path” OR -l=”path”
    The path to the log file containing the diagnostics as plain text. For example, C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric AX.BuildSSRSReportResult.log.
  • -xmllog=”path” OR -x=”path”
    The path to the XML log file. This can be used for tools processing the messages produced by the compiler. For example, C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric AX.BuildSSRSReportResult.xml.

Example of use: Compile reports for the DocentricAX module
C:\AOSService\PackagesLocalDirectory\bin\Reportsc.exe -metadata="C:\AOSService\PackagesLocalDirectory" -modelmodule="DocentricAX" -output="C:\AOSService\PackagesLocalDirectory\DocentricAx\Reports" -log="C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric Ax.BuildSSRSReportResult.log" -xmllog="C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric Ax.BuildSSRSReportResult.xml"
This will generate the compiled SSRS reports as .rdl files in the location specified in the -output parameter. Any errors that occur will be stored in the .log file in the location specified by the -log parameter.

DeployAllReportsToSsrs.ps1

A D365FO tool for deploying SSRS reports.
DeployAllReportsToSsrs.ps1 [-parameters]

Most important parameters:

  • -logFilePath “path”
    Deployment log file path. For example, C:\AOSService\PackagesLocalDirectory\DocentricAX\Docentric Ax.DeployReportsToSSRSResult.log.
  • -PackageInstallLocation “path”
    The path where the metadata is found. Most commonly, C:\AOSService\PackagesLocalDirectory.
  • -ReportServerIp “IPAddress”
    IP address of the SSRS report server. Default value is 127.0.0.1 (localhost).
  • -Module “moduleNames”
    Comma-separated module names. Default value is all deployed modules.
  • -ReportName “reportNames”
    Comma-separated report names (including design name). For example, DocWHSLicensePlateLabel.Report. Default value is all compiled reports.

Example of use: Deploy the compiled DocWHSLicensePlateLabel report with design name Report in the DocentricAXLicensePlateLabels module to the report server on localhost.
powershell.exe -File "C:\AOSService\PackagesLocalDirectory\Plugins\AxReportVmRoleStartupTask\
DeployAllReportsToSsrs.ps1" -LogFilePath "C:\AOSService\PackagesLocalDirectory\DocentricAXLicensePlateLabels\Docentric Ax.BuildSSRSReportResult.log" -PackageInstallLocation "C:\AOSService\PackagesLocalDirectory" -ReportServerIp "127.0.0.1" -Module "DocentricAXLicensePlateLabels" -ReportName "DocWHSLicensePlateLabel.Report"

If any errors occur during deployment, they will be written to the log file at the location specified by the LogFilePath parameter.

SyncEngine.exe

A D365FO tool for synchronizing the database.
SyncEngine.exe [-parameters]

Most important parameters:

  • -syncmode=”mode”
    Specify the sync mode. Supported mode: {fullall | initialschema | fullsecurity | fullids | fulltablesandviews | partiallist | drop | drop,partiallist | partialsecurity | partiallist,partialsecurity | analysisonly | precheck}. Most commonly, fullall.
  • -metadatabinaries=”path”
    The path where the metadata is found. Most commonly, C:\AOSService\PackagesLocalDirectory.
  • -connect=”connectionString”
    The database connection string.
    For example, “Data Source=%DOCENTRICAX_DB_HOSTNAME%;Initial Catalog=AxDB;Integrated Security=True;Enlist=True;Application Name=SyncEngine”.
  • Breakdown of the connection string:

    • Data Source: The hostname of the machine, can be found by typing hostname in the command line.
    • Initial Catalog: The name of the database, usually AxDB.
    • Integrated Security: If set to true the current Windows account credentials are used for authentication. Otherwise, a username and password need to be provided.
    • Enlist: If set to true the SQL Server connection pooler automatically enlists the connection in the creation thread’s current transaction context.
    • Application Name: The name of the application, or ‘.NET SQLClient Data Provider’ if no application name is provided.
  • -fallbacktonative=”boolean”
    Specifies whether fallbacktonative is active. Most commonly, set to False.
  • -raiseDataEntityViewSyncNotification
    Specifies whether raiseDataEntityViewSyncNotification will be invoked for full sync. Flag is ignored for partial sync.

Example of use: Run a full database sync on a virtual machine called DevMachine01
C:\AOSService\PackagesLocalDirectory\bin\SyncEngine.exe -syncmode=fullall -metadatabinaries="C:\AOSService\PackagesLocalDirectory" -connect="Data Source=DevMachine01;Initial Catalog=AxDB;Integrated Security=True;Enlist=True;Application Name=SyncEngine" -fallbacktonative=False -raiseDataEntityViewSyncNotification > "C:\Temp\DatabaseSync.log"
Because this tool doesn’t have a log parameter, we can use “>” to redirect the output to a log file.

Leave a Reply

Your email address will not be published.

*

Docentric respects your privacy. Learn how your comment data is processed >>

Docentric respects your privacy. Learn how your comment data is processed >>