Although interfaces were introduced in Business Central 2020 release wave 1, it can still be a fairly new concept for Business Central (BC) developers who have not programmed in other language such as C#, TypeScript, or Java. Interfaces are not new in the software engineering world, and it’s never too late to catch up with the rest of the industry on the good practices of writing and maintaining source code, and in particular, programming against an interface, not an implementation. Let’s have a look at an evolution of a simplistic piece of software to demonstrate the benefits of using interfaces.

Disclaimer: the names of companies and providers used in this blog post except Microsoft are fictitious. Any similarity to the names is entirely coincidental.

Setting the stage

To find a theme for our simple solution written in Application Language (AL), we’ll refer to the trendy tool the companies are implementing these days - AI. Let’s imagine, our business leaders asked us to create a Business Central application for helping with some users' questions, and we’re the developers from the past without interfaces in AL. We (at least I) have no idea how to build proper prompts to real AI services, and although it won’t often happen in real life, our manager agreed with my suggestion that calling real services of AI providers is out of scope of our solution. We decided to hardcode the responses from the services. Although everyone feels like this implementation may not bring any value to the business and could be a complete waste of time, the product should be enough to see the power of adding interfaces to your software development tool set. That’s the real purpose of the project - learning something new!

We’ll start with a simple AL application containing a page, an element to enter a question from a user, and an action button to get a response from the fake AI services. The page code below will be enough to get first development results.

page 50100 "ASH Fake AI Service"
{
    ApplicationArea = Basic, Suite;
    Caption = 'Fake AI Service';
    DeleteAllowed = false;
    InsertAllowed = false;
    PageType = Card;
    UsageCategory = Tasks;

    layout
    {
        area(content)
        {
            field(Question; Question)
            {
                ApplicationArea = All;
                Caption = 'Question';
                MultiLine = true;
                ToolTip = 'The question to ask the AI service.';
            }
        }
    }

    actions
    {
        area(Processing)
        {
            action("Get AI Answer")
            {
                Caption = 'Get AI Answer';
                ApplicationArea = All;
                Image = Answers;
                ToolTip = 'Get the answer from the AI service.';
                Promoted = true;
                PromotedCategory = Process;
                PromotedIsBig = true;

                trigger OnAction()
                var
                    FakeAiServiceMgt: Codeunit "ASH Fake AI Service Mgt.";
                begin
                    Message(FakeAiServiceMgt.GetAnswer(Question));
                end;
            }
        }
    }

    var
        Question: Text;

}

And the codeunit provides an answer already, which is a good start.

codeunit 50100 "ASH Fake AI Service Mgt."
{
    procedure GetAnswer(Question: Text): Text
    begin
        if Question = '' then
            Error('Please enter your question.');

        exit('answer');
    end;
}

Our current solution is action should look like in the figure below.

Let’s call our first two fake AI service providers Bingle and Alfasoft. The system logic to call their services is a bit different and can change later, so we’ll put them in dedicated codeunits and will call them from our main Fake AI Service Mgt. codeunit. To specify the provider, we’ll create an extensible Enum object and add a new field with it to the page just above the Question element.

enum 50100 "ASH Fake AI Service Providers"
{
    Extensible = true;

    value(50100; Bingle)
    {
    }
    value(50101; Alfasoft)
    {
    }
}

page 50100 "ASH Fake AI Service"
{
    ApplicationArea = Basic, Suite;
    Caption = 'Fake AI Service';
    DeleteAllowed = false;
    InsertAllowed = false;
    PageType = Card;
    UsageCategory = Tasks;

    layout
    {
        area(content)
        {
            field(Provider; Provider)
            {
                ApplicationArea = All;
                Caption = 'Provider';
                ToolTip = 'The AI service provider to use.';
            }

            field(Question; Question)
            {
                ApplicationArea = All;
                Caption = 'Question';
                MultiLine = true;
                ToolTip = 'The question to ask the AI service.';
            }
        }
    }

    actions
    {
        area(Processing)
        {
            action("Get AI Answer")
            {
                Caption = 'Get AI Answer';
                ApplicationArea = All;
                Image = Answers;
                ToolTip = 'Get the answer from the AI service.';
                Promoted = true;
                PromotedCategory = Process;
                PromotedIsBig = true;

                trigger OnAction()
                var
                    FakeAiServiceMgt: Codeunit "ASH Fake AI Service Mgt.";
                begin
                    Message(FakeAiServiceMgt.GetAnswer(Provider, Question));
                end;
            }
        }
    }

    var
        Question: Text;
        Provider: Enum "ASH Fake AI Service Providers";
}

The main codeunit GetAnswer procedure now needs the Provider parameter so that depending on the enum value that we select on the page, we are able to get answers from the service providers.

codeunit 50100 "ASH Fake AI Service Mgt."
{
    procedure GetAnswer(Provider: Enum "ASH Fake AI Service Providers"; Question: Text) Answer: Text
    var
        AlfasoftAiServiceMgt: Codeunit "ASH Alfasoft AI Service Mgt.";
        BingleAiServiceMgt: Codeunit "ASH Bingle AI Service Mgt.";
    begin
        if Question = '' then
            Error('Please enter your question.');

        case Provider of
            Provider::Bingle:
                Answer := BingleAiServiceMgt.GetAnswer(Question);
            Provider::Alfasoft:
                Answer := AlfasoftAiServiceMgt.GetAnswer(Question);
        end;
    end;
}

The dedicated to service provider logic codeunits are listed below.

codeunit 50101 "ASH Alfasoft AI Service Mgt."
{
    procedure GetAnswer(Question: Text) Answer: Text
    begin
        Answer := 'Alfasoft says: hmm, interesting question';
    end;
}


codeunit 50102 "ASH Bingle AI Service Mgt."
{
    procedure GetAnswer(Question: Text) Answer: Text
    begin
        Answer := 'Bingle says: you know it better';
    end;
}

Notice how we must update the main Fake AI Service Mgt. codeunit every time we need to add a service provider. All the services implementations are explicitly referenced in the area where we defined our variables. This is called a tightly coupled code - changing in one codeunit often must be reflected in the other codeunit as well.

Now imagine that our service providers list keeps growing as well as related features and the main codeunit at some point becomes hard to read. The cases when one service was broken after making changes for another have started to pop up and eventually no one wants to touch that code anymore. The time it takes to ensure that nothing is broken starts to delay delivery of new application features.

To add fuel to the flame, a couple of our customers want to add their custom AI breakthrough solutions to the list as well but it sounds like we have no other choice apart from letting them customize our application for them and include their codeunits into our codebase. We don’t believe it will be a good approach for maintaining and developing our solution further. Time to seriously think of a new way of organizing our code. Luckily for us, Microsoft introduced interfaces to Business Central Application Language, and we’ve decided to explore this new platform feature.

Adding an interface

From the Microsoft Learn article about interfaces in AL we understood that an interface is a syntactical contract which needs to be implemented. Let’s have a look at our service providers code that we wrote for getting the answers. If we look at the service provider management codeunits as implementations with specific to provider details, what is the common function that a service provider codeunit has? That’s right, the GetAnswer function. Our interface for fake AI service providers will look as follows.

interface "ASH AI Service Provider"
{
    procedure GetAnswer(Question: Text) Answer: Text
}

The important part here is that the method signature - the procedure name, the parameters, and the returned value - must be exactly the same as we would expect it in our implementations. The visibility of a procedure will always be public there. We need interfaces only to define how our system will be communicating with an implementation. We won’t be able to see private methods anyway.

Our providers services codeunits have procedures with the method signatures from the interface and therefore we can say that they implement it. We can explicitly say so in the program code by adding the implements keyword.

codeunit 50101 "ASH Alfasoft AI Service Mgt." implements "ASH AI Service Provider"
{
    procedure GetAnswer(Question: Text) Answer: Text
    begin
        Answer := 'Alfasoft says: hmm, interesting question';
    end;
}

