Upgrading Extensions

This topic provides information about how you can upgrade an existing extension after making changes.

Overview

Changes to a 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 of the upgrade process of the 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 by adding upgrade code to your extension. You can upgrade your extension independently of the 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-NAVApp and 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 for the Uninstall-NAVApp cmdlet. 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 on the Install-NAVApp cmdlet. Installing and uninstalling an extension from the Extension Management page in the client will always save and load the data. When using these switches to either not archive data or not load archived data, the archived data will not be restored for any tables no matter what functions where written for the individual tables. Any starting data for a table will be imported into the table however.

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 archived data when the extension is installed. 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.

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

• Load default or starting 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.

For detailed instructions about how to write upgrade code, see How to: Write Extension Upgrade Code.

See Also

Getting Started