GeekzSolutions

Install deployable packages from the command line

Posted on by sitemanager

Key concepts

  • Deployable package – A deployable package is a unit of deployment that can be applied to any environment. It can consist of a binary hotfix to the runtime components of Application Object Server (AOS), an updated application package, or a new application package.
  • AXUpdateInstaller – AXUpdateInstaller is an executable program that is bundled in the deployable package. When the package is downloaded to a computer, the installer is available.
  • Runbook – The deployment runbook is a series of steps that is generated and used to apply the deployable package to the target environment. Some of the steps are automated, and some are manual. AXUpdateInstaller enables these steps to be run one at a time and in the correct order.

Install an application (AOT) deployable package on a development environment

 Note

The steps listed below are for customization packages only. Do not use the devinstall parameter when running the Data Upgrade deployable package as part of an upgrade from Microsoft Dynamics AX 2012 to a Finance and Operations app.

An AOT deployable package is a package that contains customizations and extensions to your application. If you want to use the command line just to install an AOT deployable package on a development or demo environment, follow the instructions in this section. You can then skip the rest of this topic.

  1. On the virtual machine (VM), download the zip file for the deployable package. Make sure that the zip file is stored in a non-user folder. NoteAfter you download the zip file, right-click it, and then select Properties. Then, in the Properties dialog box, on the General tab, select Unblock to unlock the files.
  2. Extract the files.
  3. Open a Command Prompt window, and go to the folder where you extracted the deployable package.
  4. Run the following command.ConsoleCopyAXUpdateInstaller.exe devinstall The devinstall option installs the AOT deployable package on the VM. NoteThis command doesn’t run database synchronization. You must run database synchronization from Microsoft Visual Studio after you install the deployable package.

Collect topology configuration data

  1. In LCS, on the Environment page, select the name of a VM. Establish a Remote Desktop connection to the VM by using the user name and password that are provided on the Environment page.
  2. On the VM, download the zip file for the deployable package from LCS. Make sure that the zip file is stored in a non-user folder. NoteAfter you download the zip file, right-click it, and then select Properties. Then, in the Properties dialog box, on the General tab, select Unblock to unlock the files.
  3. Extract the files.
  4. In the folder where you extracted the deployable package, find and open the file that is named DefaultTopologyData.xml. You must specify the VM name and the installed components in this file.
    • To specify the VM name, follow these steps:
      1. In File Explorer, right-click This PC, and then select Properties.
      2. In the system properties, find and make a note of the computer name (for example, AOS-950ed2c3e7b).
      3. In the DefaultTopologyData.xml file, replace the machine name with the computer name that you found in the previous step.
    • To specify the installed components, follow these steps:
      1. Open a Command Prompt window as an administrator.
      2. Go to the extracted folder, and run the following command to see a list of all the components that are installed on the computer.ConsoleCopyAXUpdateInstaller.exe list
      3. Update the DefaultTopologyData.xml file with the list of components.
      When you’ve finished specifying the VM name and the installed components, the DefaultTopologyData.xml file should resemble the following illustration.Topology configuration data
  5. Repeat steps 1 through 4 for every other VM that is listed on the Environment page.

Generate a runbook from the topology

Based on the topology information in the DefaultTopologyData.xml file, you must generate the runbook file that will provide step-by-step instructions for updating each VM.

  • On any VM, run the following command to generate the runbook.ConsoleCopyAXUpdateInstaller.exe generate -runbookid=[runbookID] -topologyfile=[topologyFile] -servicemodelfile=[serviceModelFile] -runbookfile=[runbookFile] Here is an explanation of the parameters that are used in this command:
    • [runbookID]– A parameter that is specified by the developer who applies the deployable package.
    • [topologyFile]– The path of the DefaultTopologyData.xml file.
    • [serviceModelFile]– The path of the DefaultServiceModelData.xml file.
    • [runbookFile]– The name of the runbook file to generate (for example, AOSRunbook.xml).ExampleConsoleCopyAXUpdateInstaller.exe generate -runbookid="VAL200AA2BMEDIU-runbook" -topologyfile="DefaultTopologyData.xml" -servicemodelfile="DefaultServiceModelData.xml" -runbookfile="VAL200AA2BMEDIU-runbook.xml"

The runbook provides the sequence of steps that must be run to update the environment. The following illustration shows an example of a runbook file. Each step in a runbook is associated with an ID, a machine name, and step execution details.

Example of a runbook file

Install a deployable package

  1. On the first machine (VM) that is listed in the runbook file, follow these steps:
    1. Import the runbook by running the following command.ConsoleCopyAXUpdateInstaller.exe import -runbookfile=[runbookFile] ExampleConsoleCopyAXUpdateInstaller.exe import -runbookfile="VAL200AA2BMEDIU-runbook.xml"
    2. Verify the runbook.ConsoleCopyAXUpdateInstaller.exe list
    3. Run the runbook.ConsoleCopyAXUpdateInstaller.exe execute -runbookid=[runbookID] ExampleConsoleCopyAXUpdateInstaller.exe execute -runbookid="VAL200AA2BMEDIU-runbook" AXUpdateInstaller updates the runbook file after each step is run on a VM. The runbook also logs information about each step.For manual steps, follow the instructions, and then run the following command to mark the step as completed in the runbook.ConsoleCopyAXUpdateInstaller.exe execute -runbookID=[runbookID] -setstepcomplete=[stepID] ExampleConsoleCopyAXUpdateInstaller.exe execute -runbookid="VAL200AA2BMEDIU-runbook" -setstepcomplete=2 If errors occur during any step, debug the script or the instructions in the step, and update accordingly.
    4. Export the runbook.ConsoleCopyAXUpdateInstaller.exe export -runbookid=[runbookID] -runbookfile=[runbookFile] ExampleConsoleCopyAXUpdateInstaller.exe export -runbookid="VAL200AA2BMEDIU-runbook" -runbookfile="VAL200AA2BMEDIU-runbook.xml"
  2. Repeat step 1 on every other VM that is listed in the runbook file. For one-box environments, such as development, build, and demo environments, there is only one VM.

Verify installation

  1. Run the following command to verify that the new updates are installed.ConsoleCopyAXUpdateInstaller.exe list
  2. View the runbook to see the completed steps. Here is an example of a runbook file where the steps have been completed.

Backup the runbook file

  • After all the steps in the runbook are completed and you’ve exported the runbook, save the file outside the computer for future reference. For example, you might have to use the runbook file in these situations:
    • You must analyze the downtime requirements for production, and so on.
    • You must send the file to Microsoft because a deployable package can’t be installed.

Troubleshooting

  • If any step in the runbook fails, you can rerun it by running the following command.ConsoleCopyAXUpdateInstaller.exe execute -runbookid=[runbookID] -rerunstep=[stepID]
  • To prevent version mismatch or downgrade, or installation of the same deployable package, run the following command.ConsoleCopyAXUpdateInstaller.exe execute -runbookid=[runbook ID] -versioncheck=true
  • To verify database synchronization, in the aosservice\scripts\ folder, find and open the dbsync.error.txt file, and look for any errors.