DynamicsAxCommunity module – Examples

The previous article described basics of the DynamicsAxCommunity PowerShell module, this post is mostly about how to use it.

Common topics

There are some topics you should be familiar with before you start to use the module.

Configurations

Functions needs to know which AX configuration is to be used. The first positional parameter expects the configuration name (as you can see it in Configuration utility) and you can even omit it to use the active configuration. Another option is to use a configuration file – either by the -Path parameter or from pipe.

AxVersion

All functions need to know the version of AX to find right keys in registry etc. The default is set to 6 (=AX2012). If you use another version, you have three options:

  • To use AxVersion (alias Version) parameter, e.g. Get-AXConfig -AxVersion 5
  • To change value of $AxVersionPreference variable (e.g. $AxVersionPreference=5)
  • To change the default value in code (but I would prefer to set $AxVersionPreference in machine’s PowerShell profile)

Remoting

If you work only with AX client and client configurations, no PowerShell remoting is necessary. That’s also true if the AOS is installed on the same machine. But if you need to work with remote AOSes (even just to get database name from an AOS configuration), you can’t do without remoting.

You don’t have to bother with computer names, the only information you have to provide is user credentials. Relevant functions offers -Credential parameter for this purpose.

Parameter aliases

Parameters have names and they can also have aliases. But that’s not all – you can shorten any parameter name to anything still unambiguous, so you can use just -ax instead of -AxVersion without any special alias.

Functions and examples

AX configuration

Functions: Get-AXConfig, Set-AXConfig

Get-AXConfig lists AX client configurations in Windows registry and shows details about AX instances, e.g. the log directory. Such information is used by other functions in the module and can be used by your own scripts.

Examples:

List all configurations in Windows registry (local machine, current user):

Get-AXConfig -List

Change active configutation (-Verbose is used to show some output):

Set-AXConfig Release -Verbose

Show details of the active configuration (I use Format-List (or fl) here not to get too wide output):

Get-AXConfig | Format-List

Show details of a named configuration:

Get-AXConfig Release | fl

Show details of a configuration saved in a file:

Get-AXConfig -Path C:ax2012.axc | fl

You can also pipe configuration file path to AX functions (although you still can’t process multiple configurations at once):

(Join-Path c: ax2012.axc) | Get-AXConfig | fl

If you need information about server components, use -IncludeServer (alias Server) parameter:

Get-AXConfig -IncludeServer

Dynamics AX 2009 has an additional property – ApplDir:

Get-AXConfig -s -ax 5

You can use such properties in subsequent processing. For example, you can get all .aod files by the following call:

Get-AXConfig -s -ax 5 | select -exp ApplDir | ls -filter *.aod

Start AX client

Functions: Start-AXClient

As other functions, Start-AXClient can be run without parameters (to use default configuration), with AX configuration name or a path to .axc. While it simplifies running AX from command line, its main purpose is to be called from other functions.

Running AX startup parameters

Functions: Compile-AXXpp, Compile-AXIL, Synchronize-AXDatabase, Synchronize-AXVCS, Update-XRef

These commands runs AX client with a startup parameter. Notice the parameters in “What if” message:

Compile-AXXpp -WhatIf

When the process is really run (without -WhatIf), AX client is started and the function wait for the end:

Compile-AXXpp -Verbose

You can also set some timeout:

Compile-AXIL -Timeout 3600 -Verbose

To avoid to much math, you can specify the timeout value as (New-Timespan -Hours 4).TotalSeconds, for example.

You can also use -Confirm parameter to be asked before the processing is started:

Synchronize-AXDatabase Release -Confirm

Synchronize-AXVCS

Synchronize-AXVCS is the first attempt to build AX environment directly from Version Control. It does the same thing as if you call Synchronize with “Force” option from AX Version Control menu.

Choose the model to synchronize with in the -Model parameter:

Synchronize-AXVCS -Model ISV

Update xRef indexes

Functions: Update-AXXrefIndex

Update-AXXrefIndex rebuilds indexes on all xRef tables. Without that, performance of cross-references can be significantly degraded, especially when all references were rebuilt.

This functions calls SQL Server directly, so it requres different security setup than other functions. It also depends on sqlps utility. On the other hand, it doesn’t need any modification in AX.

Call it in the same way as other functions, for example:

Update-AXXRefIndex -Name Dev -Timeout (15*60)

AOS service

Functions: Start-AXAOS, Stop-AXAOS, Restart-AXAOS

All three functions are very similar and accept configuration names and paths in the same way as functions above.

For example, restart AOS using “Dev” configuration:

Restart-AXAOS Dev

Credentials

If an AOS is on a remote computer, credentials for the remote connection need to be specified. If you don’t provide them, PowerShell will make a query:

Restart-AXAOS -Path C:\AX2012.axc

Credentials will be cached and used in subsequent commands automatically. Nevertheless, you can also save them to a variable and pass them to the -Credential parameter:

Restart-AXAOS -Path C:\AX2012.axc -Credential $credential

Have fun with PowerShell!