Dynamics 365 Business Central Wave 2: customizing the Base Application

In a previous post I described how you can start building extensions for the upcoming Dynamics 365 Business Central Wave 2 release on top of the Microsoft’s System Application.

Today I want to show you how you can directly customize the Microsoft’s Base Application (alias, the standard Microsoft codebase). This is a top request I receive every day on all the partners I met, but before starting this post, I want to put in evidence what I think (receiving this question so often is not a good sign): please avoid to do this as much as possible. From the Wave 2 release, Microsoft will permit you to modify the Base Application if needed but you should do this only if you cannot solve problems with the standard extension’s model. Please always remember that in this way you’re working like in the past.

Said that (very important to remember!) let’s start

Starting from a development environment based on a Docker container with the Wave 2 release, the first step to do is to extract the Microsoft’s source code in a local folder. You can do that with the following Powershell command:

$alProjectFolder = "C:\SD\BaseApp"
Create-AlProjectFolderFromBcContainer -containerName $containerName `
-alProjectFolder $alProjectFolder `
-useBaseLine -useBaseAppProperties -addGIT

This command extracts all the Microsoft’s source code (.AL files) in the specified folder and creates a Visual Studio Code project ready to go, with launch.json configured for your enviroment.

When you start this command, there’s an important option to consider: you can create a totally new Base Application (custom appID and Publisher) or you can use the Microsoft’s standard Base Application appID and Publisher. I prefer this second option (because it permits you to handle dependencies from the Base Application in the default standard installed apps like Intelligent Cloud Base, Sales and Inventory Forecast, Paypal etc. in a transparent way) so I’ve specified the -useBaseAppProperties setting.

Now start this comand:BaseApp_01.jpg

and your AL folder file will be ready to go (you can also have files organized automatically by using the -alFileStructure option).

In this folder you have all Microsoft’s standard objects (.AL files), a launch.json file and an app.json file for your extension. As you can see, the app.json file is configured with the same parameters as the standard Microsoft’s Base Application and it has a dependency from the System Application:


Please also note that Target is set to onPrem (you cannot do that on a SaaS environment).

You now need to download dependencies (as usual) in order to have symbols recognized. You will see a lot of warnings too in your project (future deprecated things):


What we want to do now is a (stupid for simplicity) modification to the Microsoft’s Base Application, so as a first step I change the version number from 15.0.36145.0 (Microsoft’s standard number) to 15.0.36145.1 (new minor version). Then we implement our modification directly on the standard Microsoft’s objects. Here I directly modify the Customer table in order to add a new field called SD:


and then I directly modify the Customer List page in order to add that field to the page:


P.S. This is just a simple example, there are tableextension and pageextension objects for this  Imagine to do more complex customizations like modifying standard codeunits etc.

Now our code modification is complete and we can compile the app with Visual Studio Code. If all is ok you will have a file called Microsoft_Base Application_15.0.36145.1.app in your folder:


Now we have to publish our customized Base Application. For doing that, we can uninstall the existing Microsoft’s Base Application and all its dependent extensions:


If now you try to publish your custom Base Application from Visual Studio Code, you will receive an error like the following:


“The extension could not be deployed because it’s already deployed on another tenant”.

Why this? Because Microsoft’s Base Application is deployed with a Global scope and you cannot publish an app with the Global scope. To publish your custom Base Application, you need to use the Tenant scope, so start the following command:

Publish-NavContainerApp -appFile "C:\SD\BaseApp\Microsoft_Base Application_15.0.36145.1.app" -containerName $containerName -install -scope Tenant -skipVerification -sync

Maybe you should also use the following command after the app installation:

Start-NavContainerAppDataUpgrade -appName "Base Application" -appVersion 15.0.36145.1 -containerName $containerName

At the end of this process, you have your customized Base Application installed:


You need to also republish the standard Microsoft’s dependent extensions if you want to have all the previous functionalities available again:


Now you’re ready to go! In our example, if we open the Customer List page, we can see our new SD field (added with the direct modification inside the Base Application):


As you can see in this post:

  • With Dynamics 365 Business Central Wave 2 release, you can modify the Base Application again by directly altering the Microsoft’s standard objects
  • This code base modification works only for on-premise scenarios
  • If you take this direction, you’re creating a brand new app and you’re not compliant with future releases. In the future, you will have to merge your code again.

I repeat myself again: please avoid this as much as possible. This is not the best practice to do and in this way your extension is not ready for the cloud. Remember always that “in the future, on-premise will follow cloud rules“.


Comment List