In October 2022, Microsoft announced a new open-source program for the Business Central Base Application, the solution’s core functionality. The program allows partners and community members to contribute code and suggestions to the Base Application.
The open-source program for Business Central is an excellent opportunity for anyone who wants to learn more about the solution, contribute to its development, and benefit from its features.
In May 2023, we were fortunate enough to converse with Jesper and KB on the Dynamics Corner Podcast about Empowering Community Contributions. During that podcast, I asked, “How do you get started with open source?” to which both Jesper and KB responded. KB suggested observing and participating in the Pull Requests to see how the process works. After the episode, I was more excited about the program than before and started following the activity a bit more closely. I watched the interactions between community members, contributors, and Microsoft. After a period, I felt comfortable jumping into the pool and trying my hand at contributing to the base app.
First Steps
The BusinessCentralApps repository is private; you must request access before you begin. If you want to participate in the Microsoft Dynamics 365 contribution pilot, message Jesper on Yammer (Viva Engage). Let him know I sent you and request access to the BusinessCentralApps repository on GitHub.
After watching, as suggested, the lifecycle of issues, the interaction between contributors, and the pull request process for a period, it was time for me to get going. I have been working with Business Central my entire career and was excited at the opportunity to contribute to the Base App.
The Issue
I browsed through the issues and found “Issue #518 sales rep assigned to ship to address.” This issue was a perfect first issue for me to tackle, so I assigned it to me and started my journey.
I forked the repository and created a new branch for the issue. With an issue assigned and a working branch, I was excited to begin working on it. There was one more thing I needed: an environment to work in – one that allowed me to edit, package, and publish the BaseApp, which is different from the usual Business Central development. Development in Business Central is done with extensions that extend or interact with the Base Application. So, I needed to make a Docker container that allowed for the packaging and installing my modified version of the BaseApp. Sounds easy, but how?
The Environment
Now that I had an issue and a repository with a branch to work in, I needed a place to do all the magic. I needed an environment. Publishing the BaseApp file to an Online Environment, Production, or Sandbox is prohibited. Therefore, I needed a local environment, and thankfully, I used Docker regularly and knew a container would work for the cause. (Note: Docker and BCContainerHelper are required for this process)
There are two ways to create a local environment that allows the modification of the BaseApp: The Manual Way and The Easy Way. I’ll cover the manual way first. You never know if you’ll want to set up a container that allows modifying the BaseApp without access to the Contribution Pilot Repository. If you’re not interested in the manual process, then jump to The Easy Way.
The Manual Way
Create a container using BCContainer helper for the latest W1 artifact (or the version that matches the repo). The BaseApp repository is the W1 version; you should work with the same.
$artifactUrl = Get-BCArtifactUrl -version 23 -country "w1" -select Latest -type Sandbox
or
$artifactUrl = Get-BCArtifactUrl -country "w1" -select NextMajor -accept_insiderEulaOnce the container is built, you need a Business Central Base App project. BCContainerHelper to the rescue! Within BCContainerHelper there is a function Create-AlProjectFolderFromBcContainer. The Create-AlProjectFolderFromBcContainer creates a VS Code project from a container.
$containerName = '<yourcontainername>'
$alProjectFolder = '<pathtoyourprojectfolder>'
Create-AlProjectFolderFromBcContainer `
-containerName $containerName `
-alProjectFolder $alProjectFolder `
-useBaseLine `
-useBaseAppProperties `
-addGIT With the project created, we’re ready to get moving. Before we can have some fun, we need to, well, I needed to open the BaseAndTests workspace and make a few changes. Change the app file version to something higher than the current app version. Add the “tenant”: “default” to the launch file created as part of the project.
The next thing to do is download symbols from your container, open up your Business Central container, and uninstall the Base App through extension management. When you uninstall the Base App, all the dependent apps will also be uninstalled.
Package your version of the Base App and Publish it to your container using the BCContainerHelper’s Publish-NavContainerApp function.
Publish-NavContainerApp `
-appFile <PathandNameofYourAppFile> `
-containerName <YourContainerName> `
-scope Tenant `
-skipVerification `
-ignoreIfAppExists `
-sync `
-syncMode ForceSync Then, upgrade your environment using the BCContainerHelper’s Start-NavContainerAppDataUpgrade function and install the extension.
Start-NavContainerAppDataUpgrade -appName 'Base Application' -appVersion <YourAppVersion> -containerName <YourContainerName> The Easy Way
Microsoft has made it simple to create a development environment for modifying the BaseApp. This makes it easier for more developers to contribute, eliminating the need to do anything outside the standard development lifecycle besides running a script. As developers, let’s focus on what we do best – develop.
Browse to the \BusinessCentralApps\App\.AL-Go folder and run the localDevEnv.ps1 PowerShell Script.
The script will prompt you for the Container Name, authentication mode, and license file. The license file is used for specific scenarios, not general contributions, and does not need to be loaded. Accept the license agreement, and you’re off.
Note: You may need to install the GitHub CLI on your environment and authenticate with your GitHub login. The commands are listen below. You’ll need to follow the prompts.
winget install --id GitHub.cli
gh auth loginAfter you built the environment (container), if you do not have system settings for the al.assemblyProbingPaths, open the BaseAndTests.code-workspace and add it or the local project settings file and add the path to your container packages. Listed is an example of what I use for the probing path settings:
"al.assemblyProbingPaths": [
"./.netpackages",
"C:/ProgramData/BcContainerHelper/Extensions/<yourcontainername>/.netPackages/",
"C:/Windows/Microsoft.NET/Framework64",
"C:/Program Files (x86)/Reference Assemblies/Microsoft/WindowsPowerShell/3.0"
],After cloning your repository and building your environment, you can develop and publish from VS Code to your container with the BaseAndTests.code-workspace.
The Changes
I had an issue assigned and a usable environment set up. All that was left was to develop the changes to solve the requirement listed in the issue. I worked through the changes and committed them to my working branch. With my committed modifications and satisfaction with the changes, I nervously created a Pull Request and patiently waited for something to happen, and it did….
I started receiving valuable feedback on the Pull Request from community members. There were several changes and back and forth, which all resulted in a better contribution. After a few iterations, I woke up one morning to…
The Approval
The whole process took about six weeks and was well worth it. It was a fantastic experience that helped me drive towards better code, understand more of the process, and leave me proud to have contributed. I look forward to making many more enhancements to the base app.
I am excited to have a contribution that will be part of the April 2024 wave release of Business Central. The pull request can be found here .
We were fortunate to follow up with Jesper, KB, and Andrei on another In the Dynamics Corner Chair episode in February 2024. Listen to both episodes, head to the BusinessCentralApps repository, and contribute!