Demystifying upgrade process for Business Central Apps

This is the second blog post on series.

The beginning is here Demystifying installation process for Business Central.

...In the previous series

We ended up with the summary: what's going on during the first-time installation of the app.

• Upgrade codeunit was not triggered at all. That’s because we publish our app for the first time.
• Install codeunit was triggered.

The result of this scenario can be displayed in the next picture

Figure 1. Install app for the first time

SCENARIO 2. Upgrading App

When you want to add some features or fix bugs you need to change the version of your app. With this simple approach, you will have transparency in what version has what functionality.

The official documentation is here. 

But before we upgrade

When you write upgrading business logic two questions appear 

• What app version is already installed?
• What app version is installing?

We need this to understand if current upgrade business logic is compatible with the already installed app.

For example, we want to populate data in the new Address field, while upgrading an app to v.2.

So we add something like

codeunit 50100 "Upgrade App"
{
    Subtype = Upgrade;

    trigger OnUpgradePerCompany()
    begin
        PopulateNewAddressField();
    end;

    local procedure PopulateNewAddressField()
    var
        Customer: Record Customer;
    begin
        With Customer do begin
            if FindSet() then
                repeat
                    "New Address" := 'some value';
                    Modify;
                until next = 0;
        end;
    end;
}

If you will leave this code as is, and upgrade to V.3 - this code will also be executed, which would be an unexpected result for everybody. 

NAVApp and ModuleInfo will help

To avoid this situation we need to create separate upgrade codeunit for each version. So previous code could be refactored to next one

codeunit 50100 "Upgrade App to v2"
{
    Subtype = Upgrade;

    trigger OnUpgradePerCompany()
    begin
        If not CheckIfInstallingAppVersionCompatibleWithInstalledVersion() then 
           exit;

        PopulateNewAddressField();
    end;

    local procedure CheckIfInstallingAppVersionCompatibleWithInstalledVersion() : Boolean
    begin
        Exit((GetInstallingVersionNo() = '2.0.0.0') and (GetCurrentlyInstalledVersionNo() = '1.0.0.0'));
    end;

    procedure GetInstallingVersionNo(): Text
    var
        AppInfo: ModuleInfo;
    begin
        NavApp.GetCurrentModuleInfo(AppInfo);
        exit(FORMAT(AppInfo.AppVersion()));
    end;

    procedure GetCurrentlyInstalledVersionNo(): Text
    var
        AppInfo: ModuleInfo;
    begin
        NavApp.GetCurrentModuleInfo(AppInfo);
        exit(FORMAT(AppInfo.DataVersion()));
    end;


    local procedure PopulateNewAddressField()
    var
        Customer: Record Customer;
    begin
        With Customer do begin
            if FindSet() then
                repeat
                    "New Address" := 'some value';
                    Modify;
                until next = 0;
        end;
    end;
}

With ModuleInfo you get info about your app.

• DataVersion tells you what version is currently installed 
• AppVersion tells you what version are you installing

Let's upgrade begins 

We will just increase version and install the app once again.

app.json > “version”: “2.0.0.0”

Container Sandbox

VSCode > AL:Publish without debugging (Ctrl+F5)

And we receive next error

Ok, let’s run this command Start-NavContainerAppDataUpgrade

Start-NavContainerAppDataUpgrade -containerName $containername `
    -appName $appname 

And will have a look at the installation log

Online Sandbox

VSCode > AL:Publish without debugging (Ctrl+F5)

>Web client > Extensions Page >Upload .app file

What's next

Next blog will be about the re-installation process. Stay tuned.