Use the BcContainerHelper
BcContainerHelper is a collection of PowerShell scripts and cmdlets that are created by Microsoft to help you, as a developer, create and manage containers for Business Central development. BcContainerHelper is also useful in a DevOps environment to configure build pipelines that use containers. These scripts provide a user-friendly way to handle many of the commonly used actions on a Business Central container.
To create a new container, you can use the New-BcContainer cmdlet instead of the docker run command. In the script, the cmdlet uses the docker run command, but it only provides easier access and usage.
The source code of BcContainerHelper can be found on GitHub.
Before you can start, you need to install this module within PowerShell. Open a PowerShell command and use the install-module cmdlet.
install-module bccontainerhelper -Force
Create a new Business Central container
To create a new Business Central container, you can use the New-BcContainer cmdlet. Even simpler, you can use the New-BcContainerWizard cmdlet. With this wizard, creating a new Business Central container is easier. This cmdlet is part of BcContainerHelper. However, a newer version of the script might be available online. We recommend that you use the following script to start the wizard.
Invoke-Expression (New-Object System.Net.WebClient).DownloadString("http://aka.ms/bcdockerscript")
The wizard will guide you through the different steps:
Accept Eula.
Select Local Container or Azure VM.
Configure desired authentication.
Set a container name.
Select a version.
Select a country/region.
Install the Test Toolkit.
Assign Premium Plan users.
Create test users.
Upload a license.
Use the Cronus Demo database or connect to an existing database.
Configure DNS.
Select Process or Hyper-V Isolation.
Select the memory limit.
Save the image.
Create a PowerShell script.
The result and final step in the wizard process involve the creation of a PowerShell script. This PowerShell script will use the New-BcContainer cmdlet to run the container. You can save this script for later use.
The generated script can be used whenever you want to create a new container. The generated script uses the Get-BcArtifactUrl cmdlet to retrieve a link to the Business Central artifact. This artifact contains the specified version of Business Central.
$containerName = 'MyDevContainer'
$password = 'P@ssw0rd'
$securePassword = ConvertTo-SecureString -String $password -AsPlainText -Force
$credential = New-Object pscredential 'admin', $securePassword
$auth = 'UserPassword'
$artifactUrl = Get-BcArtifactUrl -type 'Sandbox' -version '' -country 'us' -select 'Latest'
New-BcContainer -accept_eula
-containerName $containerName
-credential $credential
-auth $auth
-artifactUrl $artifactUrl
-imageName 'mybcimage'
-updateHosts
The cmdlet has some mandatory parameters, such as containerName and accept_eula. The New-BcContainer cmdlet comes with the useful option of -updateHosts, which will automatically create an entry in your local host file to register the container name with the IP address of the container.
If you're uncertain which image version you need to use on your Windows machine, you can use the -useBestContainerOS option. This option will detect if it would be better for you to use an image based on Windows Server Core 2016 (ltsc2016) or Windows Server Core 2019 (ltsc2019).
By default, the option will create a container with Windows Authentication, and it will prompt for your credentials. If you use your local Windows credentials, you'll enable single sign-on (SSO). To use a username and password, you can use the -auth NavUserPassword option.
New-BCContainer -accept_eula
-containerName $containerName
-credential $credential
-auth $auth
-artifactUrl $artifactUrl
-imageName 'mybcimage'
-updateHosts
-useBestContainerOS
This option will display useful information in the output window that you can provide to Microsoft when you ask questions or report bugs. Make sure that you always include the full output.
Remove a Business Central container
Removing a container is simple with the Remove-BcContainer command.
Remove-BCContainer -containerName MyDevContainer
Compile and publish an extension in a container
A container is an excellent way to compile an extension in a DevOps scenario. BcContainerHelper provides cmdlets to help you compile AL extensions. Previously, you learned how to set up a bind mount. You can use the same approach to get access to the AL files that are stored on a local drive.
New-BCContainer -accept_eula
-containerName $containerName
-credential $credential
-auth $auth
-artifactUrl $artifactUrl
-imageName 'mybcimage'
-updateHosts
-useBestContainerOS
-additionalParameters @("-v c:\AL\Demo\:C:\src")
Use the Compile-AppInBcContainer to compile the extension. It will generate an .app file as the end result.
Compile-AppInBCContainer -containerName MyDevContainer
-appProjectFolder c:\AL\Demo\
When you have a compiled app, you can publish the app to a container. The best way to publish the app is to remove the container that you use to compile and then start a new one. A bind mount is not needed in this instance because the publishing used the management APIs of Business Central to deploy the extension in the container. If your app is not signed, you need to specify the -skipVerification option.
Remove-BCContainer MyDevContainer
New-BCContainer -accept_eula
-containerName $containerName
-credential $credential
-auth $auth
-artifactUrl $artifactUrl
-imageName 'mybcimage'
-updateHosts
-useBestContainerOS
Publish-BcContainerApp -containerName MyTestContainer
-appFile "c:\AL\Demo\Cronus_Demo_1.0.0.0.app"
-skipVerification
-sync
-install