Upgrading NAV Extensions
This topic provides information about you can upgrade existing extension after making changes.
Overview
Changes to a Microsoft Dynamics NAV deployment by an extension are treated differently than if you had manually added them to your code base. UI modifications are, in their simplest form, just the differences or deltas from the base application code. These are applied at runtime. On the other hand, because an extension package cannot modify existing code or add new code to existing objects., changes in business logic must be encapsulated through the use of events or in new codeunits (for more information, see Introducing Events).
You should not necessarily consider the upgrade of extensions as part upgrade process of the Microsoft Dynamics NAV deployment as a whole; unless, a product upgrade has an adverse effect on an extension. In this case, you will need to address the condition. You can upgrade your extension independently of the Microsoft Dynamics NAV deployment.
How to Upgrade an Extension
To upgrade an extension, you simply uninstall the old package and then install a new version of the package. The newer version takes care of the rest. You can do this by using the Uninstall-NAVAppand Install-NAVApp cmdlets.
When an extension package is uninstalled, all data for the extension is archived into a set of special tables, so while the extension is now removed from the system, the data is still preserved. This becomes important when you install an update because at that time, it invokes code designed to upgrade or restore any data from the old version.
When uninstalling the extension, you can choose to not archive the data from the extension. This is accomplished by use of the DoNotSaveData switch parameter. Similarly, when an extension package is installed, you can choose to not load any previous version archived data by use of the DoNotLoadData switch parameter. Regardless of the switch parameter, the upgrade code is called.
The following example illustrates how you can uninstall an extension and not archive its data.
Uninstall-NAVApp -ServerInstance YourDynamicsNAVServer -Path MyNAVExtension.navx -DoNotSaveData
Developing an Extension for Upgrading
When you develop an extension, you must write logic that actively upgrades or restores the extension when it installs. This code must be placed in specific functions in a codeunit in the package. As a developer of an extension, you must make sure that all scenarios for upgrades are included in your upgrade code, including the possibility that the exact same version of the extension is re-installed.
Your extension is upgraded if you implement global functions with the following names:
OnNavAppUpgradePerDatabase()Called only once in the installation process.
OnNavAppUpgradePerCompany()Called once for each company in the tenant currently being installed to.
Important
The codeunit cannot be an Upgrade codeunit type. You can use more than one codeunit to contain the upgrade functions. However, it is recommended that you use a single codeunit because this gives you more control over the execution order of the upgrade code. Within a single codeunit, the OnNavAppUpgradePerDatabase function is run before the OnNavAppUpgradePerCompany function.
There are several system functions that enable you access and manage archived data from the last version of the extension that was uninstalled. For more information about these functions, see NAV App.
For each new or modified table in your extension, you must use one of the following options in the appropriate upgrade global function for handling any archived data. A single extension may combine the approaches as long as all modified or added tables are handled.
Restore table data
Delete table data
Upgrade table data
You must include OnNavAppUpgradePerDatabase or OnNavAppUpgradePerCompany functions to your upgrade code. If these functions are not present at the time of creating the extension package and there are schema changes, the packaging will fail with an error. The installation of an extension package will also validate that all table changes are handled, and the following error occurs if they are not handled:
The package contains changes to the database schema that are not handled in upgrade code.
Note
An extension package that was created by using Microsoft Dynamics NAV 2016 prior to Cumulative Update 1 may have been successfully created without the handling of archive data. This package can be published successfully for Microsoft Dynamics NAV 2016, but it may fail on a re-install if there is archive data. You will need to use the –DoNotLoadData parameter or create a new version of the extension package with upgrade code in order to successfully re-install this extension.
For detailed instructions about how to write upgrade code, see How to: Write Extension Upgrade Code.
See Also
Tasks
How to: Develop an Extension
How to: Create an Extension Package