The topic for the next few posts is Dynamics AX, PowerShell and TFS, often together. I would also like to clear my “post buffer” a little in the following days…

If you know my previous (Czech-only) blog you may remember some PowerShell scripts published roughly two years ago (posts tagged “PowerShell” here) and I developed few more scripts in the meantime. Now I decided to wrap some parts to reusable components and implement some new features.

The main motivation was to simplify the usage of my scripts in automated builds (I’m going to show how to use them in builds both with and without TFS Build, but that’s out of scope for today). As a side effect, new functions also help with “manual” AX maintenance via PowerShell command line.

The state is not final and definite – I know some missing features, the documentation is not complete etc. and there are always ideas about how to extend it. But I feel it’s already good enough to be used – and I can get some feedback if the whole stuff is published (so please don’t hesitate to comment).

Concepts

The currently implemented features allow you to easily gather details about Dynamics AX instances, to compile AX applications and so on. As an entry point, they use AX configurations saved in Windows registry or in .axc files. Some commands can run on remote machines (e.g. to restart remote AOS) and you just have to provide user credentials is such cases.

The code is encapsulated in Advanced PowerShell functions which behave almost as cmdlets – so you can use piping, -WhatIf parameter etc. You can also use Get-Help to see the documentation.

The functions are placed in a PowerShell module which can be  installed in a usual way. See more in Installation.

The module was developed for AX2012 and tested also for AX2009.

Naming

Dynamics AX 2012 Management Shell uses “AX” as a prefix of the second part of cmdlet names, e.g. New-AXUser and I follow this convention as well (e.g. Get-AXConfig).

Functions

Here is a list of functions available, divided to several groups:

Manage AX client configuration

Get-AXConfig	Gets details about an AX instance and lists registry-based configurations.
Set-AXConfig	Sets the active client configuration.

Run AX client

Start-AXClient

Runs AX client, optionally with parameters.

Run AX startup commands

Compile-AXIL	Generates CIL assemblies.
Compile-AXXpp	Compiles AX application (X++).
Synchronize-AXDatabase	Synchronizes AX database.
Synchronize-AXVCS	Synchronizes AX application with a model in VCS.
Update-XRef	Updates cross-references.

Manage AX database

Update-XRefIndex

Rebuilds database indexes for cross-reference tables.

Manage AOS

Allows to manage AOS services, even on remote computers.

Restart-AXAOS	Restarts AOS service.
Start-AXAOS	Starts AOS service.
Stop-AXAOS	Stops AOS service.

Wait for the following post, where I provide much more details.

Where to find

I would like to see a certain consolidation in Dynamics AX community – it’s better to collaborate on widely used and tested tools rather then having a unique ad-hoc solution in every team (and lots of teams without any solution at all). That’s why we develop reusable components in our work, isn’t it?

That’s why I joined Joris de Gruyter’s CodePlex project rather then creating my own. My PowerShell module is not a replacement of Joris’s build scripts (they have some common features, but not all), nevertheless I would like to see a merge later. Now it’s only placed in the same project, but it’s a good first step.

Installation

Download DynamicsAxCommunity module .zip archive from dynamicsaxbuild.codeplex.com. Find “DynamicsAxCommunity” folder in the archive – that’s the PowerShell module itself (we’re not going to work with individual files).

PowerShell modules are installed by Import-Module cmdlet. You can either place the module to a standard location (see $env:PSModulePath) and refer just to the module name in Import-Module cmdlet, or to provide full path to your own location.

For example, you can copy the module to the standard path c:\Windows\system32\WindowsPowerShell\v1.0\Modules\ and call Import-Module DynamicsAxCommunity (use the DisableNameChecking parameter to avoid the message about unapproved verbs).

You can add this command to your profile to make AX functions always available.

Dynamics AX 2012 Management Shell is not required, although it can be used together with this module.

Additional consideration

Remoting – To get data from remote computers and to run some actions on them, PowerShell remoting must be configured. Furthermore, you have to install the module on the remote computer(s) and enable it in remote sessions. I solved this by adding a script containing Import-Module to the default remoting session configuration (Set-PSSessionConfiguration microsoft.powershell -StartupScript $pathToScript).

Synchronize-AXVCS – Synchronization with a model in Version Control System uses a custom startup command – you have to import the .xpo to all environment where you want to use Synchronize-AXVCS. The SysStartupCmdSyncVCS.xpo is contained in the .zip archive described in Installation. Only AX2012 is supported.

Update-XRefIndex – Update-XRefIndex uses SQL Server Cmdlet Snapin to connect directly to SQL Server, which may require additional setup. On the other hand, it doesn’t require any change in Dynamics AX.

What is missing?

Several things are either not completed, not integrated to the module or simply not developed at all. I can remember these:

• Documentation is not bad, but still incomplete.
• Functions using AX startup commands don’t provide any output. For example, compilation results from Compile-AXXpp would be useful. Error reporting should be improved as well (nevertheless the eventlog-based approach implemented in RunAxClientAndWait is quite promising).
• Some direct support for builds (e.g. moving label files in AX <2012) might be useful.
• Support for PSSession, better Verbose messages etc. etc.

I hope you’ll find the module handy. And notice that I intentionally call it Community to show that the source code is open for modifications…