Prerequisites

Visual Studio Code
AL Language extension for Visual Studio Code
Docker for Windows
PC running Windows 10 version 1903 or newer
- At least 8GB of RAM
- At least 20GB free disk space

Installing the NAV Container Helper

First you need to install the NAV Container Helper. The NAV Container Helper is a PowerShell module that makes creating Business Central containers a lot easier. To install the module you need to open another PowerShell session and enter the following command

Install-Module -Name navcontainerhelper

If you need to update your installation you need to run the following command

Update-Module -Name navcontainerhelper -Force

Generating the artifact URL for your container

After installing the navcontainerhelper you first need to generate the artifact URL. To get the latest version of 16.2 in english you need to run the following command

$artifactUrl = Get-BCArtifactUrl -version "16.2" -country "us" -select "Latest"

If you need another country customization you need to change the -country attribute to for example de to get the German version.

Creating a new container

After generating the artifact URL you can create a new container with the following command.

New-BcContainer `
    -accept_eula `
    -containerName "BC" `
    -credential $(Get-Credential) `
    -artifactUrl $artifactUrl `
    -isolation process `
    -useBestContainerOs `
    -updateHosts

-accept_eula: Means that you are accepting the EULA that you can look into here: https://go.microsoft.com/fwlink/?linkid=861843 (Warning: downloads a PDF file)
-containerName: The name of the container that you are creating
-credential: The username/password for the new container
-artifactUrl: The previously generated artifact URL
-isolation process: The isolation model. Process is faster, HyperV is safer
-useBestContainerOs: Uses the best available docker image for your system
-updateHosts: Update the hosts file on your PC to allow name resolution

Once you've entered the command the following window will pop up and ask you for your Windows user name and password:
powershell_RV9s4xaxq6
Enter the credentials and click on "OK".

After a few minutes you should get the the following (or similar) output:

NavContainerHelper is version 0.6.4.14
Host is Microsoft Windows 10 Enterprise - 1903
Docker Client Version is 19.03.5
Docker Server Version is 19.03.5
Using image mcr.microsoft.com/businesscentral/sandbox:ltsc2019
Creating Container BCDev
Version: 15.1.37881.38420-w1
Style: sandbox
Platform: 15.0.37865.38374
Generic Tag: 0.0.9.96
Container OS Version: 10.0.17763.805 (ltsc2019)
Host OS Version: 10.0.18362.476 (1903)
The container operating system does not match the host operating system, forcing hyperv isolation.
Using locale en-US
Using hyperv isolation
Disabling the standard eventlog dump to container log every 2 seconds (use -dumpEventLog to enable)
Files in C:\ProgramData\NavContainerHelper\Extensions\BCDev\my:
- AdditionalOutput.ps1
- MainLoop.ps1
- updatehosts.ps1
Creating container BCDev from image mcr.microsoft.com/businesscentral/sandbox:ltsc2019
244de1fc69336cff341e9b0db363a71e8e50518a90914c2abe43d374ed18e142
Waiting for container BCDev to be ready
Initializing...
Starting Container
Hostname is BCDev
PublicDnsName is BCDev
Using Windows Authentication
Starting Local SQL Server
Starting Internet Information Server
Modifying Service Tier Config File with Instance Specific Settings
Starting Service Tier
Registering event sources
Creating DotNetCore Web Server Instance
Enabling Financials User Experience
Creating http download site
Creating Windows user niehus
Setting SA Password and enabling SA
Creating SUPER user
Container IP Address: 172.23.41.59
Container Hostname  : BCDev
Container Dns Name  : BCDev
Web Client          : http://BCDev/BC/
Dev. Server         : http://BCDev
Dev. ServerInstance : BC

Files:
http://BCDev:8080/al-4.0.194000.vsix

Initialization took 202 seconds
Ready for connections!
Reading CustomSettings.config from BCDev
Creating Desktop Shortcuts for BCDev
Container BCDev successfully created

The last few lines are the important part:

Container IP Address: 172.23.41.59
Container Hostname  : BCDev
Container Dns Name  : BCDev
Web Client          : http://BCDev/BC/
Dev. Server         : http://BCDev
Dev. ServerInstance : BC

Files:
http://BCDev:8080/al-4.0.194000.vsix

Make sure that you save this information somewhere as you will need it later on

If you now open the URL displayed after Web Client: you will see the web client of the container you just created. In my example I have to open the URL http://bcdev/BC/

chrome_75Ekf9f90C

Creating a new project in Visual Studio Code

Now it is time to get to the programming part. Open Visual Studio Code and open the command palette with CTRL+SHIFT+P or F1. In the command palette enter AL: Go!

MyDaeDk0NA

You can also use the keybind ALT+A ALT+L

Now you should see the following prompt:

65uT2APwwC

In this prompt you need to enter a path for the project you want to create. In my example I will be using C:\dev\projects\GettingStartedAL.

After you have chosen a local path you need to specify the target platform.

AlGPe1bXkc

Here you need to select "5.0 Business Central 2020 release wave 1"

In the next menu you need to choose "Your own server"

pBDR2uDdvo

Cancel the next question with ESCAPE

Connecting to your Business Central container

After the creation of the project the following launch.json file should open itself. If it does not open itself you can find it in the .vscode folder

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "al",
            "request": "launch",
            "name": "Your own server",
            "server": "http://localhost",
            "serverInstance": "BC150",
            "authentication": "UserPassword",
            "startupObjectId": 22,
            "startupObjectType": "Page",
            "breakOnError": true,
            "launchBrowser": true,
            "enableLongRunningSqlStatements": true,
            "enableSqlInformationDebugger": true
        }
    ]
}

In the file you need to change the values of server, serverInstance and authentication.

The value of server has to be the value of Dev. Server: that you've got in the creation process of the container. In my example it would be http://BCDev

For serverInstance you need to use the value of Dev. ServerInstance:. It should be BC

authentication needs to be changed to Windows

My finished example:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "al",
            "request": "launch",
            "name": "Your own server",
            "server": "http://BCDev",
            "serverInstance": "BC",
            "authentication": "Windows",
            "startupObjectId": 22,
            "startupObjectType": "Page",
            "breakOnError": true,
            "launchBrowser": true,
            "enableLongRunningSqlStatements": true,
            "enableSqlInformationDebugger": true
        }
    ]
}

Downloading the application symbols

To be able to use the already present symbols you need to download them with the AL: Download Symbols command that you will also find in the command palette of Visual Studio Code.

After the download has finished you will find the files in a new folder named .alpackages. Inside you should find three files.

Code_eRpqcw7e56

You can now try the already provided source code if you open the HelloWorld.al file and press F5. Once you open the customer list you should see a message that says App published: Hello world

chrome_LElFEDZ2kQ

Version History

Date
2019-11-18	Initial release
2020-06-06	Update to new navcontainerhelper

Getting Started With Developing Extensions For Microsoft Dynamics 365 Business Central

Sven Niehus