codeunit 50102 "ASH Bingle AI Service Mgt." implements "ASH AI Service Provider"
{
    procedure GetAnswer(Question: Text) Answer: Text
    begin
        Answer := 'Bingle says: you know it better';
    end;
}

After rewriting our main codeunit, the code looks as below.

codeunit 50100 "ASH Fake AI Service Mgt."
{
    procedure GetAnswer(Provider: Enum "ASH Fake AI Service Providers"; Question: Text) Answer: Text
    var
        AlfasoftAiServiceMgt: Codeunit "ASH Alfasoft AI Service Mgt.";
        BingleAiServiceMgt: Codeunit "ASH Bingle AI Service Mgt.";
        AIServiceProvider: Interface "ASH AI Service Provider";
    begin
        if Question = '' then
            Error('Please enter your question.');

        case Provider of
            Provider::Bingle:
                AIServiceProvider := BingleAiServiceMgt;
            Provider::Alfasoft:
                AIServiceProvider := AlfasoftAiServiceMgt;
        end;

        Answer := AIServiceProvider.GetAnswer(Question);
    end;
}

We have defined a new variable of type Interface and assigned an implementation codeunit to it depending on the Provider parameter. Once we have an implementation assigned, we can call the GetAnswer method. Notice that we do it using the interface variable which at the moment of calling the method has a reference to the relevant instance of the implementation codeunit. Can we use this for extending our solution for the customers? Exposing an event sounds like a good option, so let’s do it!

codeunit 50100 "ASH Fake AI Service Mgt."
{
    procedure GetAnswer(Provider: Enum "ASH Fake AI Service Providers"; Question: Text) Answer: Text
    var
        AlfasoftAiServiceMgt: Codeunit "ASH Alfasoft AI Service Mgt.";
        BingleAiServiceMgt: Codeunit "ASH Bingle AI Service Mgt.";
        AIServiceProvider: Interface "ASH AI Service Provider";
    begin
        if Question = '' then
            Error('Please enter your question.');

        case Provider of
            Provider::Bingle:
                AIServiceProvider := BingleAiServiceMgt;
            Provider::Alfasoft:
                AIServiceProvider := AlfasoftAiServiceMgt;
            else
                OnBeforeGetAnswer(Provider, AIServiceProvider);
        end;
        
        Answer := AIServiceProvider.GetAnswer(Question);
    end;

    [IntegrationEvent(false, false)]
    local procedure OnBeforeGetAnswer(Provider: Enum "ASH Fake AI Service Providers"; var AIServiceProvider: Interface "ASH AI Service Provider")
    begin
    end;

}

All our customers have to do now is to extend the enum 50100 "ASH Fake AI Service Providers" and subscribe to the new handy event where they can assign their implementations to the AIServiceProvider variable.

Creating an extension to the main app

To demonstrate that, let’s create a separate app for the new fake AI service provider from the company called Apricot, and name the app Custom AI Provider. We want it to be automatically integrated into our Fake AI Service page once the app is installed.

After we have set up the dependency and the workspace for the two apps, we can define the new enum extension as follows.

enumextension 50150 "ASH Cust. AI Service Providers" extends "ASH Fake AI Service Providers"
{
    value(50150; Apricot)
    {
    }
}

The Apricot service provider codeunit needs its own interface implementation and we will complete the integration of the custom app via the event subscription.

codeunit 50150 "ASH Apricot AI Service Mgt." implements "ASH AI Service Provider"
{
    procedure GetAnswer(Question: Text) Answer: Text
    begin
        Answer := 'Apricot says: follow your heart';
    end;
}

codeunit 50151 "ASH Cust. Serv. Provider Mgt."
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::"ASH Fake AI Service Mgt.", OnBeforeGetAnswer, '', false, false)]
    local procedure OnBeforeGetAnswer(Provider: Enum "ASH Fake AI Service Providers"; var AIServiceProvider: Interface "ASH AI Service Provider");
    var
        ApricotAIServiceMgt: Codeunit "ASH Apricot AI Service Mgt.";
    begin
        if Provider = Provider::Apricot then
            AIServiceProvider := ApricotAIServiceMgt;
    end;
}

Once the second app is also published, the custom implementation can now be tested along with the built-in ones, and we get the expected response.

Phew, a customized code base is no longer required and the future looks brighter. Our Customers are still looking forward to doing business together with us!

What we have done now is applying the Dependency Inversion principle, one of the SOLID principles of software design. Instead of making our base product code dependent and tightly coupled with the customers code, we let customers’ solutions to depend on ours and inverted the dependency. This approach allows us to develop our features without really having to know about the custom logic for service providers. All we needed to do is to let the custom solutions know what our product expects them to do - provide a GetAnswers method implementation - and that we did with the interface definition. All customers needed to do is to have implemented the interface. Everyone can do what they want now without interference as long as the system communication contract is fulfilled.

Mapping interfaces with implementations

Although we’ve sold a couple of program code management problems, our main codeunit "ASH Fake AI Service Mgt." still needs updating when a service provider is added to our base product. There is a neater way to map interfaces with implementations that will let us completely free the codeunit from references to specific AI provider services codeunits and related to them logic leaving only reusable program code. We will look into it next.

The fact is that Enums in AL also can implement interfaces. Well, not exactly but with Enums we can further reference an implementation against each value. There is also the DefaultImplementation Enum property that can be used for all values without a specific Implementation in case we need it. Let’s see how we can use the enum 50100 "ASH Fake AI Service Providers" more effectively.

enum 50100 "ASH Fake AI Service Providers" implements "ASH AI Service Provider"
{
    Extensible = true;

    value(50100; Bingle)
    {
        Implementation = "ASH AI Service Provider" = "ASH Bingle AI Service Mgt.";
    }
    value(50101; Alfasoft)
    {
        Implementation = "ASH AI Service Provider" = "ASH Alfasoft AI Service Mgt.";
    }
}

With this approach, we can further clean up our main codeunit 50100 "ASH Fake AI Service Mgt." and remove all the implementation variables which we mapped in the Enum object.

codeunit 50100 "ASH Fake AI Service Mgt."
{
    procedure GetAnswer(Provider: Enum "ASH Fake AI Service Providers"; Question: Text) Answer: Text
    var
        AIServiceProvider: Interface "ASH AI Service Provider";
    begin
        if Question = '' then
            Error('Please enter your question.');

        case Provider of
            Provider::Bingle, Provider::Alfasoft:
                AIServiceProvider := Provider;
            else
                OnBeforeGetAnswer(Provider, AIServiceProvider);
        end;

        Answer := AIServiceProvider.GetAnswer(Question);
    end;

    [IntegrationEvent(false, false)]
    local procedure OnBeforeGetAnswer(Provider: Enum "ASH Fake AI Service Providers"; var AIServiceProvider: Interface "ASH AI Service Provider")
    begin
    end;
}

The dependent app Custom AI Provider has broken with the change - it also requires the enum extension update.

enumextension 50150 "ASH Cust. AI Service Providers" extends "ASH Fake AI Service Providers"
{
    value(50150; Apricot)
    {
        Implementation = "ASH AI Service Provider" = "ASH Apricot AI Service Mgt.";
    }
}

With this change, we no longer need the event and the subscriber code, all implementations are now mapped via the "ASH Fake AI Service Providers" enum and we can remove the redundant program code - delete entire codeunit 50151 "ASH Cust. Serv. Provider Mgt." and remove the OnBeforeGetAnswer event and related code from the codeunit 50100 "ASH Fake AI Service Mgt.". The main codeunit looks as lean as never before!

codeunit 50100 "ASH Fake AI Service Mgt."
{
    procedure GetAnswer(Provider: Enum "ASH Fake AI Service Providers"; Question: Text) Answer: Text
    var
        AIServiceProvider: Interface "ASH AI Service Provider";
    begin
        if Question = '' then
            Error('Please enter your question.');

        AIServiceProvider := Provider;
        Answer := AIServiceProvider.GetAnswer(Question);
    end;
}

