Share This Post

Business Central Extension Install Code

There can be certain operations outside of the extension code itself that is required to be performed when an extension is installed. Microsoft Dynamics 365 Business Central Extension Install Code is run when:

  • An extension is installed for the very first time.
  • An uninstalled version is installed again.

These operations could include, for example, populating empty records with the data, service callbacks and version checks, telemetry and messages to users.

To execute these types of operations, you write extension install code. This enables you to write different code for initial installation and reinstallation.

Business Central Extension Install Code Process

1. How to Write Install Code

You write install logic in an install codeunit. This is a codeunit that has the SubType property set to Install. An install codeunit supports two system triggers on which you can add the Business Central Extension Install Code.

Trigger Description
OnInstallAppPerCompany() Includes code for company-related operations. Runs once for each company in the database.
OnInstallAppPerDatabase() Includes code for database-related operations. Executes once in the entire install process.

The Business Central Extension Install Code unit becomes an integral part of the extension version. You can have more than one install code unit. Although, be aware that there is no guarantee on the order of execution of the different codeunits. If you do use multiple install units, make sure that they can run independent of each other.

Install Codeunit Syntax

The following code illustrates the basic syntax and structure of an install codeunit:

codeunit [ID] [NAME]
{
Subtype=Install;

trigger OnInstallAppPerCompany()
begin
// Code for company related operations
end;

trigger OnInstallAppPerDatabase()
begin
// Code for database related operations
end;

}

Use the shortcuts tcodunit and ttrigger to create the basic structure for the codeunit and trigger.

Get Information about an Extension

Each extension version has a set of properties that contain information about the extension, including: AppVersion, DataVersion, Dependencies, Id, Name, and Publisher. This information can be helpful when installing.

For example, one of the more important properties is the DataVersion property, which tells you what version of data you are dealing with. These properties are encapsulated in a ModuleInfo data type. You can access these properties by through the NAVApp.GetCurrentModuleInfo() and NAVAPP.GetModuleInfo() methods.

Install Codeunit Example

This example uses the OnInstallAppPerDatabase() trigger to check whether the data version of the previous extension version is compatible for the upgrade.

codeunit 50100 MyInstallCodeunit
{
Subtype=Install;

trigger OnInstallAppPerDatabase();
var
myAppInfo : ModuleInfo;
begin
NavApp.GetCurrentModuleInfo(myAppInfo); // Get info about the currently executing module

if myAppInfo.DataVersion = Version.Create(0,0,0,0) then // A ‘DataVersion’ of 0.0.0.0 indicates a ‘fresh/new’ install
HandleFreshInstall
else
HandleReinstall; // If not a fresh install, then we are Re-installing the same version of the extension
end;

local procedure HandleFreshInstall();
begin
// Do work needed the first time this extension is ever installed for this tenant.
// Some possible usages:
// – Service callback/telemetry indicating that extension was installed
// – Initial data setup for use
end;

local procedure HandleReinstall();
begin
// Do work needed when reinstalling the same version of the extension back on the tenant.
// Some possible usages:
// – Service callback/telemetry indicating that extension was reinstalled
// – Data ‘patchup’ work, for example, detecting if new ‘base’ records have been changed while you have been working ‘offline’.
// – Setup ‘welcome back’ messaging for next user access.
end;
}

2. Generating Delta Files

You can use the Compare-NAVApplicationObject powershell cmdlet to generate .delta files from two versions of a set of application objects.

The cmdlet has a ExportToNewSyntax switch that allows generating .delta files that can be utilized as a starting point for creating extensions. Setting the ExportToNewSyntax flag generates .delta files that contain additional information needed to generate the correct structure and layout of extension objects.

The Txt2Al conversion tool will reject .delta files that were generated without using the -ExportToNewSyntax flag.

Using the ExportToNewSyntax switch for the Compare-NAVApplicationObject cmdlet produces a .delta file that can be converted to an extension.

The ExportToNewSyntax Flag
Parameter Description
Type SwitchParameter
Aliases None
Position Named
Default value None
Accept pipeline input False
Accept wildcard characters False
Example

Compare-NAVApplicationObject -OriginalPath “C:\PageWith2Controls.txt” -ModifiedPath “C:\PageWith3Controls.txt” -ExportToNewSyntax

For more details on Microsoft Dynamics 365 Business Central Extension Install Code and its process, please contact us.

Share This Post

Leave a Reply

avatar
  Subscribe  
Notify of
Skip to toolbar