D365 code upgrade steps

[The following article was written in 2016. Reference and screenshots are based on the LCS and VSTS (DevOps) versions available during that time. For latest information refer to Microsoft documentation available online.]

Upgrade overview

This article explains the steps to make a code upgrade from AX 2012 R3 to Dynamics 365 for Operations (D365FO) previously known as AX7. The below details assume that the reader is already familiar with the cloud architecture of D365F0. In the new Dynamics AX the AOS is now a web application running on IIS on Azure VMs, connected to Azure SQL Databases and the client is accessed from a web browser. The diagram below from the Dynamics Technical Conference in 2016 is often used by Microsoft to explain the code upgrade process. In the sections below we will be reviewing each step in more detail to make a successful upgrade.

It is important to note that the code upgrade process explained below does not necessarily mean it is the best option to upgrade your existing Dynamics AX 2012 to the D365FO solution. The automated code-upgrade process from LCS uses overlayering to upgrade the code and does not necessarily make use of extensions or any other design improvements in D365FO. Thus if you want to make use of the new designs concepts in D3650, a re-development using the new enhanced design concepts might be a better option.

Exporting the modelstore

In the first step we need to get the AX2012 R3 code. To do this you will need to export the whole modelstore (not model) to a *.axmodelstore file. You can export the modelstore using the AXUtil or Powershell tools.

Once the modelstore is exported, take the file and compress it to a zip file. You will need to upload this to Lifecycle Services in the next code-upgrade steps.

LCS Project

Microsoft Dynamics Lifecycle Services (LCS) is a web portal to manage your Dynamics AX project. If this is the first time that you are reading about LCS, please read this article to get started. Sign-in to LCS with your Microsoft account, and create a new upgrade project. Enter a suitable name for the project and select your product version. In the steps below we will be upgrading from Microsoft Dynamics AX 2012 R3.

Link to VSTS (DevOps)

Steps 2-5 in the code-upgrade diagram will be done automatically by LCS. For step 5 “Check into VSTS” to work we need to configure LCS to link with the VSTS account.

VSTS (now called DevOps) is Microsoft’s cloud-based code repository and version control system. This will be required for LCS to check-in the upgraded code to the VSTS repository. A free account can be created if you are working on a single workstation.

To link your new LCS upgrade project to VSTS, go the project settings in LCS, open the “Visual Studio Team Services” tab and click on the “Setup Visual Studio Team Services” button. In the next pages enter the VSTS site, the personal access token, and select the VSTS Team project.

The personal access token works as a password to authorize LCS to access your VSTS account. To get the access token go to your profile in VSTS, choose security and select personal access token, then create a new token for VSTS with permissions for all scopes.

Confirm that VSTS is linked to the LCS Project from Project Settings, Visual Studio Team Services.

Upload the AX2012 modelstore to LCS

From LCS, open the upgrade project and click on the “Code Upgrade” tool from the More Tools section.

After you open the code upgrade tool, click on the Add button at the bottom left-hand side of the page to start the code upgrade process in LCS.

Code upgrade service steps

Describe – Enter a name and description for the upgrade job and select the version you are upgrading from. Currently AX2012 or AX7 can be selected.

Upload – Upload the compressed modelstore zip file.

In the next steps from “Process Pending – Processing – Generating Report” – the code upgrade tool will re-baseline the code for over-layering, migrate the code, check it in into VSTS, create the TFS work items and prepare the reports. The time this process takes depends on the size of your modelstore. There is no need to keep the LCS web page open, you can sign out and check again progress at a later time or day.

Completed – When the process is completed you can:

Download the migrated code clicking on the UpgradeMetadata.zip file. The zip file will contain the D365FO code in XML files and the Visual Studio solutions to open the code in a Visual Studio.

Open the code migration results (Microsoft Excel files). The results will give you details on the number of upgraded elements, code conflicts and approximate upgrade times. Mode details on the results are provided in the next section.

Code upgrade results

At the moment the LCS code upgrade tool provides 4 reports, the two main reports being the migration summary and the task list.

AX7 metadata version

This contains the Dynamics AX version number that the code was upgraded against. For example in our upgrade project the metadata was rebaselined against build: 7.1.1541.3036.

Migration Summary

The migration summary is an overview of what was upgraded and the number of elements with conflicts.


The task list report contains useful information for development. It enlists the tasks sorted by priority. Microsoft recommends that conflicts should be resolved in the sequence provided in the order column, always starting with the base model ‘ApplicationPlatform‘.

Models Upgrade

The models upgrade report is a list of models that were upgraded and merged with the upgraded metadata.



Assuming that on the upgrade project there will be more than one developer you will need to add the developer accounts to the VSTS Team Project. Only a Project Administrator on the Team project has permissions to add more users.

