AL Extensions: Managing Version Numbering With VSTS Builds

I wanted to do this post to talk a bit more about something that Soren Klemmensen had in Part 2 of the blog series on automated builds with VSTS. We wanted to keep those original posts as simple as possible but there are a few more topics that we would like to expand upon.

In that particular post, he covered the PowerShell code needed to generate the AL extension using the ALC compiler tool, and in there is some interesting code around setting the version number of the extension package that gets created. That’s what I want to talk a bit more about here.

As we know, the version number that is assigned to the AL extension needs to be stored in the app.json that sits in the the AL project, and that value needs to be there before the compile process can be executed, like this:

ALExtensionVersion

Typically, this means that the developer is updating that value as needed before they compile and package the extension.

Wouldn’t it be nice to not have to have the developer do that every build? They’ve already got so much to worry about! 🙂

Well…it just so happens that one of the many great features in VSTS build definitions is the ability to automatically generate build numbers. Using a combination of static values and tokens, you’re able to generate any build number that you would like and in pretty much any format you would like.

You can read up on what tokens are available here, and how you can use them to build whatever format of build number you want.

In VSTS, these build numbers can be used to tag checkins so that you can track which checkin represents a build, but we’re going to leverage this and build ourselves a properly formatted version number that we will inject into the AL extension during the build process. This way, the developer can sit back and relax wait for the VSTS magic to happen!

Here’s how we’re going to do it…

1. Update build definition

We need to update our build definition to create our version number for us. We do that by populating the Build number format box on the Options tab of the build definition. Here’s where you can use the VSTS tokens and/or static text.

For this walkthrough, my version number needs to meet the following criteria:

  1. It will follow the standard #.#.#.# formatting that is required for an AL extension.
  2. It will be based on the date that the build is executed.
  3. I need to ensure I always get a unique version number even if I generate multiple builds in a day.
  4. This is the first version of my extension, so I want to make sure the version number begins with 1.0.

Given all of this criteria, I’ll populate the field like this:

BuildVersionFormat

As you can see, I am just hard-coding the “1.0.” so that every version I get begins the same. I’m using the date token (note the format can be changed if you like) so that the version contains the date on which the build is executed. Last but not least, I’m using the revision token to ensure that every time the build is executed I will get a unique version number. If you’re implementing Continuous Integration (and you really should!) you will certainly at some point have multiple builds done within the same day.

NOTE: The revision token is 1-based, so in my example the first build on a given day will end with .1 and not .0 (not what I would have preferred but what can you do).

2. Update build script

Remember I mentioned Soren’s post? In that post the following code is added to your build script. We only really need to update 1 line in this script, but I do want to talk about a few of the other lines so you know what’s going on here. The specific code we’re interested in is shown in red:

$ExtensionAppJsonFile = “.\app.json”
$ExtensionAppJsonObject = Get-Content -Raw -Path $ExtensionAppJsonFile | ConvertFrom-Json
$Publisher = $ExtensionAppJsonObject.Publisher
$Name = $ExtensionAppJsonObject.Name
$ExtensionAppJsonObject.Version = ‘1.0.’+$env:Build_BuildID + ‘.0’
$ExtensionName = $Publisher + ‘_’ + $Name + ‘_’ + $ExtensionAppJsonObject.Version + ‘.app’
$ExtensionAppJsonObject | ConvertTo-Json | set-content $ExtensionAppJsonFile
$ALProjectFolder = $env:System_DefaultWorkingDirectory
$ALPackageCachePath = ‘C:\ALBuild\Symbols’
Write-Host “Using Symbols Folder: ” $ALPackageCachePath
$ALCompilerPath = ‘C:\ALBuild\bin’
Write-Host “Using Compiler: ” $ALCompilerPath
$AlPackageOutPath = Join-Path -Path $env:Build_StagingDirectory -ChildPath $ExtensionName
Write-Host “Using Output Folder: ” $AlPackageOutPath
Set-Location -Path $ALCompilerPath
.\alc.exe /project:$ALProjectFolder /packagecachepath:$ALPackageCachePath /out:$AlPackageOutPath

 

The first 2 lines of highlighted code read the app.json file from the AL project into a PowerShell object using ConvertFrom-Json. This will allow us to read/write any of the properties within the json file:

$ExtensionAppJsonFile = ".\app.json"
$ExtensionAppJsonObject = Get-Content -Raw -Path $ExtensionAppJsonFile | ConvertFrom-Json

Now what we want to do is update the Version property with the build number that our VSTS build definition generated. We can get that value by using one of the environment variables that VSTS makes available while the build process is running. There are a bunch of environment variables available to us (see here for more info) but the one that we’re interested in is Build.BuildNumber. The value in this variable is the value that VSTS generated based on the Build number format that you populated in your build definition. If you leave that field blank, then this environment variable would be empty.

This is where we need to replace some of the code from Soren’s post. The original code (shown below) sets the version number to Build.BuildID, which is the identifier that VSTS assigns to each build:

$ExtensionAppJsonObject.Version = ‘1.0.’+$env:Build_BuildID + ‘.0’

Since we want to control the version number format using our build definition, this is where we need to make a small change. We’ll replace the above line of code with the following that will update the Version property to Build.BuildNumber:

$ExtensionAppJsonObject.Version = $env:Build_BuildNumber

Notes

  • To access VSTS environment variables in your PowerShell script, begin the variable name with ‘$env:’ and replace ‘.’ with ‘_’.
  • Because this environment variables are only generated during the build process you will not be able to manually run your PowerShell script to test the values of these variables.

Finally, we need to write our changes to the app.json file as so far we’ve only made the changes in the PowerShell object We use ConvertTo-Json for that:

$ExtensionAppJsonObject | ConvertTo-Json | set-content $ExtensionAppJsonFile

That’s It!

After you’ve done the above updates to your build definition and script, when you generate your build either manually or via trigger, your packaged AL extension will have version numbers similar to the following:

1.0.20180407.1   (first build of the day)
1.0.20180407.2   (second build of the day)
1.0.20180407.3   (third build of the day)
1.0.20180407.n   (nth build of the day)

Source code management

One of the obvious questions if you implement your build process like this is that if the version number is only updated at the time the build is done, what happens with source code management? Well to be honest, I do not track the version number of my extension in source code management at all.

Personally, I don’t see the value since when my build runs, it tags the checkin that represents that build, so at any point in time I can go back and find the source code for any build that I’ve done, and if I need to I can rebuild it.

So what do I keep in source code management? I keep all of my extension versions permanently set to ‘0.0.0.0’. This means that no developer ever needs to touch the version property during the development stage. It also helps identify if a database has a released version of my extension installed versus a pre-release development version, which does happen from time to time.

Hopefully you’ve found this useful and you’ve now updated your build definition to provide you the exact version number format that you want.

For a listing of the all the automated build articles, see my post here.

That’s it for now, happy coding!

One thought on “AL Extensions: Managing Version Numbering With VSTS Builds

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s