Behold #XppGroupies! The day we’ve been waiting for has come! The Azure-hosted builds are in public preview with PU35!! We can now stop asking Joris when will this be available because it already is! Check the docs!
I’ve been able to write this because, thanks to Antonio Gilabert, we’ve been testing this at Axazure for a few months with access to the private preview. And of course thanks to Joris for inviting us to the preview!
What does this mean? We no longer need a VM to run the build pipelines! Nah, we still need it! If you’re running tests or synchronizing the DB as a part of your build pipeline you still need the VM. But we can move CI builds to the Azure-hosted agent!
You can also read my full guide on MSDyn365FO & Azure DevOps ALM.
Remember this is a public preview. If you want to join the preview you first need to be part of the Dynamics 365 Insider Program where you can join the “Dynamics 365 for Finance and Operations Insider Community“. Once invited you should see a new LCS project called PEAP Assets, and inside its Asset Library, you’ll find the nugets in the Nuget package section.
With the capacity to run an extra Azure-hosted build we get another agent to run a pipeline and can run multiple pipelines at the same time. But it still won’t be parallel pipelines, because we only get one VM-less agent. This means we can run a self-hosted and azure hosted pipeline at the same time, but we cannot run two of the same type in parallel. If we want that we need to purchase extra agents.
With a private Azure DevOps project we get 2GB of Artifacts space (we’ll see that later) and one self-hosted and one Microsoft hosted agent with 1800 free minutes:
We’ll still keep the build VM, so it’s difficult to tell a customer we need to pay extra money without getting rid of its cost. Plus we’ve been doing everything with one agent until now and it’s been fine, right? So take this like extra capacity, we can divide the build between both agents and leave the MS hosted one for short builds to squeeze the 1800 free minutes as much as possible.
How does it work?
There’s really no magic in this. We move from a self-hosted agent in the build VM to a Microsoft-hosted agent.
The Azure-hosted build relies on NuGet packages to compile our X++ code. The contents of the PackagesLocalDirectory folder, platform, and the compiler tools have basically been put into nugets and what we have in the build VM is now on 3 nugets.
When the build runs it downloads & installs the nugets and uses them to compile our code on the Azure-hosted build along with the standard packages.
What do I need?
To configure the Azure hosted build we need:
- The 3 nuget packages from LCS: Compiler tools, Platform X++ and Application X++.
- A user with rights at the organization level to upload the nugets to Azure DevOps.
- Some patience to get everything running 🙂
So the first step is going to the PEAP LCS’ Asset Library and downloading the 3 nuget packages:
Azure DevOps artifact
All of this can be done on your PC or in a dev VM, but you’ll need to add some files and a VS project to your source control so you need to use the developer box for sure.
Head to your Azure DevOps project and go to the Artifacts section. Here we’ll create a new feed and give it a name:
You get 2GB for artifacts, the 3 nuget packages’ size is around 500MB, you should have no issues with space unless you have other artifacts in your project.
Now press the “Connect to feed” button and select nuget.exe. You’ll find the instructions to continue there but I’ll explain it anyway.
Then you need to download nuget.exe and put it in the Windows PATH. You can also get the nugets and nuget.exe in the same folder and forget about the PATH. Up to you. Finally, install the credential provider: download this Powershell script and run it. Edit: if the script keeps asking for your credentials and fails try adding -AddNetfx as a parameter. Thanks to Erik Norell for finding this and sharing it in the comments!
Create a new file called nuget.config in the same folder where you’ve downloaded the nugets. It will have the content you can see in the “Connect to feed” page, something like this:
<?xml version="1.0" encoding="utf-8"?>
<add key="AASBuild" value="https://pkgs.dev.azure.com/aariste/aariste365FO/_packaging/AASBuild/nuget/v3/index.json" />
This file’s content has to be exactly the same as what’s displayed in your “Connect to feed” page.
And finally, we’ll push (upload) the nugets to our artifacts feed. We have to do this for each one of the 3 nugets we’ve downloaded:
nuget.exe push -Source "AASBuild" -ApiKey az <packagePath>
You’ll get prompted to enter the user. Remember it needs to have enough rights on the project.
Of course, you need to change “AASBuild” for your artifact feed name. And we’re done with the artifacts.
Prepare Azure DevOps
This new agent needs a solution to build our packages. This means we have to create an empty solution in Visual Studio and set the package of the project to our main package. Like this:
If you have more than one package or model, you need to add a project to this solution for each separate model you have.
We have to create another file called packages.config with the following content:
<?xml version="1.0" encoding="utf-8"?>
<package id="Microsoft.Dynamics.AX.Platform.DevALM.BuildXpp" version="7.0.5644.16778" targetFramework="net40" />
<package id="Microsoft.Dynamics.AX.Application.DevALM.BuildXpp" version="10.0.464.13" targetFramework="net40" />
<package id="Microsoft.Dynamics.AX.Platform.CompilerPackage" version="7.0.5644.16778" targetFramework="net40" />
The version tag will depend on when you’re reading this, but the one above is the correct one for PU35. We’ll need to update this file each time a new version of the nugets is published.
And, to end with this part, we need to add the solution, the nuget.config, and the packages.config files to TFVC. This is what I’ve done:
You can see I’ve created a Build folder at the root of my DevOps project. That’s only my preference, but I like to only have code in my branches, even the projects are outside of the branches, I only want the code to move between merges and branches. Place the files and solution inside the Build folder (or wherever you decide).
Now we need to create a new pipeline, you can just import this template from the newly created X++ (Dynamics 365) Samples and Tools Github project. After importing the template we’ll modify it a bit. Initially, it will look like this:
As you can see the pipeline has all the steps needed to generate the DP, but some of them, the ones contained in the Dynamics 365 tasks, won’t load correctly after the import. You just need to add those steps to your pipeline manually and complete its setup.
You need to select the Hosted Azure Pipelines for the Agent pool, and vs2017-win2016 as Agent Specification.
I’ve mapped 2 things here: our codebase in the first mapping and the Build folder where I’ve added the solution and config files. If you’ve placed these files inside your Metadata folder you don’t need the extra mapping.
NuGet install Packages
This step gets the nugets from our artifacts feeds and the installs to be used in each pipeline execution.
The command uses the config files we have uploaded to the Build folder, and as you can see it’s fetching the files from the $(build.sourcesDirectory)\Build directory we’ve configured in the Get sources step. If you’ve placed those files in a different place you need to change the paths as needed.
Update Model Version
This is one of the steps that are displaying issues even though I got the Dynamics 365 tools installed from the Azure DevOps marketplace. If you got it right you probably don’t need to change anything. If you have the same issue as me, just add a new step and select the “Update Model Version” task and change the fields so it looks like this:
In the build solution step, you have a wildcard in the solution field: **\\*.sln. If you leave this wildcard it will build all the projects you have in the repo and, depending on the number of projects you have, the build could time out.
I solve this by selecting a solution, that contains all the models I have, that I have placed in the Build folder in my repo, and update that solution if you add or remove any model.
Thanks to Ievgen Miroshnikov for pointing this out!
There could be an additional issue with the rnrproj files as Josh Williams points out in a comment. If your project was created pre-PU27 try creating a new solution to avoid problems.
Create Deployable Package
This is another one of the steps that are not loading correctly for me. Again, add it and change as needed:
Add Licenses to Deployable Package
Another step with issues. Do the same as with the others:
And that’s all. You can queue the build to test if it’s working. For the first runs, you can disable the steps after the “Build solution” one to see if the nugets are downloaded correctly and your code built. After that try generating the DP and publishing the artifact.
You’ve configured your Azure-hosted build, now it’s your turn to decide in which cases will you use the self-hosted or the azure hosted build.
Update for version 10.0.18
Since version 10.0.18 we’ll be getting 4 NuGet packages instead of 3 because of the Microsoft.Dynamics.AX.Application.DevALM.BuildXpp NuGet size is getting near or over the max size which is 500MB and will come as 2 NuGet packages from now on.
There just 2 small changes we need to do to the pipeline if we’re already using it, one to the packages.config file and another one to the pipeline.
The packages.config file will have an additional line for the Application Suite NuGet.
<?xml version="1.0" encoding="utf-8"?>
<package id="Microsoft.Dynamics.AX.Platform.DevALM.BuildXpp" version="7.0.5968.16973" targetFramework="net40" />
<package id="Microsoft.Dynamics.AX.Application.DevALM.BuildXpp" version="10.0.793.16" targetFramework="net40" />
<package id="Microsoft.Dynamics.AX.ApplicationSuite.DevALM.BuildXpp" version="10.0.793.16" targetFramework="net40" />
<package id="Microsoft.Dynamics.AX.Platform.CompilerPackage" version="7.0.5968.16973" targetFramework="net40" />
We need to add a new variable to the pipeline variables called AppSuitePackage with the value Microsoft.Dynamics.AX.ApplicationSuite.DevALM.BuildXpp.
And then use it in the build step and change it to:
/p:BuildTasksDirectory="$(NugetsPath)\$(ToolsPackage)\DevAlm" /p:MetadataDirectory="$(MetadataPath)" /p:FrameworkDirectory="$(NuGetsPath)\$(ToolsPackage)" /p:ReferenceFolder="$(NuGetsPath)\$(PlatPackage)\ref\net40;$(NuGetsPath)\$(AppPackage)\ref\net40;$(MetadataPath);$(Build.BinariesDirectory);$(NuGetsPath)\$(AppSuitePackage)\ref\net40" /p:ReferencePath="$(NuGetsPath)\$(ToolsPackage)" /p:OutputDirectory="$(Build.BinariesDirectory)"