In a not too distant future you may find yourself wanting to migrate your C/AL code customizations to AL apps that are compatible with Microsoft Dynamics 365 Business Central, but unsure about how exactly to go about that. If you can imagine that scenario, then keep reading. In this article we'll explain how you could go about achieving that with a few, easy-to-follow steps.

1. Divide and conquer

Before you start migrating your code customizations to apps, ask yourself a few questions. The answers are essential for completing the mission:

  1. Do I need to migrate my entire customization to a single app, or can I split it into smaller, more manageable components?
  2. Do I really need all the functionality for my story to be complete?
  3. Are there any parts of my app that are outdated, and need a refresh anyway?

Avoid trying to rip up the tree by its roots. Likewise, don’t try to migrate your entire customization to an app in a single go. Instead, componentize it as much as you can and then migrate the components one-by-one.

Also, get rid of irrelevant or outdated functionality, and figure out the minimum viable scope for your app. Refactor and rethink your architecture to prepare for the move from code customization to apps. Migrating the components of your solution one by one will give you incremental successes and visible progress.

Truth be told, this step is far from trivial to complete, but in this article, we’ll move forward, as we want to get to the point where we do the actual migration.

2. Isolate and refactor your component

The next step is to isolate the component you want to migrate. First, you'll need to create a Docker container to do the refactoring in. If you’re new to Docker, you can read more about how to get started here.

You’ll also need the navcontainerhelper module. To get the module, in Windows PowerShell, run install-module navcontainerhelper -force.

Pick the same version for the container as the version your code customization is in. This example uses a NAV 2017 NA CU3. To create your Docker container, run the following command:

# Create NAV 2017 NA CU3

New-NavContainer -accept_eula `

                 -imageName "microsoft/dynamics-nav:2017-cu3-na" `

                 -containerName "nav2017" `

                 -licenseFile "<path>" `

                 -Credential “<your credentials>” `

                 -updateHosts `


You now have a container-based NAV 2017 C/SIDE environment to work in. But before we go there, we need to export your customized C/AL code. Pick the code that makes up your component, and export it as TXT or FOB. When that's done, go ahead and import your component in your new container-based C/SIDE environment. There you can safely change and refactor for the next steps. Your modified objects should have the Modified flag, because we’ll use that flag as an indicator for what should get migrated. Use your preferred client to verify that your code works.

Then, the next step is to export your solution into deltas by running one simple command:

Export-ModifiedObjectsAsDeltas -containerName nav2017 -openFolder

The folder opens automatically, and you can inspect the deltas one-by-one. Apps are code extensions and therefore don't allow for code modifications, like deltas do. That means that you need to refactor your code to remove all code modifications in the deltas.

This is the toughest part of the process, and again goes beyond the scope of this article, but you can get assistance on refactoring from our community. Keep refactoring in C/SIDE until your deltas are clean. You can rerun the Export-ModifiedObjectsAsDeltas as often as you like.

3. Convert to an App

Now that the code is nicely decoupled, you’re ready for the answer to the core question this article addresses: how do I turn my C/AL code into an AL App? For that, you need yet another Docker container. To get one, use the New-NavContainer command again:

# Create temp Business Central Sandbox Container for conversion

New-NavContainer -accept_eula `

                 -imageName "microsoft/bcsandbox " `

                 -containerName "temp" `

                 -licenseFile "<path>" `

                 -Credential “<your credentials>” `

                 -updateHosts `

                 -additionalParameters @("-e WebClient=N","-e httpsite=N")

By using three simple commands, you “automagically” convert all deltas in your delta folder to AL files, using the newly created temporary container:

Import-DeltasToNavContainer -containerName "temp" -deltaFolder "C:\ProgramData\NavContainerHelper\Extensions\nav2017\delta"

Compile-ObjectsInNavContainer -containerName "temp" -filter "Modified=Yes"

Convert-ModifiedObjectsToAl -containerName "temp" -startId <your start id> -openFolder

And that’s it! After the last command completes a folder with your freshly baked AL objects will open. Now, all you need to do is to spin up a sandbox and create an extension as described here, and copy your AL objects into your newly created extension. Hit F5, and then take your new app for a spin.

Granted, this article is heavily simplified. Some of the steps require hours, days, and even weeks of complete. But the hope is that some of the commands and the Docker approach will make it easier for you to migrate your C/AL customizations to AL apps. Best of luck!

Get a list of all posts in the Holiday count down series here: