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
184.108.40.206. To increase the version number, you must increase the value of
Build by at least one, for example
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
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.
|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.
||Deletes the archived data from table 70000000.|
||Gets a record ref to the archived data from table 70000000.|
||Gets the version of the archived data from the old extension.|
||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 ‘220.127.116.11.’. The V1 extension is published, installed, and populated with data.
The V2 extension has the same name (and ID), but it has the version ‘18.104.22.168’. 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 22.214.171.124
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 .\ProswareStuff_126.96.36.199.app -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 188.8.131.52
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 184.108.40.206
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 220.127.116.11
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.