How To Use Install And Upgrade CodeUnits In Business Central

In Business Central, Install and Upgrade codeunits are important in managing the installation and upgrade processes of extensions. Install codeunits handle installation tasks, while Upgrade codeunits manage upgrades to newer versions. This blog post explores the purpose, usage, and benefits of these codeunits, as well as provides insights on how to use them effectively.

• What Are Install And Upgrade CodeUnits?
• What Are They Used For?
• How To Use Install CodeUnits
  • AppInfo
• How To Use Upgrade CodeUnits
  • Upgrade Tags
    

What Are Install And Upgrade CodeUnits?

Install or Upgrade codeunits are codeunits in which their Subtype property has been set to ‘Install‘ or ‘Upgrade‘.

They work in a very specific way:

An Install codeunit executes when an application is installed for the first time. Or when an uninstalled app is installed again.

Unlike the other, an Upgrade codeunit only runs when a greater version of an already installed app is installed.

What Are They Used For?

The general purpose of these codeunits is to help with initialization data some apps might require. Or when specific data management needs to be done for a newer version to work correctly. For example, for data migration between tables, when an old table is obsolete and we want to migrate it to the new one.

How To Use Install CodeUnits

This is when things get interesting. For Install codeunits there are two triggers available that trigger in the following order:

• OnInstallAppPerCompany
• OnInstallAppPerDatabase

The first trigger will loop through every company in the database. The second will run only once for the installation process, without accessing any company data.

Let’s start with OInstallAppPerCompany. Here you can insert data into the database. In this example, we want to insert item 50000 for every company.

As you can see, when you install the app, item 50000 will be inserted in every company.

If we use the very same code for the OnInstallAppPerDatabase trigger an error like the following will appear:

We can’t access company data with it. So, what’s its purpose?

In the Microsoft documentation, you can see how to check if an extension is installed for the first time or has been installed before. So if you use it for initialization data, for instance, you can check it to avoid doing the process again if the app is reinstalled.

This is done with the help of the NavApp data type. There are several methods in NavApp, I suggest having a look at them because they are quite handy.

With ‘Version.Create’ we can compare the version installed.

You can also access common tables. Tables with the property ‘DataPerCompany’ set to false. They don’t belong to any specific company so we can use them for initialization data.

In this example, ‘MyCommonTable’ is a table with ‘DataPerCompany’ = false.

Keep in mind that installing the same version from VS Code will trigger the codeunit logic, both triggers included, This won’t happen if you install it from the ‘Extension Management’ page. As we mentioned above, it will only run for the first time the app is installed. Or if it was uninstalled at some point, a reinstall will also trigger the codeunit.

You can find more information in the Microsoft documentation.

Writing extensions installation code – Business Central | Microsoft Learn

How To Use Upgrade CodeUnits

Upgrade codeunits often relate to existing data. Meaning that they are used to manage data already in Business Central. For example, we can use these codeunits to set the default values of a new field in an existing table.

Also, you can do version compatibility checks as it can identify any conflicts or potential issues that may arise due to changes in functionality or dependencies.

It comes with 6 triggers:

We will focus on ‘OnUpgradePerCompany‘ and ‘OnUpgradePerDatabase‘ which are the ones that carry the upgrade process.

The others are for checking purposes. For example, we can check if the actual version is compatible with the new 1.0.0.1 just released with ‘OnCheckPreconditionsPerDatabase‘. If not, we can throw an error and stop the upgrade process.

Now, let’s see an example on how you can use it to upgrade existing data. This piece of code will take the data from an obsolete field to a new field when upgrading.

This is nice but, what happens when we upgrade again? We don’t want to run this process every time we upgrade and overwrite existing data. This is when Upgrade Tags come in.

They are basically a mark defining that this upgrade process has been run before. So it’s not run again.

First, you can see how we check if the tag has been set before and exit if it’s found. If not, the upgrade process continues and set the upgrade tag when finished. The concept is quite simple. The tag is just a code that you should define with a certain criteria so you don’t repeat a tag.

Also, we don’t want to run the process for newer companies. So an event like this should be created:

For testing purposes, a very handy trick is to use the property ‘forceUpgrade‘ in your launch.json to run the codeunit without increasing the version number. Yun explains it in detail in this blog post.

Dynamics 365 Business Central: How to easily test your upgrade codeunit (forceUpgrade setting in launch.json) | Dynamics 365 Lab (yzhums.com)

Also, you can learn to debug these codeunits in the following link.

Dynamics 365 Business Central: Debugging Upgrade and Install code in Visual Studio Code | Dynamics 365 Lab (yzhums.com)

Find more information about upgrade codeunits in the following link.

Upgrading Extensions – Business Central | Microsoft Learn

CONCLUSION

Both install and upgrade subtype codeunits are essential for managing the lifecycle of extensions in Business Central. They ensure a smooth installation and upgrade process, allowing extensions to adapt to changes in the system or take advantage of new features and functionalities.

If you are interested in learning about Postman and how to use it to connect with Business Central APIs follow the article below:

That´s all. Hope you find it helpful.