ForNAV Add-in Version 2.0

This article explains how NAV works with the ForNAV add-in. With version 2.0 of ForNAV, we have changed the way that we version the add-in and this affects how NAV loads, deploys, and caches it.

The DLL File

A NAV add-in can consist of multiple files. In our case, we have built everything into a single DLL file. This decision was made to keep things as simple as possible. All released versions of the DLL have properties – the file name, file version, and assembly version – that help us identify the specific version.

The add-in folder and file are named according to the version number. For example:

With ForNAV Add-in Version 2.0+

Example Version: 2.0.0.1135
Add-in folder: ReportsForNAV_2_0_0_1135
File name: ForNav.Reports.2.0.0.1135.dll
File version: 2.0.0.1135
Assembly version: 2.0.0.1135

Before ForNAV Add-in Version 2.0

Example Version: 1.3.0.1053
Add-in folder: ReportsForNAV
File name: ForNav.Reports.dll
File version: 1.3.0.1053
Assembly version: 1.3.0.0

As you can see, with ForNAV version 2.0, the version number is now part of both the DLL file name and the add-in folder name. Another important difference is that each new build now has a unique assembly version number.

Loading the Add-in

When NAV looks for an add-in, it scans all the add-in folders, including subfolders, and looks for the first assembly that matches the assembly name and version number.

Before ForNAV version 2.0, all the DLL files had the same assembly version. This could cause the NAV service tier or client to load the wrong build of the assembly, if more than one was present in the add-in folder structure. With the new versioning, you are guaranteed to get the right version of the add-in. If it doesn’t exist, you will get an error, which is better than loading the wrong version!

Caching the Add-in

Starting with NAV 2015, the NAV service tier can automatically deploy add-ins from the server to the client. Each user will have a personal cache of add-ins from the server. The cache is maintained by the NAV client and server. When a client needs an add-in of a specific version, it first checks the cache. If it isn’t in the cache, it will update the cache with the add-in from the server. The server will send the specific add-in and all the other files in the folder where the add-in was found on the server. This is why the ForNAV installer creates a new folder for each version of the add-in.

Before ForNAV 2.0

Previously, the AL code had to remove the add-in from the cache if the DLL had the wrong file version. This was necessary because the NAV client thought it had the right version because the assembly version did not change when a new version was released.

Client Cache Folder

NAV keeps the cached files in the %TEMP%\Microsoft Dynamics NAV\Add-Ins folder. You can clear the cache by deleting this folder. The client will rebuild it when it uses add-ins that need to be cached.

Add-in Folders

You can find add-in folders on both the client and server side. The add-ins in these folders can be the same but they serve a different purpose.

Client Add-in Folder

The client add-in folder is typically located under C:\Program Files (x86)\Microsoft Dynamics NAV\[NAV VERSION]\RoleTailored Client\Add-ins. This folder is mostly used by C/SIDE. It is the first place the client looks for an add-in. If you are a developer, we recommend that you have the DLL in this folder because it will speed up compilation and help finsql.exe when it is used by the ForNAV Designer to compile objects. The caching of add-ins is not used for the add-ins found in the client add-in folder.

With NAV 2015 and later, you don’t need the add-in in the client add-in folder if you are just a regular user. It will be transferred from the NAV service tier and cached automatically when needed.

Users of NAV 2013 must have the add-in installed in the client add-in folder. To ease the deployment in a corporate environment, you can get an MSI file with the add-in from ForNAV support.

NAV Server Add-in Folder

For the NAV server add-in folder, the default location is C:\Program Files\Microsoft Dynamics NAV\[NAV VERSION]\Service\Add-ins. From here, the NAV service tier searches the subfolders for an add-in with the right assembly number.

How it works with ForNAV 2.0 – Side-by-Side Installation

The new way of versioning the DLL, starting with ForNAV 2.0, has both pros and cons. We believe that the advantages clearly outweigh the disadvantages.

Advantages of the new versioning:

  • There are no more version conflicts – the NAV service tier has always had problems loading the right version into the client cache and keeping track of the functions and properties available in different versions of the same DLL. NAV now sees every new version of the ForNAV add-in as a different assembly, so you always get the right version.
  • Side-by-side installations are now possible – this means that you can have different reports running on different versions of the add-in at the same time. In the past, you had to upgrade all your reports to run on the latest ForNAV add-in version installed on the NAV service tier. Now, you can choose to upgrade specific reports to a newer version. This offers greater flexibility when fixing problems with specific reports.
  • You don’t need to restart the NAV service tier – when you install a new version of the ForNAV add-in, since all the files are new, they are not loaded and locked by the NAV service tier.

Changing the add-in references

The most significant benefit of the previous versioning was that the assembly and the assembly version was the same with each build. This meant that all the references to the add-in in the ForNAV C/AL variables never had to change. Now, you must change the add-in references to make the reports run on the new versions. You can do this by either opening the report in the ForNAV Designer and saving it with the new ForNAV version number, or by reconverting the report.

Reconversion

When you want your reports to use a new version of the add-in, you simply reconvert the report objects using the ForNAV Converter. You only have to do this with the reports you want to run on the new version. If you have reports that run as they should on previous versions, you can keep them there. This is the benefit of the side-by-side installation.

To reconvert the report objects for the ForNAV Converter:

  1. Select the reports in the Object Designer (C/SIDE) and export them to a text file. You can use the version list to set a filter that matches the reports for the export.
  2. Run this text file through the ForNAV Converter and select the version of the add-in that you want to target.

After conversion, you can import and compile your report objects. Now they are ready to run on the new version of the add-in.

The reconversion will preserve your report layout and C/AL code.

Conclusion

Overall, the new way of versioning the DLL files improves stability and ease of deployment. Previous DLL problems caused by NAV service tier shortcomings are eliminated. These benefits outweigh the disadvantage of an occasional reconversion of report objects.