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):
Change active configutation (-Verbose is used to show some output):
Show details of the active configuration (I use Format-List (or fl) here not to get too wide output):
Show details of a named configuration:
Show details of a configuration saved in a file:
You can also pipe configuration file path to AX functions (although you still can’t process multiple configurations at once):
If you need information about server components, use -IncludeServer (alias Server) parameter:
Dynamics AX 2009 has an additional property – ApplDir:
You can use such properties in subsequent processing. For example, you can get all .aod files by the following call:
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:
When the process is really run (without -WhatIf), AX client is started and the function wait for the end:
You can also set some timeout:
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-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:
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:
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:
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:
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:
Have fun with PowerShell!