There is actually no essential need for the main codeunit 50100 "ASH Fake AI Service Mgt." now. We can assign the enum to the interface directly in the page action if you wish to go further.

At this point, we have rewritten both of the apps to use Enum as the implementation mapper. The main codeunit no longer needs to know about any implementation details of the service. All it is responsible from now on is only processing whatever we receive from the service calls. If we need to add a new service provider, we would only need to add it to the Enum object and provide the interface implementation. The service page and the main codeunit is now reused across entire functionality when we need to add new service providers or update their system logic.

An example from Business Central apps

Every time I need to learn more about using AL types or find code samples, I tend to look into the standard Microsoft applications first. There is a great example for interfaces there - the Email Connector interface. It’s defined in the System Application and implemented in dedicated to a particular connector apps, for instance, SMTP or Microsoft 365. The below is a screenshot from my environment.

When we use the Set Up Email page, where do you think the list items come from?

You’re right, from the installed Email apps. By this time, you already know how those items automatically appear there, well done! If you look into the Business Central applications source code, I’m sure you’ll find something new that we haven’t covered today.

Summary

After making a couple of impractical decisions in the beginning of our AI services app design, I’m glad that we have finally achieved the primary objective of our project. I hope that by gradually making changes to our source code, we all now have a clear understanding that the main purpose of interfaces is being able to separate implementation details from the system parts that need not be concerned with them. Especially, if we have several ways of performing the same task and we want to create a program module or an app for each of them.

We were able to enable our valuable customers to work on their own software modules extending our base product. We still could improve our application without interference due to loose coupling of our apps achieved by applying the Dependency Inversion principle.

With the interfaces concept understood and applied, we have also reduced the number of code lines and made our code more readable and maintainable.

If there are still questions on the subject or I missed anything along the way, please let me know. Happy coding!

The source code for this blog post can be found at https://github.com/ashirokikh/ashirokikh.com

The most common way of creating validation data for Business Central is entering the data manually and then creating a (RapidStart) Configuration Package to export the created data and import it into another application environment. There are many articles and blog posts on how to use configuration packages and this blog post goes beyond that.

Configuration packages are a powerful tool and the data import is a fairly simple process (depending on the setup, of course). There is one challenge I faced, however, while automating a Business Central environment creation - tracking configuration package content. After the package is exported, it's hard to say whether it has all what you would expect it to have.

RapidStart file content

If we look at the standard source code for package export, the data is processed as an XML document (codeunit 8614 "Config. XML Exchange") and then compressed using the GZip format (codeunit 8619 "Config. Pckg. Compression Mgt."). That means we should be able to change the .rapidstart extension of the exported file to .gz and use an archiver software like 7-Zip to get the content. In my case, the contained file did not have an extension, therefore, once the file is decompressed, the result file extension needed to be specified as .xml to open it with a default viewer. That's it, a configuration package is essentially an archived XML file changes of which we can track as any text file.

Showcase scenario

Let's do a simple exercise that will show how the changes can be reviewed. Imagine that we develop a Business Central application extension. To streamline demonstration of our extension to the end users, we need specific to our application data setup. We decided to use configuration packages to consistently recreate the required data set by importing that data on top of the standard Microsoft Cronus company validation (demo) data. One of the tables that we need our custom data for is Customer. Our initial configuration package setup might look as in the picture below.

The exported and decompressed package file contains data from the listed in the configuration package tables including the setup such as information about included table filters and fields order as well as the data itself.

To exclude the standard Cronus data, our extension-specific Customer data is filtered by the No. field with the "TEST*" filter value, and we can see it under the ConfigPackageFilterList element of the XML package file.

We're happy with the data for now and we commit this file version along with the source code of the extension.

