Saturday, October 12, 2013

AXUtilLib - AX Management Utilities version matter

With Dynamics AX 2012 you get this library of tools for all sorts of management tasks, like maintaining your models and modelstores, deploy SSRS reports or Enterprise Portal components and a lot of other cool stuff. While some may argue using command line tools is a set-back compared to rich UI tools, there is a vast number of DevOps (or OpsDev, if you prefer) who without a doubt find this to be a critical component for any major software solution. Before AX2012, I had just briefly tampered with PowerShell, but now I can't do my job (efficiently) without it. PowerShell is awesome!

This blog post is about the importance of the build version of AXUtilLib.dll. When you're running the Dynamics AX Management Shell PowerShell Window, you will by default launch it with whatever build version is installed, normally under C:\Program Files\Microsoft Dynamics AX\60\ManagementUtilities.
You can basically check your current version by running these two lines in PowerShell:

cd 'C:\Program Files\Microsoft Dynamics AX\60\ManagementUtilities'
ls -fi *.dll | % { $_.versioninfo }

Why is this important

Here is a couple of things you might struggle with.

ModelStore Database location

The RTM version will assume your application modelstore is located in the same database as your business data. This is expected behavior in RTM as the business data and the application data resided in the same database.
R2 version will obviously assume the application modelstore is located in a separate database using the "_model" suffix.

Unable to import models from newer version

When you export a model, it is bound to the version of the management utilities you used. Just try export a model to a file and then run this command to view the version:
Get-AXModelManifest -File C:\mymodel.axmodel | Select ModelBuildVersion
If you were to try import this model file using a previous version of Management Utilities you will get an error:
The model file is from a newer version of Microsoft Dynamics AX (version ) and cannot be installed.

How to get around

Say you have upgraded to the latest update of Management Utilities but have an AOS running a previous build and you need to use Management Utilities to import a model. Luckily, when installing the AOS, the installer drops a copy of the AxUtilLib.dll in the AOS bin-folder, and this copy will always (*knock-knock*) be of the same version of that AOS-service. All you need to do is to make sure your command line session uses this version and not the default one.

If your only concern is to install a model, then all you need is AxUtilLib.dll, AxUtil.exe (for Command Line Window) and AxUtilLib.PowerShell.dll (for PowerShell commands). For your own convenience, copy the files to a different path, say C:\AxUtilLib\6.2.1000.1437\.

For a Windows Command line session, simply open MS-DOS Prompt (with Administrator rights, I might add), navigate to the folder and run the necessary commands.

For a PowerShell session, you will have to import the assemblies necessary. Since this example is only about operations against models, we only need a limited set of assemblies.

There is a nice list of commands and assemblies in this nice post by Martin DrĂ¡b.