Customization INSIDE the System Application in Dynamics 365 Business Central
In Business Central 2019 release wave 2 we’re introducing a shift in the story around customization. In fact, it’s a big step toward a future where the term “extend” has replaced “customize.”
To make Business Central lighter and easier to maintain and upgrade, we’re componentizing its platform and business logic in the System Application. If you’re interested in what that’s all about, see the following post.
In a previous post we looked at how to build new functionality on top of the System Application. But what if you find something that you want to change inside a module in the System Application? Let’s see how you can do that and then build your own version of System Application.
Note: Because the System Application is part of Business Central 2019 release wave 2 it isn’t yet publicly available. To get access you’ll need to join the ReadyToGo program so that you can use Microsoft Collaborate and our insider builds.
This example will walk you through the following steps:
- Get the latest Docker image.
- Prepare the environment for code customization.
- Publish and install a new version of System Application.
- Share your great work with others.
Get the latest Docker image
Start by pulling the latest Docker image (current walkthrough based on build 15.0.34197). To do that, run the following command.
docker pull bcprivate.azurecr.io/bcsandbox-master:base-ltsc2019
After that, we need to create a Docker container. We can use our favorite PowerShell script to do that, we just need to be sure to add the useCleanDatabase parameter. There are several ways to do this, and if you’re interested you can find more information in this post. For the sake of this example, however, here’s how I do it:
$credential = New-Object System.Management.Automation.PSCredential -argumentList "admin", (ConvertTo-SecureString -String "P@ssword1" -AsPlainText -Force) $imageName = "bcprivate.azurecr.io/bcsandbox-master:base-ltsc2019" $licensePath = "C:\..\l.flf" #put actual path to your license $containerName = "BC" New-BCContainer -accept_eula ` -updateHosts ` -containerName $containerName ` -auth NavUserPassword -Credential $credential ` -imageName $imageName ` -licenseFile $licensePath ` -doNotExportObjectsToText ` -includeAL ` -useCleanDatabase ` -memoryLimit 16g `
The container will start as a process and the output of the function will display in the PowerShell output. Among other parameters we can find the URL for the web client, which we’ll open in a later step. Now we need to replace the standard System Application from Docker image with our own version.
Run the following cmdlet to uninstall and unpublish System Application:
UnPublish-NavContainerApp -containerName $containerName ` -appName "System Application" ` -unInstall ` -doNotSaveData
Prepare the environment for code customization
We now have a blank environment, but we can’t use it yet because it’s missing a few application objects (for example, the default Role Center) that are required.
Let’s open VS Code and start enhancing an existing module or building our own version of the System Application.
Note: We need the latest version of the AL extension for VS Code. The PowerShell output contains the link to the .vsix file, so we can download it from the container.
1. In VS Code, run the AL:Go! command to create a new AL Project, and then choose 4.0 as the Target Platform.
Note: The project folder should be in a location that is shared with the container. For example, a folder in C:\ProgramData\NavContainerHelper will work.
2. Update the Server and Server Instance parameters in the launch.json file with values from the PowerShell output.
3. Delete the HelloWorld.al and app.json files.
Now we’re ready to code. Rather than building the System Application from scratch, we can get the latest code from ALAppExtensions repository on GitHub. To do that, we’ll follow these steps:
- In GitHub, choose the Clone or Download button, and then Download ZIP.
- Open the downloaded archive and copy the content of the \ALAppExtensions-master\Modules\System folder to our AL project.
Now we have the latest version of the System Application and can download symbols and make enhancements.
Publish and install your System Application
When we’re done, we’ll package the System Application without publishing it.
To publish and install a new version of the System Application, we’ll run the following cmdlet in PowerShell:
Publish-NavContainerApp -containerName $containerName ` -appFile "C:\ProgramData\NavContainerHelper\AL\DemoSolution\Microsoft_System Application_15.0.0.0.app" ` -skipVerification ` -sync ` -syncMode ForceSync ` -install
Now let’s open a web browser and check out how our enhanced System Application works.
We’ll repeat the UnPublish-NavContainerApp, modify AL, and Publish-NavContainerApp steps until we’re happy with the results.
We’ll repeat the UnPublish-NavContainerApp, modify AL, and Publish-NavContainerApp steps until we’re happy with the results.
Share your improvement
When we’re done, we may want to share our enhancements with Microsoft and others. For information about how to do that, see this blog post. Note, however, that there is a difference. We will use a container rather than a cloud sandbox. Otherwise, the steps are the same.
The System Application is a work in progress, and new modules will be added in the future. If you want to peek at the latest, you can always go to the GitHub repository https://github.com/Microsoft/alappextensions. While you’re there, if you see something you think we’ve missed, you can submit a pull request and we might add it. Additionally, if you think we’ve left out a module, you can submit an idea on https://aka.ms/bcideas.
