Category Archives: Runtime

How to install Business Central (developer) preview version

In the last weeks, I got some questions about installing the developer’s preview version (the Insider build) of the Business Central. This version is available through Artifacts for docker similarly to standard versions; however, they are available only for Microsoft’ partners.

If you are a partner, you can find your access code directly in the Microsoft Partner Center (Collaborate -> Overview -> Packages -> Working with Business Central Insider Builds). On this page, you can download the .txt file that contains sasToken (token you need to download any of insiders builds).

Creating the container is similar to creating the standard container; the only difference is the “sasToken” parameter in the Get-BCArtifactUrl command. See the whole command below.


 $sasToken = "YOUR-OWN-TOKEN-FROM-PARTNER-CENTER"
 Measure-Command {
   $artifactUrl = Get-BCArtifactUrl -country base -select nextmajor -sasToken $sasToken
   $credential = New-Object pscredential 'UserName', (ConvertTo-SecureString -String 'Password' -AsPlainText -Force)
   New-BcContainer          
     -accept_eula
     -containerName Your-Container-Name          
     -artifactUrl $artifactUrl
     -Credential $credential          
     -auth UserPassword
     -updateHosts          
     -imagename Your-Own-Image-Name
     -includeTestToolkit `
     -licenseFile 'C:\PartnersLicense.flf'
 }

Visual Studio Code AL Language extension from Insider’s build

With the new major version, there are always many changes to development. To use these changes and try to create new objects, new structures, or check changes to standard procedures, you have to use the new version of the AL Language extension for Visual Studio Code.

The new version is not available directly through Visual Studio Code until the full version of the Business Central is officially published. However, the extension is available directly on the image you downloaded when the container was created (it could be a little different path in your case):

C:\bcartifacts.cache\sandbox\18.0.22317.0\platform\ModernDev\program files\Microsoft Dynamics NAV\180\AL Development Environment

This .VSIX package can be installed manually in Visual Studio Code (Extensions -> … -> Install from VSIX…).

A quick look into the upcoming major version in April 2021 (Business Central 2021 release wave 1) from the developer’s point of view

It is only four months since the last major version of the Business Central (2020 wave 2) has been released, and we can already look forward to another version that will be released in April.

Microsoft has already provided the list of planned and confirmed functionality (available here). Let’s look at some of the planned features that will be usable (or, at least available) for programmers.

Most useful changes for developers

Extensible reports

One of the most annoying things for customising in the AL language are definitely reports. Till now, to add own field to the existing report from the base app or another extension, there was no other way but to copy the report and do the change in this copy.

With the upcoming version, developers will be able to create a report extension objects. Using this extension object type, we will be able (at least) to add new fields to existing datasets and request pages.

In my opinion, this is one of the most critical changes and as so I will look at it in another article once it is available in public preview.

Returning of complex types from AL procedures

One of the greatest news is that with the new update almost every complex type (record, page, query, list, …) can be returned from a procedure. Let’s see an example:


 procedure GetSellToCustomer(): Record Customer
 var
   Customer: Record Customer;
 begin
   Rec.TestField("Sell-to Customer No.");
   if Customer.Get("Sell-to Customer No.") then
     exit(Customer);
 end;

As this is a big change and as it is something known and often used in almost any other language, I will look at it in details in the next weeks.

Ability to add own keys/indexes to base table/tableextension

To increase custom processes’ performance, Microsoft added support of adding own keys to original tables and tables from any extension.

Entitlement and PermissionSet objects

There will be new object types for better administration and security of user’s roles: Entitlements, PermissionSets and PermissionSetExtension.

PermissionSets (and PermissionSetExtension) are already familiar to anybody. However, in current versions of the Business Central, they are stored and managed directly in the Modern Client.

Entitlements is a new object type that will allow specifying, which objects are available for specific users based on their assigned license (Full, Team Member, …) or Azure Active Directory role.

Easier working with 1-D barcodes in report layouts

There are new fonts available to use in report layouts. These fonts allow generating one-dimensional barcodes. For now (2021/02) licensed fonts are as follow

Some of other improvements

  • Availability to specify report layout both using AL or directly in the Modern Client (so as developers, we can use the same report for more layouts dynamically)
  • Performance improvements to Role Centers. The content of the Role Center is loaded in a similar way to FactBoxes. That means that Role Centers are loaded part by part from top-level (from menus), and only the visible parts are loaded. For developers, that is the improvement that helps with the performance a lot as users will be able to use menu actions without waiting for bricks and other stats shown on the main page.
  • Interfaces can be obsoleted as any other objects (In my opinion, this is a fix, not an improvement…)
  • Lookups triggers will return record link of selected record instead of its name.
  • Many improvements to the extensibility of reservation management. I will cover this topic as a separate article in the upcoming weeks.

Connect to Business Central Container using VS Code

In the last article, we created our first Business Central Container for development. But how to use it within the VS Code environment?

There is nothing special about the configuration. Just use values from message gained once the container was created.

Use a value of “Dev. Server” as a value of “server” property in launch.json and in the same way use value of “Dev. ServerInstance” as a value of “serverInstance”.

 {
     "version": "0.2.0",
     "configurations": [
         {
             "name": "My Container (Kepty-Demo)",
             "request": "launch",
             "type": "al",
             "environmentType": "OnPrem",
             "server": "http://Kepty-Demo",
             "serverInstance": "BC",
             "authentication": "UserPassword",
         }
     ]
 }

Access Business Central database running in a container from the Microsoft SQL Server Management Studio

Whether your instances are running directly on the server or in containers, it is sometimes necessary to access a database directly from the SQL Server Management Studio. When you have everything installed on your device, it is usually straightforward – you have the database on SQL Express Server installed together with the Business Central, or the database is deployed on your existing SQL Server.

However, when you use BC Containers (with the standard setup – everything running inside the container, even database), it could be unclear how to access the database.

The first thing to know is that the database can be accessed like any other database, without any special setup.

So, how we can access the database? The most important things to know are that the database is accessible only from the computer where the container is running, and that database server name is the same as the name of your container. The same is also your user name and password (as you used to create a BC container/instance).

Access database hosted in BC container from Microsoft SQL Server Management Studio

Start SQL Server Management Studio on the computer where the container is running, set the server name to the same value as your container name and use your own credentials that you set for the container and that’s it!

Starting with Container-Based Development using Dockers

Microsoft Dynamics 365 Business Central offers images for container-based development. Creating a new development environment using this container-based image (with Docker) is especially quick and easy.

Install Docker

The first thing that must be done is installing Docker. Docker. The current stable version for Windows could be found directly on docker.com (Windows 10).

Once the Docker is installed (the installation will probably require a restart of the computer), set the docker to use Windows containers (in Taskbar, right-click on the Docker icon and choose “Switch to Windows Containers”. If you already have any Linux containers, they won’t be deleted, but you won’t be able to manage them while you are working with Windows containers.

Create Container

The easiest way how to install container is to use PowerShell module created by Freddy Kristiansen that is available on powershellgallery.com.

This module contains many functions that are prepared directly for using for the Business Central and helps a lot with any task from creating to managing containers.

To start with, open a PowerShell (run as an administrator) and install this module using Install-Module command. Then import the module using Import-Module.

Install-Module -Name navcontainerhelper
Import-Module navcontainerhelper

Once we have the module installed & imported, we can create a new container using New-NavContainer function (see details of how to use this function in Freddy’s article where he introduced all new functions in the NavContainerHelper module).

PS C:\WINDOWS\system32> Measure-Command {
    $artifactUrl = Get-BCArtifactUrl -version 16.4 -select Latest -country w1
    $credential = New-Object pscredential 'Kepty', (ConvertTo-SecureString -String 'TKA@Password' -AsPlainText -Force)
    New-NavContainer `
        -accept_eula `
        -containerName Kepty-Demo `
        -artifactUrl $artifactUrl `
        -Credential $credential `
        -auth UserPassword `
        -updateHosts `
        -imagename 16-4-w1
}

