Upgrading code from AX 2012 to D365 can be a daunting task. MS has given us some tools to help but we'll go through a high level overview of the available tools and methodologies to get the process started.

Start with LCS

LCS has some tooling to help upgrade some code as well as create tasks in Azure DevOps to manage the customizations from 2012 that it couldn't resolve. The code upgrade tool will bring all customizations into an overlayer model in the package that the base element is in. For instance. if you have customizations on table SalesTable, this will show up in an overlayer model in the Applicaiton Suite package. If you have any customizations on table Batch, that will be converted into an overlayer model in the Application Platform package. If the element is new, such as table MyNewTable, it will be converted into a table element in the Application Platform package in an overlayer model. If you have a large code base, the LCS code upgrade tool will issue an error after 10000 items in Azure DevOps has been created but the overall result of the upgrade will not be compromised. Other than those few call outs, it's a fairly straight forward process.

To find out more about the LCS Code upgrade tool, go to https://docs.microsoft.com/en-us/dynamics365/unified-operations/dev-itpro/lifecycle-services/configure-execute-code-upgrade

Getting Started

The LCS code upgrade tool will commit all of the upgraded code into Azure DevOps. The next step is to get connected with a dev machine and pull the code down to review. Once everything is mapped and synced, open up the Source Control Explorer and navigate to one of the overlayer models that were created, like so.

Let's use classes as an example. Any classes that were created as new classes, such as MyNewClass, will show up in the AxClass directory. Any that were system elements that have been customized will show up in the delta directory. In order to get started, you will have to create a package and model to store your customzations and new elements. There are 2 basic problems you will be solving. The first will be just moving (net) new elements into your new package and model. This is fairly easy as you are just managing references and updating your elements to play nice with any changes on system elements that may have changed. The second is refactoring all of your customiations on system elements into extensions. This is were the bulk of the work lies when upgrading code.

Processing (Net) New Elements

From in the AxClass directory, you simply need to move your new elements into the package / model. To do this, right click on the element then select move, like so.

The simply select the newly created package / model for the like so:

Once moved, compile the model you moved the element to ( and ONLY that model for the time being ). This will call out if there are any requirements for the element. If it referred to a system element that has changed, let's say a method was removed or renamed, then we will get a compile error and we'll have to address whatever the issue is. There is the concept of relaxing available for develop machines that we'll discuss in a later article. 

Addressing Overlayered Elements

Next, let's take a look in the delta directory. This will be all system elements that have been overlayered and will need to be converted to extensions. To get an idea of what changed, there are two major tools to assist with this. First, find a class in delta.

Next, right click on it we'll want to look at the output of 2 tools: Compare code with baseline and Compare metadata with baseline.

Compare Code with Baseline

This will give you diff between the baseline for the element and the overlayer telling you want needs to be refactored into extensions. This will capture new methods as well as changes in existing methods on the system element that was overlayered. This tool is focused on code changes and not metadata changes. Notice the two gray bars on the right hand side. They will show green for new code and red for code that has been deleted and also will show these colors on either the left or right preview windows to show that either code was removed or added on either the left or the right with the left being the base element and the right hand side being the overlayered element. In the example below, we have our simplest use case. We have a class that is overlayered with some new methods and that's it. 

Compare Metadata with Baseline

This tool will show you what metadata changes have been made to the element. Metadata changes are changes like new methods, fields, field groups, indexes and similar. Anything highlighted is a difference that needs to be addressed. Depending on the element type, some issues presented here may be addressed by code changes rather than direct metadata changes, such as new methods. This is the same example as above and again it is calling out that we only new methods and nothing else. When we convert this to an extension and remove the overlayered code, we'll also remove the metadata for those methods.

Between the two tools, that should give you enough to get started on upgrading code. We'll discuss upgrade patterns and how to work through common issues in another post.

Other Ways To Look At This - Try to Relax!

Depending on the element type, there are other more informative ways to see what needs to be resolve. One way is to just open the designer view, if applicable. This is an example of what you'd see for a class. 

Depending on the conflict type, you can right click on the method the go to "Resolve Code Conflicts". This will bring up a familiar merge window.

However, System models are set to not allow you to make any changes. Enter "Relaxing". Find the descriptor file for the model you are working against for a given package and change the value of "Customization" in the XML to "Allow". This will let you take 1 or more overlayers and merge them into 1 master change set to refactor into extension(s). In the above I have a USR, VAR and SYS I have to reconcile so my plan is to combine USR and VAR then take the result of that and either refactor that OR merge that into SYS then take all of those changes and refactor them into something that makes no changes to the SYS SalestableType class.

Corner Cases

What if you have a customization on something that is no longer there? Again, open the designer view and look for the conflicts node and see what it has, if anything. Below is an example of a change to a 2012 SYS method that doesn't exist anymore. I have to decide if I want to keep that code and if so, refactor it somewhere to get the same net affect. Any other changes, exceptions or item left to be resolved here so be sure to check this out before you mark something as complete and delete the overlayer.