Share This Post

Business Central Extensions V1 to V2 Conversion

This article explains the Business Central Extensions V1 to V2 Conversion steps that are involved in converting V1 extensions, written in C/SIDE to V2 extensions written using the AL Language extension for Visual Studio Code.

Extensions are a programming model where functionality is defined as an addition to existing objects and defines how they are different or modify the behavior of the solution. The overall steps for the conversion are:

  • Convert the source code from C/AL to the AL syntax.
  • Complete the development of the extension in AL syntax.
  • Write upgrade code to restore and modify data from the V1 Extension tables.
  • Build the Business Central Extensions.
  • Uninstall the V1 extension and publish and run upgrade on the V2 extension.

Business Central Extensions V1 to V2 Conversion Steps

1. Convert the Source Code from V1 to V2

To convert the source code, you must use the Txt2Al conversion tool. The Txt2Al conversion tool allows you to take existing application objects that have been exported in .txt format and convert them into the new .al format. The .al format is used when developing extensions for Dynamics 365 Business Central.

2. Complete the Development of the Extension

When the source code has been converted using the Txt2Al conversion tool, open the project folder in Visual Studio Code, and then modify or add code to the new version as needed.

You might run into compilation errors, which can typically be caused by:

  • Object IDs that have changed. The conversion tool tries to transform your code into the object ID range allowed for Extensions V2.
  • Field or control names look different; the AL syntax requires names, this means that no empty or default names are allowed.
  • Menu suites do not exist in Extensions V2.
  • .NET references are not allowed; there is no support for .NET types. Instead you must use the classes that replace .NET calls.

The version number is of the format Major.Minor.Build.Revision, for example To increase the version number, you must increase the value of MajorMinor, or Build by at least one, for example or

To use NAVAPP.RestoreArchiveData() method for upgrading, you must not change the IDs of the tables that are being restored; this means that tables from your V1 extension must have the same IDs in the V2 extensions.

3. Write Upgrade Code to Move Data from V1 Extensions

Just like with V1 extensions, you have to write code to handle data in tables during upgrade. Writing code for the V1 to V2 extension upgrade is very much alike to the code that you have been writing for V1 Extensions. The differences are:

  • Rather than adding code to normal codeunit, you write code in an upgrade codeunit, which is a codeunit whose SubType property is set to Upgrade.
  • Rather than adding code to the user defined methods OnNavAppUpgradePerDatabase() or OnNavAppUpgradePerCompany(), you add code to one or more of the system triggers for the data upgrade. These triggers are invoked when a data upgrade is started.
  • The table lists the upgrade triggers in the order in which they run.
Trigger Description
OnCheckPreconditionsPerCompany() or OnCheckPreconditionsPerDatabase() Used to check that certain requirements are met in order to run.
OnUpgradePerCompany() or OnUpgradePerDatabase() Used to run the actual upgrade work
OnValidateUpgradePerCompany() or OnValidateUpgradePerDatabase() Used to check that the upgrade was successful

However, for this one-time conversion, all of the same NAVAPP system methods you used in V1 extensions work with V2 extensions and can be called from any of the upgrade triggers.

Method Description
NAVAPP.DeleteArchiveData(70000000) Deletes the archived data from table 70000000.
NAVAPP.GetArchiveRecordRef(70000000, archRef) Gets a record ref to the archived data from table 70000000.
archVersion := NAVAPP.GetArchiveVersion() Gets the version of the archived data from the old extension.
NAVAPP.RestoreArchiveData(70000000) Restores the data from the archive of table 70000000.

By using these methods, you can restore or move all your data from the old V1 extension into the new V2 by running an upgrade.

4. Build the Extension Package

Press Ctrl+Shift+B to compile and build the Business Central Extensions complete with the application objects and upgrade codeunit.

5. Run the Upgrade

The final task of the conversion is to publish the V2 extension, and run the data upgrade. The following steps use an example that upgrades a V1 extension that is called ‘ProsewareStuff’ and has the version ‘’. The V1 extension is published, installed, and populated with data.

The V2 extension has the same name (and ID), but it has the version ‘’. The Dynamics 365 Business Central service instance is called ‘DynamicsNAV’, and there is only one tenant. The steps use the Dynamics NAV Server Administration tool.

  • Uninstall the V1 extension.

Uninstall-NAVApp -ServerInstance NAV -Name ProsewareStuff -Version

This removes the tables from the SQL Server database and archives extension data.

  • Publish the V2 extension. This example assumes the extension is not signed.

Publish-NAVApp -ServerInstance DynamicsNAV -Path .\ -SkipVerification

This validates the extension syntax against server instance, and stages it for syncing.

  • Integrate the V2 extension with the database.

Sync-NAVApp -ServerInstance NAV -Name ProswareStuff -Version

This adds tables from V2 extension to SQL database.

  • Run the upgrade process to handle archived data from the V1 extension.

Start-NAVAppDataUpgrade -ServerInstance NAV -Name ProswareStuff -Version

This executes the upgrade logic defined by the upgrade code unit in the extension and installs the new V2 extension.

  • (optional) Unpublish the V1 extension.

Unpublish-NAVApp -ServerInstance NAV -Name ProswareStuff -Version

This removes the unused Business Central Extensions package from server. The upgrade code unit turns into an integral part of the extension. The NAVAPP methods were mainly utilized for the conversion from V1 to V2.

After converting the extension, you should begin to write upgrade code. For more details on Microsoft Dynamics 365 Business Central Extensions V1 to Extensions V2 Conversion, please contact us.

Share This Post

Leave a Reply

Notify of
Skip to toolbar