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.
|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]
// Code for company related operations
// Code for database related operations
Use the shortcuts
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
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
myAppInfo : ModuleInfo;
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
HandleReinstall; // If not a fresh install, then we are Re-installing the same version of the extension
local procedure HandleFreshInstall();
// 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
local procedure HandleReinstall();
// 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.
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.
ExportToNewSyntax switch for the
Compare-NAVApplicationObject cmdlet produces a .delta file that can be converted to an extension.
The ExportToNewSyntax Flag
|Accept pipeline input||False|
|Accept wildcard characters||False|
Compare-NAVApplicationObject -OriginalPath “C:\PageWith2Controls.txt” -ModifiedPath “C:\PageWith3Controls.txt” -ExportToNewSyntax