Work Items

The LCS code upgrade project automatically creates work items (tasks) in your Team Project. For each code conflict and upgrade task a work item is created and grouped in a user story (using the Agile process template). Work items can then be assigned to individual developers to work in parallel. User stories and work items are sorted by priority – always starting from the Application Platform first.

For each ‘task’ work item LCS automatically adds a description of the element to resolve, model and layer name, priority and a number of tags that makes it easier to look for specific work items.

Code repository

The VSTS code repository for the Team Project is structured as in the image below.

Releases folder

The releases folder contains all the versions of the uploaded modelstores. If you had already uploaded a modelstore on a previous version of AX build, the LCS code upgrade tool will not automatically merge it to the Trunk, you will have to do this manually.

The release folder has the same folder structure as the Trunk/Main TFS folder. You can therefore merge the release folder to the trunk by right-clicking on the release folder, select ‘branching and merging’ and choose ‘Merge’. The merge wizard will then open as shown below, select all changes and proceed with the merge using default settings.


The Trunk contains the code and projects that developers needs to synch with their developers to resolve the conflicts. To check the current version of the Trunk you will see an ax7.version file in the Main Folder. This shows the current release number that is merged on the Trunk.


The metadata contains the migrated code in XML files. The folder structure of the metadata is split by packages and models so that you can synch this with main packages folder of the development environment (currently at C:\AOSService\PackagesLocalDirectory). If you are not familiar with the packages concept in D365FO please read more about the new Dynamics AX development architecture from the AX Help Wiki.


In the projects folder you will find three Visual Studio solutions:

CodeMergeSolution: This solution contains Visual Studio projects (one project per model) with the elements that have conflicts and need to be resolved.

UnparsableSolution: Sometimes a table/class can be have a comment or curly bracket which the code upgrade tool is not able to parse properly. Any files that were not converted to XML are added to this UnparsableSolution.

Microsoft recommends to resolve conflicts in this solution first.

UpgradedSolution: Contains a collection of projects, one for each upgraded model.

Development environment

VM setup

For this demo we downloaded the latest D365FO VM (Version 1611 Platform Update 3) from the Microsoft Connect website https://connect.microsoft.com/site1321/Downloads *.

* The Dev Box VM (VHD file) con now be downloaded from LCS Asset Library.

If you will have multiple developers (multiple VMs) connected to the same VSTS project each VM should be renamed.


From the downloaded VM, open the developer’s development environment which is now Visual Studio (it’s no longer MorphX dev environment) in D365FO, connect to VSTS and configure the workspace to synch with the Trunk Metadata and Projects.

Trunk/Main/Metadata > C:\AOSService\PackagesLocalDirectory

(Assuming that that your packages folder is located at c:\AOSService\PackagesLocalDirectory).

Trunk/Main/Projects > C:\Users\Administrator\Documents\Visual Studio 2015\Projects

(The local developer’s Visual Studio projects location)

Local vs Server Workspace

In recent years Microsoft introduced local workspaces, a new concept that makes working offline much easier from the traditional server workspace. Microsoft explains that “a local workspace caches the unmodified version of each of your files to enable you to edit, compare, and do other things without being connected to the server”. With local workspaces the source code files in TFS are no longer read-only by default and allow files to be edited without a check-out (check-out locks are un-enforceable). This also means that with local workspace developers cannot see pending changes from what other developers (team members) have checked-out.

To switch to a traditional server workspace which does not allow multiple check-outs a user with administrative rights needs to change this setting from the project collection. For more detailed instructions on how to change from a local workspace to a server workspace follow this link:  https://www.visualstudio.com/en-us/docs/tfvc/decide-between-using-local-server-workspace.

Resolving the code conflicts

The approach you take to resolve the conflicts depends on your upgrade strategy and delivery timeframes. Microsoft does not oblige you to follow a procedure but provides a number of tools that can make it easier to upgrade the code.

The work items can be used to split tasks within development teams, they also sorted by priority starting from the Application Platform conflicts first.

When you open the CodeMergeSolution you can go to each conflict. A conflict will be shown as [!] symbol next to the element. The symbol means that the element has been customized.

To view the conflict, open the element in designer mode and you will see the red arrows symbol next to each conflicting method. From the designer view use the cf: command to filter conflicting methods only as shown below.

To compare the code between the Application Baseline and the customized code use the merge tools provided in Visual Studio. Once you have made the code changes to resolve the conflict, right-click the element and select “Resolve code conflicts” to remove the [!] symbol.

When the code changes are ready, use the Team Explorer pending changes to check-in the changes and link them back to the work item.

Article written for Bluefort Malta.