RM for VS2013 : Creating the deployment sequence

This is the third post in a series discussing automated releases for Dynamics AX 2012 with ReleaseManagement for Visual Studio 2013. Before, we discussed the following topics:

  • Part 1 discussed the pros and cons of ReleaseManagement and gave a glimpse on how we would fit in Dynamics AX.
  • With part 2 , a first tool was created. This gave an overview of the central PowerShell module and explained the use of tool wrappers.

In this post, I wanted to tell you all about setting up servers, environments, paths and so on, but this is already well documented in the user’s guide. Also for AX, this does not differ from other products. (http://download.microsoft.com/download/2/9/B/29B10D38-3473-4AC2-9CEB-7D471E0A8ECD/Release%20Management%20for%20Visual%20Studio%202013%20User%20Guide.pdf) (Sorry for the links in here, but WordPress is bugging me with some issues in the editor :))


Instead, let’s focus on the AX specific parts. More specifically:

  • Component configuration
  • Release Template configuration
  • Deployment sequence

Component configuration

Components can be seen as logical parts of a solution. This can be a database, a website, … These components can be configured in RM and you can assign deployment tools to them, link them to sources, … For Dynamics AX, we state that the component is comprised of the set of models or model store in the build output.

So for us, the configuration of an ‘AX Component’ is pretty straight forward. We create a component “AX2012Solution” and there are 2 things to configure: Where are your component sources and how do we deploy these source to the agents?


First, we define where the component sources are located. There are 3 options here:

  • Builds with application
    This links the component to a TFS Build definition defined in the release template. By doing so, RM knows what build drops to take and use these as the source for your deployment. So different release templates can be attached to different definitions. We use this when branching environments.
  • Builds independently
    In short, this is the same as the first option, but the build definition is linked to the component and not to the release template.
  • Builds externally
    Use this when you have no access to TFS from you deployment machines. You are able to have ‘offline’ source available in a folder.

In our case , this is linked to TFS through the release template.


Next, the Deployment tab is up. Here we’ll tell RM how to deploy the selected resources to the deployment agents (the machines involved in your deployment). And for AX, we can use the XCopy deployer here. Why?? Because we can use it to simply copy the sources from the build output folder to a known variable (__installationPath__) within RM. From then on, we can use that variable in our release template.


Release Template configuration

Next, you need to create a release template. This is when all of the pieces fall together. Start of by selecting the properties of your template. There you can specify the release path to be used. All of the stages in your path will result in a tab on your template. So it is possible to have a different deployment sequence for the different stages.

The second important thing here is the connection to the TFS Build definition. When you specify a build definition, RM will be able to present a list of recent builds when starting a new release.


Deployment sequence

And now, the magic of the whole thing! Putting together a sequence of actions that define your release. In the sequence editor you can see the following:

  • At the left side, the toolbar containing your servers, components and inventory (tooling)
  • Top right, you can see a tab for each of you stages in the release path. (To be able to have deployment template per stage)
  • In the main area, you can drag and drop your action to the canvas. Depending on the action, you can input the parameter values needed.

So you can start of by dragging actions and composing your deployment. There a few rules here to keep in mind.

  • Actions run on a certain server, so you have to start dragging the machine you want to use first.
  • Your component is also available in the toolbox, so you can use your component shape to copy the build sources to the corresponding server.

Below, you can see a part of the deployment sequence and how it all falls together. The Install AX model action will collect parameters and pass them on to the PowerShell wrapper tool. From there on, the central PowerShell module is called and parameters are passed.



 There you go! I hope this has shed some light on how to configure you deployment sequence for AX. In the next post, we will take a look at starting a release and how we can follow up deployments. After that, we should also take a look into the TFS Build template to trigger RM releases from within TFS Builds.


Release Management for VS2013 … and AX : The first tool

In part 1 of this series, we discussed the pro and cons of Release Management for VS2013 and scratched the surface of how we are going to use it with Dynamics AX. As that post has been there for a while, new updates have been available for Release Management (RM from now on) adding some interesting features like deployment agent-less deployment using Desired State Configuration. But anyway, I have been working with RM lately together with my colleague Kevin Roos to automate deployment of daily TFS build drops to a test Dynamics AX 2012 environment. Today I want to start scratching the surface and show you how to create a first tool within RM to clean the AX artifact folders. It is one of the simplest tools that we are going to use but it shows the following:

  • Creating a powershell module that contains generic functions to use with Dynamics AX (The module also takes care of loading other libraries like the ones from Joris De Gruyter)
  • Creating a powershell script to act as a bridge between RM and the PS module
  • Creating a tool and corresponding action to use in RM

So the goal here is to have a tool / action in RM that removes AX artifacts. To achieve this, we use a PowerShell script representing the clean artifacts tool and that script will in it’s turn make use of a generic PowerShell module that contains a library of functions to be used with Dynamics AX 2012.

 Creating the powershell module

First things first, before wiring up RM, let’s create a PowerShell module to contain all kinds of functions to be used with AX. (Cleaning of folders, reading configuration files, starting compilations, …). A good introduction to PowerShell modules can be found on the SimpleTalk blog article : An Introduction to PowerShell modules.

So for our module here, we created a default model manifest and added the following stuff:

RequiredAssemblies = @('CodeCrib.AX.Config.dll', 'CodeCrib.AX.AXBuild.dll', 'CodeCrib.AX.Client.dll')
ModuleToProcess = @('RDAXManagement.psm1')
NestedModules = @('CodeCrib.AX.Config.PowerShell.dll', 'RDAX.CodeCribWrapper.dll')

The RequiredAssemblies line makes sure that the CodeCrib dll files we use are loaded when we load our module. ModuleToProcess shows the module where this definition applies to. And finally, NestedModules will load additional Cmdlets available in the specified dll files.

So, our definition file is ready, let’s create the module file itself. So create a PowerShell file named RDAXManagement.psm1 and put in the following function:

function Clear-AXArtifactFolders
	[Parameter(	Position    = 0, 
			Mandatory   = $true)]
        [Parameter(	Position   = 1, 
			Mandatory  = $true)]

        # Read the client configration file
        $serverConfiguration = Get-ServerConfiguration -filename $serverConfigName
	$serverAltBinDir = $serverConfiguration.AlternateBinDirectory

	$LocalAppDataFolder = [Environment]::GetFolderPath('LocalApplicationData')
	$FolderPath = [string]::Format("{0}Application\Appl\Standard\*",$ServerAltBinDir)
	Write-Host "Cleaning server label artifacts ($FolderPath)"
	Remove-Item -Path $FolderPath -Include ax*.al? -Recurse
	$FolderPath = [string]::Format("{0}XppIL\*",$ServerAltBinDir)
	Write-Host "Cleaning server XppIL artifacts ($FolderPath)"
	Remove-Item -Path $FolderPath -Include *.* -Recurse
	$FolderPath = [string]::Format("{0}VSAssemblies\*",$ServerAltBinDir)
	Write-Host "Cleaning server VSAssemblies artifacts ($FolderPath)"
	Remove-Item -Path $FolderPath -Include *.* -Recurse

	$FolderPath = [string]::Format("{0}\*", $LocalAppDataFolder)
	Write-Host "Cleaning client cache artifacts ($FolderPath)"
	Remove-Item -Path $FolderPath -Include .auc,kti

	$FolderPath = [string]::Format("{0}\Microsoft\Dynamics Ax\*", $LocalAppDataFolder)
	Write-Host "Cleaning client VSAssemblies artifacts ($FolderPath)"
	Remove-Item -Path $FolderPath -Filter "VSAssemblies"

So there we have the first function of our generic library available. It’s time to create a wrapper script that we can attach to a tool within the RM client.

Creating the PowerShell RM tool wrapper

There is a good reason why we use wrapper scripts that are linked to RM tools. By creating several tools, the parameter list passed to a specific tool is smaller than creating one big script having to deal with all of the possible actions/parameter combinations to feed the RDAXManagement PowerShell module. And trust me, some of the tools coming up later already have a bunch of parameter sets to deal with things.

But anyway, create a PowerShell script called RDAXFolderCleaner.ps1 and put in the following code:

< #
	Cleans up the Ax artifacts
	This script will delete cache files, xppil files, label caches, ... from the Ax folders
.PARAMETER AxClientConfigName
	The client configuration to load client side folder metadata
.PARAMETER AxServerConfigName
	The server configuration to load server side folder metadata

    [string]$AxClientConfigName = $(throw "The client configuration file name must be provided."),
    [string]$AxServerConfigName = $(throw "The server configuration file name must be provided.")

# This makes sure that ReleaseManagement also fails the step instead of continuing execution
$ErrorActionPreference = "Stop"


$ExitCode = 0

	# Determine the working directory of the deploy agent
	$InvocationDir 		= Split-Path $MyInvocation.MyCommand.Path

	# Load the Dynamics AX Management PowerShell module
	$AXModuleFileName 	= [string]::Format("{0}\RDAXManagement.psd1", $InvocationDir);
	Import-Module -Name $AXModuleFileName

	# Call the cleanup routine
	Clear-AXArtifactFolders -clientConfigName $AxClientConfigName -serverConfigName $AxServerConfigName

	"`nCleaning of artifacts finished."
Catch [system.exception]
	$ErrorMessage = $_.Exception.Message
	"Error : RM Cleaning of folder failed. Exception message: $ErrorMessage"	
	$ExitCode = 1

exit $ExitCode

So to summarize the above code, the script takes the needed parameters from RM for this specific action and passes them AX generic PowerShell module. Apart from the business logic, the most important line is the one telling PowerShell to stop when an error is encountered. If you do not put this line in there, PowerShell will pop up errors in the log, but RM will just keep on thinking the steps in the release sequence finish successful.

Creating the RM tool and corresponding action

Now that we have the business logic in the PowerShell module and a script that acts as a bridge between RM and the module, let’s create a tool and action for it in RM itself. Tools are used to group several actions that can be done with one and the same tool. In RM, go to the tab page Inventory, select Tools and create a new tool. Then you can setup the tool as in the picture below.


As you can see the tool will invoke PowerShell and pass the folder cleaner tool script. Parameters can be specified by using the double underscores ‘__’ before and after the parameter name. By doing this, the parameters will become available in the workflow shapes later on.

Now we’re almost there, the only thing remaining now is adding the needed resources for the tool. When the Deployment Agent needs to run the tool, it will need the PowerShell script, our module and the related dll files that are used. By adding these references in the bottom part of the tool screen, they get deployed on the Deployment Agent when running the tool. This is actually the easiest way to get the PowerShell scripts of the standard scripts available in RM since you cannot save a local copy of those in the RM client.


So there we have our first tool. The only thing left to do now in this already grossing blog post is creating an action we can use within our deployment sequences. Next to the tools seciont, you can find the Actions tab. Now create a new action as seen below. Notice that when you select the tool this action uses, the command is copied from the tool and can be modified for this action. This is convenient when using the same tool for multiple actions that require different parameter sets.


With all of the in place, you can start using this tool in deployment sequences.


In the following blog posts, we will discuss the Release Paths / Environments and get closer to the actual Release Templates. And in between, Tools and Actions for dealing with custom Dynamics AX stuff will pop up as we go.