With our next useful feature, we added a custom Customer field (for this example, let's call it "ASH Important Field"), and would like to include that data into our package. A new Cronus company environment is created from scratch as usual to avoid data and configuration drift, our extension published to it and the configuration package is archived back to GZip format, imported and applied. Now we need to update the field values, add the field into the configuration package setup, and export the rapidstart file.

After going through the XML extraction process, we can clearly see the changes that a field has been added with the data from the database. We have confirmed nothing else is lost and only the expected data update is going to be committed to the source code repository.

By following this approach, every time we change the source code and the data needs an update, we track all data changes as well so that at all times the version of the application source code corresponds with the data version that we need our code to be demoed with.

Automating the process

The conversion from rapidstart to xml and back can be done with a PowerShell script. The below are the functions that can perform that.

function Convert-RapidStartFileToXmlFile {
    param(
        [Parameter(Mandatory=$true)]
        [string]$RapidStartFilePath
    )
    $filePath = Join-Path $PSScriptRoot ([System.IO.Path]::GetFileName($RapidStartFilePath)) -Resolve
    $XmlFilePath = [System.IO.Path]::ChangeExtension($filePath, "xml")
    Write-Host "Decompressing $filePath to $XmlFilePath"
    $xmlFileStream = New-Object IO.FileStream ($XmlFilePath, [System.IO.FileMode]::Create)
    $rapidstartFileStream = New-Object IO.FileStream ($filePath, [System.IO.FileMode]::Open, [IO.FileAccess]::Read)
    $gzipStream = New-Object IO.Compression.GzipStream ($rapidstartFileStream, [IO.Compression.CompressionMode]::Decompress)
    
    try {
        $gzipStream.CopyTo($xmlFileStream)
    }
    finally {
        $gzipStream.Close()
        $rapidstartFileStream.Close()
        $xmlFileStream.Close()
    }
}

function Convert-XmlFileToRapidStartFile {
    param(
        [Parameter(Mandatory=$true)]
        [string]$XmlFilePath
    )
    $filePath = Join-Path $PSScriptRoot ([System.IO.Path]::GetFileName($XmlFilePath)) -Resolve
    $RapidStartFilePath = [System.IO.Path]::ChangeExtension([System.IO.Path]::GetFullPath($filePath), "rapidstart")
    Write-Host "Compressing $filePath to $RapidStartFilePath"
    $xmlFileStream = New-Object IO.FileStream ($filePath, [IO.FileMode]::Open, [IO.FileAccess]::Read)
    $rapidstartFileStream = New-Object IO.FileStream ($RapidStartFilePath, [System.IO.FileMode]::Create)
    $gzipStream = New-Object IO.Compression.GzipStream ($rapidstartFileStream, [IO.Compression.CompressionMode]::Compress)
    
    try {
        $xmlFileStream.CopyTo($gzipStream)
    }
    finally {
        $xmlFileStream.Close()
        $gzipStream.Close()
        $rapidstartFileStream.Close()        
    }
}

The below are examples of how those functions can be called.

# Example of getting the contents of a RapidStart file:
Convert-RapidStartFileToXmlFile -RapidStartFilePath .\PackageCHECK-CONTENTS.rapidstart

# Example of creating a RapidStart file from an xml file:
Convert-XmlFileToRapidStartFile -XmlFilePath .\PackageCHECK-CONTENTS.xml

After the XML file that we track changes for is converted to a rapidstart file, it can be imported back into a Business Central environment. There is no need to track the original rapidstart file as we always can create it from the XML file.

The PowerShell scripts are helpful in particular if we use some kind of continuous integration (CI) pipeline which uses Docker containers to run automated tests. For example, if your source code repository is set up with AL-Go for GitHub, the ImportTestDataInBcContainer can be customized so that the Convert-XmlFileToRapidStartFile function is run to create the rapidstart file and then the UploadImportAndApply-ConfigPackageInBcContainer is called with the created file path as a parameter.

Summary

We have found out that a Business Central configuration package is an archived XML file and we can track its history of modifications and still be able to import it back to a newly created environment either manually or as part of an automated process using PowerShell scripts. The downside of this approach that needs to be considered is that the extracted XML file is significantly bigger than the archived configuration package.

The source code for this blog post can be found at https://github.com/ashirokikh/ashirokikh.com

There are good old tools for finding references to C/AL table fields or methods such as Prism for C/AL, or GDT Where Used Tool which I find very useful even today. Customizing the standard Dynamics NAV application used to be the most common way of filling the gaps in the business processes implementation, and these tools were absolutely crucial to have in order to make the modification reliable and consistent across the entire application. The Go to Definition action was added to C/SIDE some time ago, but there is still no big help in finding all places where an object is used.

With the move to AL, VS Code became the main development environment. It has been widely used by software developers to write applications in almost any language, and therefore, it has all the necessary tools to make their daily work productive. As a Business Central developer, there is one feature of VS Code that I wish the AL Language extension had. When working with an extension, it would be very helpful if the Go to References action supported finding code references across the extension and the AL symbols.

Challenge

Let's imagine we have just run the AL: Go! command and created a new extension project.

We have a task that involves extending an object. Getting familiar with the object and its references first is a good idea before we can say how big our work is. For that, we press Ctrl and left-click on the "Customer List" to go to definition. The SourceTable of the page is Customer, and we'd like to see where it's used. We right-click on Customer and select the Go to References action. The figure below shows the not very exciting message saying that No references found for 'Customer'.

Of course, we can take the source code from the Business Central installation archive, extract it into a folder, and open it in VS Code as a second window to explore. And we may need another window if we need to dig further into the System Application to see examples of the Facade design pattern, for example, when we get bored. Wouldn't it be nice to have everything in one place? I hope it will be working sometime in the future but for now, let's see what we can do about it by using VS Code Workspaces.

Adding projects to VS Code workspace

A folder opened by VS Code is essentially a workspace. We're going to put together several folders, which will become a multi-root workspace. It's supported by the AL Language extension, so let's start by creating an empty folder and opening it. Then, we follow the menu File -> Add Folder to Workspace... and select the ALProject1 folder with the extension project we created earlier. The result now should look as follows.

Let's keep this workspace for future use and go to File -> Save Workspace As..., which will create a new code-workspace file.

Your folder path might be different depending on your projects' locations.

If you want to keep just one set of symbols in the workspace, and this is a completely optional step, create an alpackages folder where we'll have our symbols to share across the projects of our workspace. By adding the al.packageCachePath path to the workspace settings, we let the AL compiler know where to look for the symbols. In my case, the path to the alpackages folder is C:\al\al-workspace\alpackages. It's important to have an absolute path so that all referenced projects refer to the same path.

After that, copy the symbols from our ALProject1\.alpackages folder to the workspace's package cache folder and reload VS Code (hit Ctrl+Shift+P to open Command Palette and type reload to find the Developer: Reload Window command) to finish the symbols setup. All red squiggly lines should go away now and our ALProject1 should be able to see the shared symbols. The window now should look as in the below figure.

Update 28/04/2022: Although knowing about the al.packageCachePath setting can be useful, symbols also can be downloaded for each of the added app separately, if we skip the previous step. The AL compiler seems to like symbols per app more.

Now things get even more interesting. Let's add the Base App source code.

The standard Business Central source code comes with the installation package. For this exercise, I'm following a tip from Arend-Jan Kauffmann given in a BC Professionals Discord channel. I'm going to clone Stefan Maroń's repository MSDyn365BC.Code.History. It is regularly updated when a major version is released. Its current size is more than 5 GB, which means cloning the repository will take some time. The fetched codebase can be very handy if we want to play with different localization or versions, we could just check out the dedicated branch.

I'm working with the Australian localization, therefore, once the repo is cloned, I check out the au-19 branch and add the Base App source folder (in my case, at C:\git\MSDyn365BC.Code.History\BaseApp\Source\Base Application) to our workspace. VS Code will process the new project addition for several minutes, there should be no errors as a result.

If we try and Go to Definition of the Customer List page now, we'll end up on the Customer List.dal tab with the symbols source code as before. The trick of pointing to the Base App project in our workspace is adding the Base App as a dependency to the extension app. After updating our extension, the app.json file content will look as follows.

{
  "id": "583af059-c0cb-42e2-b2d8-eeb89e3ad67a",
  "name": "ALProject1",
  "publisher": "Default publisher",
  "version": "1.0.0.0",
  "brief": "",
  "description": "",
  "privacyStatement": "",
  "EULA": "",
  "help": "",
  "url": "",
  "logo": "",
  "dependencies": [
    {
      "id": "437dbf0e-84ff-417a-965d-ed2bb9650972",
      "name":  "Base Application",
      "publisher":  "Microsoft",
      "version": "19.1.0.0"
    }
  ],
  "screenshots": [],
  "platform": "1.0.0.0",
  "application": "19.0.0.0",
  "idRanges": [
    {
      "from": 50100,
      "to": 50149
    }
  ],
  "resourceExposurePolicy": {
    "allowDebugging": true,
    "allowDownloadingSource": false,
    "includeSourceInSymbolFile": false
  },
  "runtime": "8.0"
}

This is it! Now if we go to the Customer List page definition from our HelloWorld.al code, we'll get into the CustomerList.Page.al file! Now try using Go to Referfeces from the Customer List page reference in the page object.

Right? There are references from our extension and Base Application. Now we're navigating!

If Base Application navigation is all you need, you could stop at this point. Although I'd like to say that System Application is something that we definitely need to check out. It's just beautiful, implemented as separate apps using interfaces. I'll add my C:\git\MSDyn365BC.Code.History\System Application\Source\System Application folder to the workspace and give it some time to cook.

Now let's imagine, we need to work with InStream or OutStream, the Temp Blob codeunit can help with that.

The Temp Blob codeunit is part of System Application. We get to the symbols code if we navigate to its definition at this point. It should be okay after updating our app.json again by adding the following dependency after a comma.

 {
   "id":  "63ca2fa4-4f03-4f2b-a480-172fef340d3f",
   "name":  "System Application",
   "publisher":  "Microsoft",
   "version":  "19.1.0.0"
 }

The result should look as in the figure below.

Finally, we can witness a great piece of documented source code if we go to the Temp Blob codeunit definition.

Conclusion

Following the steps in this article, we have set up an environment where we can navigate across our extensions along with Base and System Applications. Our application can even be published from the workspace - just select the HelloWorld.al file on the list and hit F5.

The workspace can be a bit slow to work though. The good news is that this setup also works if we decide to open only our application folder for faster development when symbols are just enough. We can always return back to the VS Code workspace if we need better navigation without using any other tool.

If anything didn't work for you, or something could be done better, please let me know in the comments. Happy sailing!

There are a couple of tips that can help with the setup in specific cases.

Tip #1

Disabling VS Code extensions for the workspace can improve processing performance. The AL Language extension is a must-have, of course.

Tip #2

If you're developing against a localized Business Central version, ensure to use the source code for the country.

Tip #3

Ensure the source code in the referenced folders belongs to the same version as the symbols, or remove the app symbols with code in a workspace. For instance, if we put the Microsoft_System Application_19.1.31886.32889.app file into the alpackages folder, and System Application source code that we have in a workspace folder is of version 19.1.31886.32186, we might get confusing at the first sight errors.

Adding a dependency in app.json to an existing app in the workspace removes the requirement to have symbols.

Building a custom reporting system with direct SQL queries to the Business Central can be done with a good understanding of the application data types and how values are persisted in the database. One interesting issue I've come across recently is reading a text value from a BLOB field. This blog post is for you if you're looking for a way to get the text values of a BLOB field directly from a SQL query without having to modify the Business Central code base.

The Problem

A BLOB field in Business Central corresponds to a database column of type image. It can hold text values far longer than a table field of type Text. Therefore, BLOB has been a reliable choice of a column type when we need to provide a way for adding detailed comments or descriptions where the length limitation of 250 characters would be an issue.

If a BLOB field is for storing a text value, it usually has its handler methods in the table which might look as follows (example from the Sales Header table, field Work Description):

    procedure GetWorkDescription() WorkDescription: Text
    var
        TypeHelper: Codeunit "Type Helper";
        InStream: InStream;
    begin
        CalcFields("Work Description");
        "Work Description".CreateInStream(InStream, TEXTENCODING::UTF8);
        if not TypeHelper.TryReadAsTextWithSeparator(InStream, TypeHelper.LFSeparator(), WorkDescription) then
            Message(ReadingDataSkippedMsg, FieldCaption("Work Description"));
    end;
    
    procedure SetWorkDescription(NewWorkDescription: Text)
    var
        OutStream: OutStream;
    begin
        Clear("Work Description");
        "Work Description".CreateOutStream(OutStream, TEXTENCODING::UTF8);
        OutStream.WriteText(NewWorkDescription);
        Modify;
    end;

The text value is saved by creating a stream for the BLOB field and writing the text into it. As a result, it's stored as raw bytes in the SQL server database. It wouldn't be a big problem to convert the saved value from bytes to text with Transact-SQL. The SQL query would be as follows:

SELECT CONVERT(varchar(max), CONVERT(varbinary(max), [Work Description])) as [Work Description]
FROM [CRONUS Australia Pty_ Ltd_$Sales Header] with(nolock)
WHERE [Work Description] IS NOT NULL

There is one little detail, however. The bytes are compressed by Business Central before they are sent to the SQL server. The saved Work description text value into the field would be returned by the SQL query as E}[Ï/ÊVHI-N.Ê,(ÉÌÏ, which we might doubt is useful, obviously.

An Option

The property that is responsible for BLOB value compression is Compressed, its default value is true.

"Aha! We just need to change that property to false and it's solved! And here are some Stack Overflow discussions that prove that it's working.", we might get excited. But then we remind ourselves that every non-default behavior implemented in source code requires maintenance in the future, and we should find the right solution for ourselves.

Maybe the reporting team is not responsible for the code and it's a dependency on other teams. Or maybe it's a third-party product that we have no control over. We should keep away from customizing the third-party or standard base application code, and there is no option to extend a BLOB table field by overriding the Compressed property value in an AL app. Even if we make the field change happen now, how about all the rest compressed by default BLOB fields that we have to alter the source code for? The way to make it work on the SQL side without having to change anything in the application could be a good solution in these cases.

The SQL CLR Solution

The task is simple. We need to decompress the byte data before converting it to text.  The built-in DECOMPRESS T-SQL function can look to be useful, but it's using the GZIP algorithm and not working for us.

There are multiple articles showing successful implementation of reading text from image fields. For example, Accessing Compressed Blobs from outside NAV (NAV2013) (Revisited) | deV.ch - man vs. code (wordpress.com). The conclusion that we can make from that C# code is that we're missing 2 pieces in T-SQL: there are magic bytes in compressed BLOB values that we have to check, and the values are compressed with the Deflate algorithm. Once these two problems are addressed in SQL Server, we should be able to query the database directly.

Now, how can we use .NET code to extend SQL Server functionality? With SQL Server CLR integration, a small class can be written for value handling which can be compiled as a library. The library can be uploaded to the server as an assembly, which can serve as a foundation for our custom T-SQL function.

Following the Getting Started with CLR Integration article, I needed a .NET Framework 4.8 installed that is compatible with the SQL Server 2019 on my computer (the framework version should be compatible with SQL Server versions 2012+ according to this source). Here is the code of the class to compile:

using System.Linq;
using Microsoft.SqlServer.Server;
using System.Data.SqlTypes;
using System.IO;
using System.IO.Compression;

public class BcBlobDecompressor
{
    private static readonly byte[] BlobMagic = new byte[] { 2, 69, 125, 91 };

    [SqlFunction(DataAccess = DataAccessKind.None, IsDeterministic = true)]
    public static SqlBytes Decompress(SqlBytes inBytes)
    {
        if (inBytes == null || inBytes.Length < 4)
            return inBytes;

        byte[] firstFourBytes = inBytes.Buffer.Take(4).ToArray();
        if (!BlobMagicOk(firstFourBytes))
        {
            return inBytes;
        }

        using (Stream inBytesStream = inBytes.Stream)
        {
            inBytesStream.Read(firstFourBytes, 0, 4);
            var outStream = new MemoryStream();
            using (DeflateStream deflateStream = new DeflateStream(inBytesStream, CompressionMode.Decompress))
            {
                deflateStream.CopyTo(outStream);
                return new SqlBytes(outStream);
            }
        }                
    }
    private static bool BlobMagicOk(byte[] checkMagic)
    {
        return checkMagic.SequenceEqual(BlobMagic);
    }
}

The code can be copy-pasted into a file BcBlobDecompression.cs which can be put in, let's say, C:\temp\sqlclr\ folder. If we run cd C:\temp\sqlclr in the terminal to make it the current folder, the PowerShell compilation command then would look like as follows:

C:\temp\sqlclr\> C:\Windows\Microsoft.NET\Framework\v4.0.30319\csc.exe /target:library .\BcBlobDecompression.cs

The result of the steps is the BcBlobDecompression.dll file that will be used for our BC BLOB decompression function.

The next step is uploading the assembly to the SQL Server. Firstly, let's enable CLR on the server by following the Microsoft docs article.

EXEC sp_configure 'clr enabled', 1;  
RECONFIGURE;  
GO  

The SQL Server 2019 has clr strict security enabled by default and the CREATE ASSEMBLY request stated in the guide failed for me with the error: CREATE or ALTER ASSEMBLY for assembly 'BcBlobDecompression' with the SAFE or EXTERNAL_ACCESS option failed because the 'clr strict security' option of sp_configure is set to 1. Microsoft recommends that you sign the assembly with a certificate or asymmetric key that has a corresponding login with UNSAFE ASSEMBLY permission. Alternatively, you can trust the assembly using sp_add_trusted_assembly.

If we use our decompression library on a production server, we'd better not turn off security features for the sake of it. Having looked at the best practices following this blog post, the following assembly installation script was created.

-- Source: https://pastebin.com/mwi5BidL

use [master]
-- Verify that "clr strict security" is 1 (i.e. ON), and that TRUSTWORTHY is 0 (i.e. OFF):
PRINT CHAR(13) + CHAR(10) + 'Verifying settings...';
SELECT *
FROM   sys.configurations sc
WHERE  sc.[configuration_id] = 1587 -- "clr strict security"
 
SELECT [name], [is_trustworthy_on], [collation_name]
FROM sys.databases WHERE [database_id] = DB_ID(N'YourDatabaseName');
GO

USE [YourDatabaseName]

-----------------------------------------------------------
-- Create asembly and function:

IF (OBJECT_ID(N'dbo.DecompressBcBlob') IS NULL)
BEGIN

	PRINT CHAR(13) + CHAR(10) + 'SQLCLR UDF [DecompressBcBlob] does not exist:';

	PRINT ' TEMPORARILY Altering Database to set TRUSTWORTHY=ON...';
		ALTER DATABASE [YourDatabaseName]
			SET TRUSTWORTHY ON;

	IF (ASSEMBLYPROPERTY(N'BcBlobDecompression', N'MvID') IS NULL)
	BEGIN
		PRINT ' Creating [BcBlobDecompression] Assembly...';

		CREATE ASSEMBLY BcBlobDecompression 
		AUTHORIZATION  dbo
		FROM 'C:\temp\sqlclr\BcBlobDecompression.dll' WITH PERMISSION_SET = SAFE;
	END;

	PRINT ' Altering Database to set TRUSTWORTHY back to OFF...';
	ALTER DATABASE [YourDatabaseName]
		SET TRUSTWORTHY OFF;

	PRINT N'    Creating [dbo].[DecompressBcBlob]...';
		EXEC(N'
	CREATE FUNCTION [dbo].[DecompressBcBlob]
	(
		@BlobValue VARBINARY(MAX)
	)
	RETURNS VARBINARY(MAX)
	WITH    EXECUTE AS CALLER,
			RETURNS NULL ON NULL INPUT
	AS EXTERNAL NAME [BcBlobDecompression].[BcBlobDecompressor].[Decompress];
	');

END;
GO

-----------------------------------------------------------
-- Sign assembly for the database:
 
IF (SUSER_ID(N'YourDatabaseName-BcBlobDecompression-Login') IS NULL)
BEGIN
    PRINT CHAR(13) + CHAR(10) + 'Permission Login does NOT exist:';
 
    IF (CERT_ID(N'YourDatabaseName-BcBlobDecompression-Cert') IS NULL)
    BEGIN
        PRINT ' Creating Certificate in [YourDatabaseName]...';
        CREATE CERTIFICATE [YourDatabaseName-BcBlobDecompression-Cert]
            ENCRYPTION BY PASSWORD = 'CiKqB9wv88wYCB'
            WITH SUBJECT = 'Sql Quantum Leap',
            EXPIRY_DATE = '2099-12-31';
    END;
 
    IF (NOT EXISTS(
                    SELECT *
                    FROM  sys.crypt_properties cp
                    INNER JOIN sys.assemblies sa
                            ON sa.[assembly_id] = cp.[major_id]
                    WHERE sa.[name] = N'BcBlobDecompression'
                ))
    BEGIN
        PRINT ' Signing the Assembly...';
        ADD SIGNATURE
            TO Assembly::[BcBlobDecompression]
            BY CERTIFICATE [YourDatabaseName-BcBlobDecompression-Cert]
            WITH PASSWORD = 'CiKqB9wv88wYCB';
 
    END;        
 
    IF (NOT EXISTS(
                    SELECT *
                    FROM   [master].[sys].[certificates] crt
                    WHERE  crt.[name] = N'YourDatabaseName-BcBlobDecompression-Cert'
                ))
    BEGIN
        PRINT ' Copying the Certificate to [master]...';
        DECLARE @PublicKey VARBINARY(MAX),
                @SQL NVARCHAR(MAX);
 
        SET @PublicKey = CERTENCODED(CERT_ID(N'YourDatabaseName-BcBlobDecompression-Cert'));
 
        SET @SQL = N'
CREATE CERTIFICATE [YourDatabaseName-BcBlobDecompression-Cert]
    FROM BINARY = ' + CONVERT(NVARCHAR(MAX), @PublicKey, 1) + N';';
        --SELECT @PublicKey AS [@PublicKey]; -- DEBUG
        --PRINT @SQL; -- DEBUG
 
        EXEC [master].[sys].[sp_executesql] @SQL;
    END;
 
 
    PRINT ' Creating permissions Login...';
    EXEC [master].[sys].[sp_executesql] N'
CREATE LOGIN [YourDatabaseName-BcBlobDecompression-Login]
    FROM CERTIFICATE [YourDatabaseName-BcBlobDecompression-Cert];
';
END;
GO

PRINT CHAR(13) + CHAR(10) + 'Granting UNSAFE ASSEMBLY permission...';
EXEC [master].[sys].[sp_executesql] N'
GRANT UNSAFE ASSEMBLY TO [YourDatabaseName-BcBlobDecompression-Login]; -- REQUIRED!!!!
'; 
GO

PRINT '';
SELECT ASSEMBLYPROPERTY(N'BcBlobDecompression', 'CLRName') AS [CLRName];

/*
-----------------------------------------------------------
-- Clean up:
 
PRINT CHAR(13) + CHAR(10) + 'Cleaning up objects (to be re-runnable)...';
 
USE [YourDatabaseName]
DROP FUNCTION [dbo].[DecompressBcBlob]
DROP ASSEMBLY [BcBlobDecompression];
DROP CERTIFICATE [YourDatabaseName-BcBlobDecompression-Cert];
 
USE [master];
DROP LOGIN [YourDatabaseName-BcBlobDecompression-Login];
DROP CERTIFICATE [YourDatabaseName-BcBlobDecompression-Cert];
*/

In order to run it, replace the YourDatabaseName string with your database name and the password for assembly signing can be changed as well. The script works per database, hence the database names utilization. The clean-up section needs to be run whenever a new version of the assembly needs to be created. I had to ensure the database owner is the sa user (or the same as the owner of the master database).

If the script runs without errors, you now should be able to check if the DecompressBcBlob function works by running the following examples:

select dbo.DecompressBcBlob(null)
select dbo.DecompressBcBlob(0x02457D5B0B29CF0700)
select dbo.DecompressBcBlob(0x54776F)

The results should look as follows.

The first select query checks if the NULL value is handled. The second one passes a compressed text example. The third result returns the same uncompressed value as if the Compressed property of the BLOB field is set to false.

The SQL query that would return text value from a Business Central BLOB field may look like as follows:

SELECT CONVERT(varchar(max), dbo.DecompressBcBlob(CONVERT(varbinary(max), [Work Description]))) as [Work Description]
FROM [CRONUS Australia Pty_ Ltd_$Sales Header] with(nolock)
WHERE [Work Description] IS NOT NULL

It's working but slightly unreadable. How about creating another function for this? To do that, run the following SQL script.

CREATE FUNCTION dbo.ConvertBcBlobToText
(
	@i image
)
RETURNS varchar(max)
AS
BEGIN
	RETURN CONVERT(varchar(max), dbo.DecompressBcBlob(CONVERT(varbinary(max), @i)));
END
GO

With that last enhancement, our query becomes as elegant as follows:

SELECT dbo.ConvertBcBlobToText([Work Description]) as [Work Description]
FROM [CRONUS Australia Pty_ Ltd_$Sales Header] with(nolock)
WHERE [Work Description] IS NOT NULL

Conclusion

Using this SQL CLR solution for Business Central BLOB field value decompression can be a good fit for a system built on a SQL Server on top of the application database using Transact-SQL. The assembly adds just the necessary function that the server needs to understand a compressed value by Business Central. It would allow you to build your own logic for reading the bytes and converting them into text.

We expect our Business Central or NAV application to perform well to accommodate the highest predicted volume of operations. Finding the root cause of a performance issue is often a challenging task especially if there is no good instrument for that on hand.

If you are running Business Central in the cloud or have converted your solution to AL (including on-premise versions), it is recommended to look into monitoring extensions with Application Insights (an example from Dmitry Katson) which is the industry standard for Microsoft cloud solutions. Otherwise, in case your system is still running on premise where we can use custom .NET libraries, the performance profiler I’m going to talk about in this article is definitely worth a shot.

NAV Application Profiler Is Still Out There

The NAV Application Profiler (EtwPerformanceProfiler) repository description states that it is a sample for profiling application code created by David Worthington and Dmytro Sitnik (while being part of the Dynamics NAV team) in 2013 and announced in 2014. ETW stands for Event Tracing for Windows, and the application is based on the Microsoft.Diagnostics.Tracing.TraceEvent library which, if interested, you could get familiar with by reading the library documentation. One interesting fact I learnt from it is that tracing with the library is asynchronous and therefore has almost no performance impact and it should be safe to run it on a production instance.

About a year ago (mid 2019), shortly after we upgraded NAV 2009 to Business Central version 14 and brought all our data, the load in production indicated some symptoms of code inefficiency by showing messages like a “table was locked by another user”. We needed something that would point us to the bottleneck and do it fast.

Having had a chance to get familiar with NAV Application Profiler before, I urged to try it but quickly realized it hasn’t been updated for some time and the last version it was updated to was NAV 2018 (according to the commit history). I used that opportunity to refresh my C# skills and after some time the profiler started working for our version of BC. Since then, our team has adopted the tool and now runs it every time before deploying a change to the codebase.

The fix should widen the range of supported platforms, the result of which is in the source code of the GitHub repository.

Installation Steps

The NAV Application Profiler repository is public, therefore anyone can clone and play with it. The .NET libraries can be built by Visual Studio 2019 Community edition which can be used for free for open source projects.

In case you would like to just download the installation package, I've build it for you. Please use the following link where I've put them together:

Download NAV Application Profiler files (1.5MB, built on 18/10/2020)

After you have the files, the next actions need to be performed:

1. Extract the files.
2. Copy the EtwPerformanceProfiler folder to the following locations
   1. Server Add-ins folder of BC. By default, it’s C:\Program Files\Microsoft Dynamics NAV\140\Service\Add-ins\ (for NAV 2013 it is C:\Program Files\Microsoft Dynamics NAV\80\Service\Add-ins)
   2. Role Tailored Client Add-ins folder which should be C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\140\RoleTailored Client\Add-ins (C:\Program Files (x86)\Microsoft Dynamics NAV\80\RoleTailored Client\Add-ins for NAV 2013)
3. Ensure the Enable Full C/AL Function Tracing is turned on in the instance configuration and restart the instance if it wasn’t.
4. Import and compile the objects from the App Objects folder. The BC instance should see the libraries already. However, the libraries might get blocked by the system, which we can resolve by running an Unblock-File PowerShell command or by manually unblocking them in the file properties.

Now that we have our objects compiled, we can proceed to the most exciting part, seeing what are the most time-consuming lines in our code!

Running NAV Application Profiler

The main application profiler page is the page 50000 Performance Profiler, let's run it from the Development Environment.

It is possible to trace multiple sessions but we would often target our session to analyze performance. One of the ways of finding out the Session ID is using the Debug Session function and see all running sessions on the instance. I've started another client session to run a user operation example and have now two sessions running, which you can see in the picture below.

In the example below, I specified my second session as the target session and hit the Start action button to get the ball rolling.

Now, using the second client, we could run the code that concerns us. I'm going to open the Vendors page and then stop the profiler.

After tracing data is collected, it's read by NAV Application Profiler and aggregated into the table with a hierarchical view. We can see the Object Types, Object IDs, C/AL, and SQL statements with duration and hit counts, all ready for our analysis. How amazing is that? If you are looking for a particular statement, you could try filtering the Statement column specifying *<my statement substring>* as the filter value and see how well that code line behaves itself.

The Copy To Archive function lets us save the results in the database to be able to refer to it later. The Archive action button can be used to open archived traced data.

Summary

Deploying NAV Application Profiler to an on-premise Business Central or NAV can be a life-changer. I have caught myself multiple times already wrongly assuming a particular area was the culprit of the performance degradation. This tool can provide us with facts to address problems quickly and directly.

Business Central 2019 wave 1 (version 14) is going to stay with us for some time considering the next versions support AL applications only. Its mainstream support end date has already been moved to October 10, 2023, according to the Fixed Lifecycle Policy. Even if all the customization logic has been moved to AL, there are some cloud limitations like the database size of 80 GB or other reasons that would make you choose to stay an on-premises customer. The C/AL NAV Application Profiler objects can be converted to AL and you should still be able to use it happily after.  

Although NAV Application Profiler can help troubleshoot performance issues significantly, it is best to avoid them at the design stage. Great places to look at to master the skill are the performance articles for developers and numerous Dynamics 365 BC community blog posts (like this one by Roberto Stefanetti).

I hope you enjoyed reading this post and the performance profiler helps to make your application or customization more efficient and your BC users happier.

Additional Tips

Deploy NAV Application Profiler to a Container

A BC container version 14 was used for the examples in this article. Below are the steps and scripts that were used.

$containerName = 'bc14dev'
$imageName = "mcr.microsoft.com/businesscentral/onprem:14.11.41204.0-au"

$credential = New-Object pscredential 'dev', (ConvertTo-SecureString -String 'dev' -AsPlainText -Force)

Measure-Command {
    New-BCContainer -accept_eula `
        -accept_outdated `
        -containerName $containerName `
        -imageName $imageName `
        -auth UserPassword `
        -credential $credential `
        -doNotExportObjectsToText `
        -memoryLimit 10G `
        -updateHosts `
        -includeCSide `
        -myscripts @()
}

In order to import the text files and modify them, a license might be required. You should be able to import the fob file with all objects in any case.

Once the container is running, I ran the following

cd C:\Temp\NAVAppProfiler\ # your unzipped folder
Compress-Archive -Path .\EtwPerformanceProfiler\* -DestinationPath .\EtwPerformanceProfiler.zip
Copy-FileToBcContainer -containerName bc14dev -localPath .\EtwPerformanceProfiler.zip -containerPath 'c:\Temp\EtwPerformanceProfiler.zip'
Open-BcContainer bc14dev

The below commands were executed in the container PowerShell session.

Expand-Archive -Path C:\Temp\EtwPerformanceProfiler.zip -DestinationPath C:\Temp\EtwPerformanceProfiler\
Copy-Item -Path "C:\Temp\EtwPerformanceProfiler\" -Destination "C:\Program Files\Microsoft Dynamics NAV\140\Service\Add-ins\" -Recurse
Set-NAVServerConfiguration -ServerInstance nav -KeyName EnableFullALFunctionTracing -KeyValue true
Get-NAVServerInstance | Restart-NAVServerInstance -Force -Verbose

BC Container Helper creates the RoleTailered Client folder on your machine, therefore the libraries need to be copied to C:\ProgramData\BcContainerHelper\Extensions\bc14dev\Program Files\140\RoleTailored Client\Add-ins to be able to compile the objects in NAV Development Environment.  

The final step is importing the BC objects, compiling them with the Synchronize Schema option set to Later, and tenant synchronization with the following command in the container's PowerShell terminal.

Get-NAVServerInstance | Sync-NAVTenant -Force -Verbose

Spending time efficiently while working is mainly about having proper tools. If you're a software engineer, there are many points why Docker is worth investing your time. The main argument for me as a D365 Business Central (BC) developer is that you can keep your computer clean of BC installations and work with multiple versions of the system at the same time!

This post is for you if you still think that Business Central (BC) development using Docker is something difficult to start with. Freddy Kristiansen (Microsoft) with help of other contributors has done a great job to make it easier for everyone to include this amazing tool into our collection by introducing a BC Container Helper.

If you are teamed up with an end user and don’t have the Microsoft Partner portal access, using Docker is a very liberating experience with regard to being able to play with the source code of multiple application versions. Have you ever wanted to quickly get an original BC object without customization, or to see how the next version looks like? Now it can be done with spinning up a local BC environment with the version.

Convinced to give it a try? Let's get to it!

Prerequisites

The prerequisites for this walk-through are as follows:

• Windows 10 Enterprise, Pro, or Education (Hyper-V virtualisation is required for Docker on Windows).
• Good unlimited Internet connection.

The steps below were run on a Virtual Machine (VM) based from the Windows 10 dev environment image to ensure everything is done on a clean machine. See the VM specific extra steps below if you use a VM.

Getting Docker Desktop

When I try to search for Docker, a popular search engine points me at https://hub.docker.com/editions/community/docker-ce-desktop-windows for the Docker Desktop installation resources. We need the Community Edition (CE) version.

You don’t have to have a Docker account to complete this step. Download the Stable version package, run it and follow the installation instructions.

Once the installation is completed, we need to switch to Windows containers using the Docker tray icon.

If the Containers feature has not been enabled, Docker will exit for the error.

That can be fixed by running the following PowerShell command as Administrator and restarting the computer.

Enable-WindowsOptionalFeature -Online -FeatureName Containers -All

The version of Docker Desktop that was used for this walkthrough is 2.3.0.5.

Getting BC Container Helper

Open a PowerShell window as Administrator and paste the following command that should install the version 1.0.4 (current at the moment of writing) of the module,

Install-Module -Name BcContainerHelper -RequiredVersion 1.0.4

confirming installation of the dependencies along the way. The PowerShell Gallery lists the module versions and specifying the latest stable version is usually a good idea.

Creating a Business Central Container

Ensure Docker Desktop is running and run Docker Desktop if it's not there.

Your environment might have the required execution policy. Otherwise, set it to RemoteSigned with the following command in case there are issues with running the scripts below.

Set-ExecutionPolicy RemoteSigned

Check the module is working by typing in the following.

Write-BcContainerHelperWelcomeText

To ensure the module has the permissions required, run the command below.

Check-BcContainerHelperPermissions -Fix

I’m using the Australian version so the image tag is au-ltsc2019. Run the following script to create the latest available on Docker Business Central (update the image tag if required). You could save it in a file with the .ps1 extension and put somewhere close. The script should not require running as Administrator.

$artifactUrl = Get-BCArtifactUrl -version 16 -country au -select Latest
$containerName = "bclts"
$authenticationType = 'NavUserPassword' # or Windows for the current AD user

Write-Host "*** Starting $containerName container creation ***" -ForegroundColor Yellow
Write-Host "Artifact URL: $artifactUrl"

if ($authenticationType -ne 'Windows'){
    $credential = get-credential -Message "Enter BC Super User credentials"
}
Measure-command {
    New-BCContainer -accept_eula `
                    -accept_outdated `
                    -containerName $containerName `
                    -artifactUrl $artifactUrl `
                    -auth $authenticationType `
                    -credential $credential `
                    -memoryLimit 10G `
                    -updateHosts `
                    -includeAL `
                    -myscripts @()
}

Enter the container administrator user credentials if you’re asked to.

Docker will start downloading the image.

Running the script fist time will take quite a bit of time as it downloads docker images and artifacts (took ~30 minutes for me). Once it finishes, the result console look will resemble the below.

Last output lines include some useful information about the container, such as the .vsix file location that we’ll need to set up Visual Studio Code. In case the output info somehow got lost, the following command should give you enough data.

docker logs bclts

You’ll notice some newly created shortcuts on your Desktop.

Feel free to follow the Web Client link and confirm the application is working! If you follow the naming in this post, it should be http://bclts/BC/.

After entering the credentials, you should see something like this.

Congratulations, you’ve just created a working environment of the latest version of Business Central!

The beauty of using Docker is that no matter how creative you mess with the container, you can save your progress, delete the container, and spin up a new one in about 10 minutes! Once the images are downloaded to your machine, they’ll be used for your next container as long as you use the same BC Docker image tag.

Setting Up Visual Studio Code

Visual Studio Code is the most popular IDE for AL development and is required to go further.

Download the vsix file using the address from your logs which contains the AL language version that matches the container. It’s http://bclts:8080/ALLanguage.vsix in my case.

When switching between the containers from different release waves, install the extension from the VSIX file that comes with the container if there are issues.

Then open VS Code, go to the Extensions tab and hit the Install from VSIX menu item, and select the downloaded file.

After the extension is installed, hit Alt+A, Alt+L to trigger the AL Go! command, specify a to be created project folder and which version to run.

Then select the latest platform.

After the project forlder opens up automatically, select Your own server as the server when the dialog pops up.

Next, escape from the server authentication prompt as we need to update the launch.json to point to our container instance.

Now we need the container name that we specified before, and the Dev. Server Instance name that was mentioned in the logs. My result launch.json file looks as below.

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

Publishing AL Extension

You might have noticed that the Hello World application is already there created for us. If you look at the HelloWorld.al file, it extends the Page 22 Customer List to display the "App published: Hello world" message. I don’t believe it will break the system, so let’s skip testing and just deploy it!

Now hit F5 and enter the container user credentials.

The below is a picture of Visual Studio Code in the Debugging mode that it switches to as a result of the previous action.

Now wait a moment and the Web Client should pop up, and the Customer List page should open. And when it opens, we can see our powerful extension at work!

Woo-hoo, finally! Now that we have everything working, don't be shy, apply your creativity and break things! That's usually the outcome of trying to learn something new for me.

Summary

If your company is running the NAV 2016 or later version, there is probably a Docker image for you to play with. Many of us are running a customized version of NAV/BC, and refreshing (or if you aim for the next version, updating) the knowledge about how the standard logic works adds to the quality of what you're doing.

Next time you start a new project, try using a BC Docker image to do some testing on the specific application version to identify the gaps in the standard functionality first. Then do some prototyping to see how it might work out for you (without the rest of customization if possible). And remember, if you break the environment, you'll get a shiny clean one in 10 minutes! Just remove the container and create a new one.

I hope you enjoyed reading this article and learned a couple of new tricks. Thank you for reading and until next time!

Additional Tips

Here are some useful commands for working with containers:

docker ps # check running containers
docker ps -a # get all containers on the machine
docker stop <container-name> # stop a container, saves memory if not using it
docker start <container-name> # start a stopped (status Exited) container

Getting errors similar to the below would mean Docker Desktop is not running.

Without a good understanding of the BC Docker environment, we probably shouldn’t go much further with the docker commands on BC containers. It’s always best to use the available in the BcContainerHelper commands. The wrappers for the commands above are as follows:

Get-BCContainers # get all BC containers on the machine
Stop-BCContainer <container-name>
Start-BCContainer <container-name> # also provides the start-up logs and BC container specific information like the vsix file location for AL development

By the way, the Get-BCContainers command is an alias of the Get-NavContainers command and they can be used interchangeably. Same applies for the rest of the commands.

Once you've finished with a container, just remove it.

Remove-BCContainer <container-name> # takes care of the Desktop shortcusts too!

In case there isn’t a method for you and you have a good idea, the NavContainerHelper (still has the original name) repository is open to submission of pull requests and contributions!

Additional Links

If you’re new to AL, Getting Started with AL is a great place to look at for further learning AL language and extending Business Central functionality.

I haven’t tried it yet but AL Object Designer looks very promising if you’re looking for a C/SIDE-like experience, and it comes with some extra nice features.

More information on Docker is available at the website https://docs.docker.com/desktop/.

For more information on BC Container Helper, Freddy’s blog is where heaps of it can be found.

In case a BC version 14 or an older NAV version is required, we might need to still need to follow the traditional path and use docker images with NavContainerHelper. The full list of image tags and other information is available at https://hub.docker.com/_/microsoft-businesscentral-onprem.

Dynamics NAV 2016 to 2018 images can be found at https://hub.docker.com/r/microsoft/dynamics-nav. The container creation parameters might need to be different for them. Here is a script that I used last time to create a BC 14 container:

$navImage = "mcr.microsoft.com/businesscentral/onprem:14.11.41204.0-au"
$containerName = "bc14dev"
$licenseFile = (Join-Path $PSScriptRoot "\license.flf")
$authenticationType = 'UserPassword'

Write-Host "*** Starting $containerName container creation ***" -ForegroundColor Yellow

if ($authenticationType -ne 'Windows'){
    $credential = get-credential -Message "Enter NAV Super User credentials"
}

Measure-command {
    New-NavContainer -accept_eula `
                    -accept_outdated `
                    -containerName $containerName `
                    -imageName $navImage `
                    -credential $credential `
                    -memoryLimit 10G `
                    -includeCSide `
                    -doNotExportObjectsToText `
                    -alwaysPull `
                    -updateHosts $true `
                    -auth $authenticationType `
                    -myScripts @() `
                    -navDvdPath "" `
                    -includeTestToolkit `
                    -doNotCheckHealth 
}

IF($licenseFile -ne ""){
    Import-NavContainerLicense -containerName $containerName -licenseFile $licenceFile
}

Write-Host "*** $containerName container creation completed ***" -ForegroundColor Green

Notice it has the -includeCSide parameter to include our beloved C/SIDE development environment. It also has the -includeTestToolkit to exercise automated unit testing skills. Feel free to try and figure our the parameter set that suits your needs.

Extra Steps to Set Up the Windows 10 Dev Environment VM

The Windows 10 VM for this walkthrough was created using the Quick Create action in Hyper-V Manager.

Then the image (16.10 GB) is downloaded and the machine is created.

After that, turn it off and enable nested virtualization for it https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/user-guide/nested-virtualization by running the following command as Administrator:

Set-VMProcessor -VMName <VMName> -ExposeVirtualizationExtensions $true

Set the amount of memory to at least 8 GB. It should perform better with 10 GB+ of RAM.