9. July 2019
Delivering Application Symbols to enable hybrid deployments
If you are like us at Axians Infoma and can’t make the transition of your on-premises solution from C/AL to AL with a single snap of your fingers, you may want to use hybrid deployments as a first step. This means shipping your standard C/AL solution and publishing dependent extensions on top of that to enable a step-by-step migration to AL. If you have the opportunity for an immediate transition to AL you should definitely do that but if you’re struggling with some technical limitations of AL-only deployments or your solution is simply too big to make an immediate transition, hybrid deployments could be temporarily a valid option.
To publish dependent extensions you need the current application symbols available. Those symbols contain information about the objects in your database, e.g. all fields a page contains. This information is needed to develop and publish extensions if these extensions are referencing already existing objects. As an example, if you create a page extension you can specify the page you want to extend and to place your newly created field after an existing one with the information from these symbol references.
One obvious way to have the application symbols available for installing dependent extensions is to extend your update process to run the generatesymbolreference command of the finsql.exe for every customer database after deploying your C/AL objects. This command basically collects information about all objects inside your database to update the application symbols accordingly. Depending on the way you update your solution, running this command could happen automatically via scripts or manually. As our update process is fully automated and already contains steps like importing a FOB file with all updated objects via the finsql.exe or running XMLports to import data into application tables, we would just add an additional step to run the mentioned command.
As running this command for every customer database is tedious and time consuming (around 40 minutes for our solution) we looked for options to ship the one time generated symbols with our application to be able to automatically import them into every customer database as part of the mentioned update process. Here’s how it works:
After finishing the C/AL development you generate the symbols for your application with the already explained command or you continuously generate the symbols right away while development. This is only needed once for each release. Afterwards you increment the application version with the PowerShell Cmdlet of the Management Tools:
Set-NAVApplication -IncrementApplicationVersion -ServerInstance myinstance
The specified instance
myinstance is connected to an internal release database serving as the baseline for the upcoming release of your solution. To have a clean versioning of your solution and to be able to reference a specific version of your base application within your extensions you should increment this application version for each release. It can be set to any version string containing numbers and dots according to your internal conventions. For more information also have a look at the documentation of this cmdlet. To verify if the version was incremented you can use the following PowerShell cmdlet from the Management Tools:
Get-NavApplication -ServerInstance myinstance
We need this incremented application version later on.
The previously generated symbols with the incremented version can be downloaded from your release database now. You can do this by creating a new extension or using an existing extension and run the “Download symbols” command in VS Code and grab the *.app file from the .alpackages directory. Another option is to directly use the corresponding HTTP API to download the *.app file via your browser or from a script:
Microsoft_Application_14.0.xx.xx.app file can now ship with your solution. This means it belongs to other artifacts like the FOB file which may be available for your customers to download or it is used while updating customer databases on your own.
You need to extend your update process to replace the old application symbols with the new ones after importing your updated C/AL objects. This is achieved with the following two PowerShell cmdlets which are executed against an instance
mycustomer connected to your customer database:
Unpublish-NAVApp -ServerInstance mycustomer -Name Application
Publish-NAVApp -PackageType SymbolsOnly -ServerInstance mycustomer -Path C:\update\Microsoft_Application_14.0.xx.xx.app
The first one unpublishes any application symbols which may exist in the app catalog from previous releases. The second cmdlet then publishes the new symbols from the specified
*.app file into the database connected with the given customer instance. Both cmdlets are available within the Management Tools.
Now comes the crucial part. For extensions published later to use those new application symbols you need to set the application version in the customer database to the incremented version of the application symbols in four system tables. We identified this incremented version with
Get-NavApplication before and can now use the following SQL command for storing it inside the database:
DECLARE @newversion nvarchar(max) = '14.0.xx.xx'
UPDATE [$ndo$dbproperty] SET applicationversion = @newversion
UPDATE [$ndo$tenantproperty] SET applicationversion = @newversion
UPDATE [$ndo$tenantdatabaseversion] SET applicationversion = @newversion
UPDATE [$ndo$tenantdatabaseproperty] SET applicationversion = @newversion
This SQL command should be also included within your update process and could be executed for example via a script. The variable in the first line needs to be set to the incremented application version. It is then written to the database and used by Business Central.
Just to be sure you could run the following PowerShell Cmdlet to sync the database changes:
Sync-NAVTenant -ServerInstance mycustomer
and check if the application version was correctly updated via the cmdlet
Get-NAVApplication -ServerInstance mycustomer
Afterwards other extensions can be published as you would normally, e.g. via Publish-NAVApp. Those extensions should now be able to use the newly imported application symbols.
Please keep in mind that updating the application version like shown above could trigger the data upgrade process of already installed extensions. Normally this shouldn’t be a problem but make sure to test this sufficiently. Using this method is a bit more complex but it can save you a lot of time so feel free to try it out. Please note that this is nowhere documented officially but according to our tests and experience, this works well.