Using this script, we create a new container with the name “Kepty-Demo”, credentials “Kepty” / “TKA@Password” with an image of Business Central 16.4 W1.

Once the script finishes (it may take time, sometimes up to 45 minutes till the image is downloaded and container created).

NavContainerHelper is version 0.7.0.26
NavContainerHelper is running as administrator
Host is Microsoft Windows 10 Education - 1909
Docker Client Version is 19.03.13
Docker Server Version is 19.03.13
ArtifactUrl and ImageName specified
Fetching all docker images
Downloading application artifact /sandbox/16.4.14693.19714/w1
Downloading C:\Users\Kepty\AppData\Local\Temp\acc7c156-c5c5-46ac-b407-d987704aa4bb.zip
Unpacking application artifact to tmp folder using Expand-Archive
Image 16-4-W1:sandbox-16.4.14693.19714-w1 doesn't exist
Building image 16-4-W1:sandbox-16.4.14693.19714-w1 based on https://bcartifacts.azureedge.net/sandbox/16.4.14693.19714/w1
Pulling latest image mcr.microsoft.com/dynamicsnav:10.0.18363.1198-generic
10.0.18363.1198-generic: Pulling from dynamicsnav

9038b92872bc: Pulling fs layer
...
d2c27142114e: Pulling fs layer
4e34d77e7c33: Waiting
...
d2c27142114e: Waiting
ebf009e1d015: Verifying Checksum
ebf009e1d015: Download complete
...
708d38bb8af6: Verifying Checksum
708d38bb8af6: Download complete
9038b92872bc: Pull complete
...
d2c27142114e: Pull complete
Digest: sha256:6c7974113fc53b0eda6db752409b9bebfd1c7dce8327bcf6fe0f917a5104d50f
Status: Downloaded newer image for mcr.microsoft.com/dynamicsnav:10.0.18363.1198-generic
mcr.microsoft.com/dynamicsnav:10.0.18363.1198-generic
Generic Tag: 0.1.0.24
Container OS Version: 10.0.18363.1198 (1909)
Host OS Version: 10.0.18363.1198 (1909)
Downloading platform artifact /sandbox/16.4.14693.19714/platform
Downloading C:\Users\Kepty\AppData\Local\Temp\c57ebf7f-be77-488b-a31c-5647f9933ee8.zip
Unpacking platform artifact to tmp folder using Expand-Archive
Downloading Prerequisite Components
Downloading c:\bcartifacts.cache\sandbox\16.4.14693.19714\platform\Prerequisite Components\Open XML SDK 2.5 for Microsoft Office\OpenXMLSDKv25.msi
Downloading c:\bcartifacts.cache\sandbox\16.4.14693.19714\platform\Prerequisite Components\IIS URL Rewrite Module\rewrite_2.0_rtw_x64.msi
Downloading c:\bcartifacts.cache\sandbox\16.4.14693.19714\platform\Prerequisite Components\DotNetCore\DotNetCore.1.0.4_1.1.1-WindowsHosting.exe
Copying Platform Artifacts
Copying Database
Copying Licensefile
Copying Extensions
c:\bcartifacts.cache\tmp637428760545412940
Building image took 492 seconds
Using image 16-4-w1:sandbox-16.4.14693.19714-w1
Creating Container Kepty-Demo
Version: 16.4.14693.19714-W1
Style: sandbox
Platform: 16.0.14648.19648
Generic Tag: 0.1.0.24
Container OS Version: 10.0.18363.1198 (1909)
Host OS Version: 10.0.18363.1198 (1909)
Using locale en-US
Using process isolation
Disabling the standard eventlog dump to container log every 2 seconds (use -dumpEventLog to enable)
Files in C:\ProgramData\NavContainerHelper\Extensions\Kepty-Demo\my:
- AdditionalOutput.ps1
- MainLoop.ps1
- SetupVariables.ps1
- updatehosts.ps1
Creating container Kepty-Demo from image 16-4-w1:sandbox-16.4.14693.19714-w1
65926627a6741139fbf7346e415980f4bf79b5ab03350d0eed6366b78b5bfcc5
Waiting for container Kepty-Demo to be ready
Initializing...
Setting host.docker.internal to 10.0.0.5 in container hosts file (copy from host hosts file)
Setting gateway.docker.internal to 10.0.0.5 in container hosts file (copy from host hosts file)
Setting kubernetes.docker.internal to 127.0.0.1 in container hosts file (copy from host hosts file)
Setting host.containerhelper.internal to 172.29.144.1 in container hosts file
Starting Container
Hostname is Kepty-Demo
PublicDnsName is Kepty-Demo
WARNING: DNS resolution not working from within the container.
Using NavUserPassword Authentication
Starting Local SQL Server
Starting Internet Information Server
Creating Self Signed Certificate
Self Signed Certificate Thumbprint 7EFE7BCF953F86A54D82DD84DF6790C5093F39AD
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
Setting SA Password and enabling SA
Creating Kepty as SQL User and add to sysadmin
Creating SUPER user
WARNING: The password that you entered does not meet the minimum requirements. 
It should be at least 8 characters long and contain at least one uppercase 
letter, one lowercase letter, and one number.
Container IP Address: 172.29.144.157
Container Hostname  : Kepty-Demo
Container Dns Name  : Kepty-Demo
Web Client          : http://Kepty-Demo/BC/
Dev. Server         : http://Kepty-Demo
Dev. ServerInstance : BC
Setting Kepty-Demo to 172.29.144.157 in host hosts file

Files:
http://Kepty-Demo:8080/ALLanguage.vsix

Container Total Physical Memory is 15.9Gb
Container Free Physical Memory is 5.6Gb

Initialization took 145 seconds
Ready for connections!
Reading CustomSettings.config from Kepty-Demo
Creating Desktop Shortcuts for Kepty-Demo
Container Kepty-Demo successfully created


Days              : 0
Hours             : 0
Minutes           : 11
Seconds           : 2
Milliseconds      : 578
Ticks             : 6625789612
TotalDays         : 0,00766873797685185
TotalHours        : 0,184049711444444
TotalMinutes      : 11,0429826866667
TotalSeconds      : 662,5789612
TotalMilliseconds : 662578,9612

A that’s all! The container is created and is accessible through a link at the end of the report (for the example, the link to the web client is http://Kepty-Demo/BC)

If you want to find out more about the module “NavContainerHelper” see Freddy’s GitHub.