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:

BaseApp_02

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

BaseApp_03.jpg

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:

BaseApp_04.jpg

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

BaseApp_05.jpg

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:

BaseApp_06.jpg

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:

BaseApp_07.jpg

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

BaseApp_08.jpg

“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 -saveData

and then

Sync-NavContainerApp -appName "Base Application" -appVersion 15.0.36545.1 -containerName $containerName

Maybe you should also use the following command after the app installation (for preserving data):

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:

BaseApp_09.jpg

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

BaseApp_10.jpg

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

BaseApp_11.jpg

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

 

13 Comments

  1. Hi, thanks for the post. Question (maybe stupid one): what do you mean by “compile the app with Visual Studio Code”, how can this be done?

    Like

    1. As you can see in the post, you have a Visual Studio Code AL project with all the Microsoft’s source code in .al files like every other extension you create from scratch. To have a .app file to publish on D365BC you need to compile (CTRL+SHIFT+B) your project in VS Code as usual.

      Like

      1. Ok, did this exercise. But it is very very slow.. It took more than 10 minutes to compile version ‘15.0.36545.1’ and another 10-1 minutes to publish extension.. Feel like 20 years ago when you were starting compile code in the evening and by next day in the morning it was ready :)) Don’t know how Microsoft thinks this Business Central AL can be usable in the real life as it is at this moment..

        Like

  2. Hi Stefano Demiliani, thank you for the post, it’s very interesting!!! I Have a question, it is possible to do all this with out Docker container?… unzipped the “Base Application.Source.zip” located in Business Central folder Installer, then open this folder un VSCode but i have 13629 problems. Compiled the project but give me “Error: The package could not be created.” Thanks for everithing.

    Like

  3. Hi Stefano, after unzipped “Base Application.Source.zip” and downloaded symbols I’ve many error. For example in AutomationExtensionUpload.Page.al file this row was in error:

    DotNetALPackageDeploymentSchedule: DotNet ALPackageDeploymentSchedule;

    “DotNet ‘ALPackageDeploymentSchedule’ is missing.

    Where is the problem?

    Like

    1. In VS CODE try to set the following option in user settings or workspace settings:
      “al.assemblyProbingPaths”: [
      “C:\\Program Files\\Microsoft Dynamics 365 Business Central\\150”,
      “C:\\Program Files (x86)\\Microsoft Dynamics 365 Business Central\\150”,
      “C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.7.2”,
      “C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\WindowsPowerShell”
      ],

      Like

  4. Hi Stefano, thanks for the quick reply. But now in the compilation I have numerous warnings concerning syntax or objects that in the future will be errors and four error in one file that prevent the compilation.
    File is ExchangePowerShellRunner.Codeunit.al
    This is errors:
    DotNet ‘PSCredential’ is missing
    DotNet ‘ErrorRecord’ is missing
    ‘DotNet’ does not contain a definition for ‘GetEnumerator’

    How I can solve also these too?

    Thanks in advance

    Like

  5. Excuse me, Stefano, I didn’t check well. That reference was missing and I entered it.
    Now there are only two error:

    in file AzureMLConnector.Codeunit.al this row:
    AzureMLRequest.SetHttpMessageHandler(HttpMessageHandler);

    Errorr:
    Argument 1: cannot convert from ‘DotNet “System.Net.Http.HttpMessageHandler”‘ to ‘DotNet “System.Net.Http.HttpMessageHandler”‘

    Missing other reference?

    Like

  6. This is reference added in my settings.json:

    “al.assemblyProbingPaths”: [
    “C:\\Program Files\\Microsoft Dynamics 365 Business Central\\150”,
    “C:\\Program Files (x86)\\Microsoft Dynamics 365 Business Central\\150”,
    “C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.7.2”,
    “C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\WindowsPowerShell”,
    “C:\\Windows\\assembly”
    ],
    .NET Framework 4.7.2 was installed

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.