The “Dynamics 365 for Operations” Code Upgrade Journey from Dynamics AX 2012

December 7, 2016

By Robert Sammut

Introduction

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. If you want to read more about the architecture visit the https://ax.help.dynamics.com online Wiki. Training on D365FO can also be provided by Bluefort, more details can be found in the Academy section.

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.

tech_conf_code_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. You can read this article from Robert F. Badawy to learn more about overlayering vs extensions.

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. If you are not familiar with these tools please read the following Technet article.

axutil_export_modelstore

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.

lcs_create_project

Link to Visual Studio Teams Services (VSTS)

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 (previously known as Visual Studio Online) 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. If you haven’t yet created a VSTS account, you can create one from https://www.visualstudio.com/team-services/. 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.

lcs_vsts_setup

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.

vsts_personal_access_token

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

lcs_vsts_settings

Upload the AX2012 modelstore to LCS

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

lcs_code_upgrade_tool

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.

lcs_code_upgrade_service

Upload – Upload the compressed modelstore zip file.

lcs_code_upgrade_file_upload

 

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.

lcs_code_upgrade_completed

Interpreting the 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.

lcs_code_upgrade_migration_report

Tasklist

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‘.

lcs_code_upgrade_tasklist_report

Models Upgrade

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

VSTS

Users

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. For more details refer to the Microsoft page https://www.visualstudio.com/en-us/docs/setup-admin/add-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.

vsts_user_stories

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.

vsts_repository

Releases folder

The releases folder contains all the versions of the uploaded model stores. 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.

vsts_branch_merge

Trunk

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.

vsts_ax7version

Metadata

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.

Projects

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.

If you will have multiple developers (multiple VMs) connected to the same VSTS project each VM should be renamed. For guidance visit http://ax.help.dynamics.com/visual-studio-online-vso-machine-renaming.

Workspaces

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).

vs_workspace

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 [c] symbol means that the element has been customized.

vs_code_conflict_resolve

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.

vs_code_conflict_cf

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.

vs_code_conflict_check_in