Upgrading the Application Code in Dynamics 365 Business Central

Note

• If you're coming from version 13 or earlier, Business Central Spring 2019 (v14) is a required step to upgrade to the latest version of Business Central. However, mainstream support for version 14 ends in October 2023, and minor updates to the version are no longer available. New customers can't use version 14 in production, but only as a path for upgrading to latest version. Existing customers on version 14 remain supported by Microsoft as defined in the Fixed Lifecycle Policy.

• All version 14 updates are compatible with any update version of Business Central 2024 release wave 1 and later release waves.

Typically, customers want all the customizations that have been implemented in their existing databases to be migrated to their new Business Central databases. Depending on the version of Business Central that a database is being upgraded from, the amount of code changes between the two versions can vary. To upgrade the application code, you must merge code from different versions of the application. This merge process is known as a code upgrade or application upgrade. You must upgrade the application before you upgrade the data.

Important

Before you begin, read the article Important Information and Considerations for Before Upgrading. This article contains information about limitations and things that might require you to perform extra tasks before you upgrade, such as the use of extensions V1 and the deprecation of codeunit 1.

Application Upgrade Overview

During an upgrade, you have to first identify which changes you have to make, and then you'll have to upgrade the application objects and the application code, and finally, you might have to upgrade data so that it fits the new database schema.

For the application portion of the upgrade, you must analyze and process code changes by comparing and merging three separate versions of the database:

Version	Description
Original version	This is the baseline version of the solution that you want to upgrade, such as the original release of Business Central October 2018 or Microsoft Dynamics NAV 2018.
Modified version	This is the version that you want to upgrade, such as a customer's Business Central October 2018 or Microsoft Dynamics NAV 2018 database with customizations and add-on solutions.
Target version	This is the target of the merge process that you want to upgrade your application to, such as the standard version of the Business Central database.

When you merge the application objects from these three versions, you can import the result into a new Business Central database that then contains the upgraded application. At the end of the process, you export the merged Business Central objects from this database to a .fob file that you will use during the data upgrade.

Single-tenant and multitenant deployments

The process for upgrading the application code is basically the same for a single-tenant and multitenant deployment. However, there are some inherent differences because with a single-tenant deployment, the application and business data is included in the same database, while with a multitenant deployment application code is in a separate database than the business data (tenants). Here is the general process for each deployment type. In the tasks that follow this section, tasks are marked as Single-tenant only or Multitenant only where applicable.

Single-tenant

1. Upgrade the application code.
2. Create a new database on the new platform.
3. Import the upgraded application to the new database.
4. Export the application to a .fob file.
5. Upgrade the data. Here you will import the .fob file.

Multitenant

1. Upgrade the application code.
2. Create a new database on the new platform.
3. Import the upgraded application to the new database.
4. Upgrade the data by mounting the tenant on the application database.

With a multitenant deployment, you will perform the steps in this article on the application database, that is, the database that contains the application object definitions.

Different ways of upgrading application code

You can use any tool or set of tools to help you compare and merge code. Dynamics NAV and Business Central include Windows PowerShell cmdlets and sample scripts that can help you upgrade your application. The cmdlets are available through the Microsoft Dynamics NAV Development Shell and Dynamics NAV Development Shell, or by importing the Microsoft.Dynamics.NAV.Model.Tools.psd1 module into the Windows PowerShell Integrated Scripting Environment (ISE). You can find the sample scripts on the product installation media, in the WindowsPowerShellScripts\ApplicationMergeUtilities folder. We recommend that you use these cmdlets and sample scripts because they can make it faster to merge most changes. For example, you can combine several steps in a command that uses a cmdlet such as the Merge-NAVApplicationObject. The sections in this article describe how you can use the Merge-NAVApplicationObject cmdlet and other Windows PowerShell cmdlets. For more information, see Comparing and Merging Application Object Source Files.

Task 1: Install the Prerequisites and Tools

To complete the tasks in this article, you will use various tools and components of the old Dynamics NAV version and Business Central. Ensure that you have the following installed:

Dynamics NAV to Business Central upgrade

Product	Tool/Component
Old Dynamics NAV version	Dynamics NAV Development Environment Dynamics NAV Development Shell
Business Central	Business Central Server Dynamics NAV Development Shell(DISCONTINUED AFTER: Business Central Spring 2019) Business Central Administration Shell Dynamics NAV Development Environment (DISCONTINUED AFTER: Business Central Spring 2019)

Business Central to Business Central upgrade

Product	Tool/Component
Old Business Central version	Dynamics NAV Development Environment Dynamics NAV Development Shell
New Business Central version	Business Central Server Dynamics NAV Development Shell(DISCONTINUED AFTER: Business Central Spring 2019) Business Central Administration Shell Dynamics NAV Development Environment(DISCONTINUED AFTER: Business Central Spring 2019)

Task 2: Prepare the Application Object Text Files

You must prepare text files that contain the application objects for the different application versions previously described (original, modified, and target). The text files provide the input for the application merge process.

There are three ways to export application objects to text files:

• Use the Dynamics NAV Development Environment version that matches the application database version.

  For more information see To export objects by using the development environment UI.

• Use the finsql.exe that matches the application database version to run the ExportObjects command.

  For more information, see To export objects by running finsql.exe with the ExportObjects command .

• Use the Microsoft Dynamics NAV Development Shell or Dynamics NAV Development Shell version that matches the application database version.

  This is the way that is described in the tasks of this article. Note that the Microsoft Dynamics NAV Development Shell is not available for Microsoft Dynamics NAV 2013 and Microsoft Dynamics NAV 2013 R2. For these versions, you must use development environment or finsql.exe.

Create the application text files

Note

Be sure to upload a valid developer license to the database before doing the following steps.

1. Create four folders on the computer, and name them as follows:

   • ORIGINAL

     This folder will be used to store the application object text file(s) from the baseline version, such as the original release of Business Central October 2018, Microsoft Dynamics NAV 2018, or Microsoft Dynamics NAV 2017.

   • MODIFIED

     This folder will be used to store the application object text file(s) from the modified version, such as the customer's database.

   • TARGET

     This folder will be used to store the application object text file(s) from the latest Business Central version.

   • RESULT

     This folder will be used to store the application object text file(s) that are the result of the application merge. It will also contain zero or more .CONFLICT files that describe conflicting code.

2. Export all application objects except system tables from the original version of the old application database, such as the original Microsoft Dynamics NAV 2018 database.

   Do not export system tables, which have the IDs in the 2000000000 range. Name the file OldBaseVersion.txt, and then save the file in the ORIGINAL folder that you created earlier.

   For example, start the Microsoft Dynamics NAV Development Shell version that matches the database version, and run the Export-NAVApplicationObject function as follows:

   Export-NAVApplicationObject –DatabaseServer MyServer –DatabaseName "Demo Database NAV (11-0)" –Path C:\Upgrade\ORIGINAL\OldBaseVersion.txt -Filter 'Id=1..1999999999'
   

3. Export all application objects, except system tables, from the old modified application database, such as the customer's customized Microsoft Dynamics NAV 2018 database.

   Name the file OldCustomVersion.txt, and then save the file in the MODIFIED folder that you created earlier.

   For example (using the Microsoft Dynamics NAV Development Shell version that matches the database version), if the customer's database is called MyCustomerNAV2016Database, you can run the following command:

   Export-NAVApplicationObject –DatabaseServer MyServer –DatabaseName "MyCustomerNAV2018Database" –Path C:\Upgrade\MODIFIED\OldCUSTOMVersion.txt -Filter 'Id=1..1999999999'
   

   Tip

   In some cases, existing customizations might be irrelevant after the upgrade because they correspond to new functionality in Business Central.

4. Export all application objects, except system tables, from the new base version, such as the original Business Central database.

   Name the file NewBaseVersion.txt, and then save the file in the TARGET folder that you created earlier.

   For example, using the Dynamics NAV Development Shell for Business Central, run the following command:

   Export-NAVApplicationObject –DatabaseServer MyServer –DatabaseName "Demo Database BC (14-0)" –Path C:\Upgrade\Target\NewBaseVersion.txt -Filter 'Id=1..1999999999'
   

Optionally, you can use the Split-NAVApplicationObjectFile cmdlet to split each text file into separate text files for each application object. This can make it easier to keep track of the process. The end result at this stage is three folders with one or more text files that contain the three sets of application objects that you want to merge.

Task 3: Merge Versions

You now merge the three sets of application objects to create the application for the new database. This section illustrates how to do this by using the Merge-NAVApplicationObject cmdlet.

The product installation media contains sample scripts that provide examples of how you can use the Merge-NAVApplicationObject cmdlet to merge application objects. For more information, see Merge Application Changes.

Note

In certain scenarios, you can choose to use the Compare-NAVApplicationObject cmdlet to identify the changes between the existing customized application and the new application. You can then choose to use the Update-NAVApplicationObject cmdlet to apply all or some of the changes to the new version. For more information, see Compare and Update Application Object Source Files. However, we recommend that you use the Merge-NAVApplicationObject cmdlet in most cases.

Merge the application object versions into text files

1. Run the new Dynamics NAV Development Shell as an administrator.

2. At the command prompt, change to the directory that contains the four folders that contain the application text files, and then run the following command:

   Merge-NAVApplicationObject -OriginalPath ORIGINAL -TargetPath TARGET -ModifiedPath MODIFIED -ResultPath RESULT  
   

   For example:

   Merge-NAVApplicationObject -OriginalPath C:\Upgrade\ORIGINAL -TargetPath C:\Upgrade\TARGET -ModifiedPath C:\Upgrade\MODIFIED -ResultPath C:\Upgrade\RESULT  
   

Depending on the number of objects that you are merging and the number of differences found, this can take a few seconds, a few minutes, or longer. When the cmdlet completes, the result of the merge is shown, including a description of any application objects with conflicting code. The RESULT folder will contain a text file (.TXT) for each merged application object and possibly one or more .CONFLICT files that describe the code conflicts that occurred during the merge.

At this point, you can either go to Task 4 to analyze and eventually resolve the conflicts, or you can go directly to Task 5 to import the merged objects as-is from the RESULT folder to the new Business Central database.

Task 4: Handling Conflicts

Depending on the application that you are upgrading, you can choose to analyze and fix the conflicting code before you import the merged objects into the Dynamics NAV Development Environment for Business Central. The conflicts are shown in the merged text files but are also identified in .CONFLICT files in the subfolders of the RESULT folder. The subfolders ConflictOriginal, ConflictModified, and ConflictTarget folders then contain copies of the source files from the versions that have conflicting code.

You can analyze the conflicts in any tool, make the relevant changes, and then run the merge operation again. For more information, see Handling Merge Conflicts. Alternatively, you can go directly to task 5 to import the merged files into the Dynamics NAV Development Environment, and resolve the conflicts there.

Task 5: Import and Compile Merged Objects in an Empty Database

After you have completed the merge, you import the new merged application objects as text files into a new (empty) Business Central database, and then compile all objects. You must resolve any compilation errors before you can continue. The text files include successfully merged code, and code that is partially merged. You can import the partially merged objects into the Business Central development environment and resolve the conflicts there.

1. Create a new Business Central database for the new upgraded application. The database should be empty, except for the system tables.

   For example, give the database the name My Upgraded App. For more information, see Creating and Altering Databases.

   Important

   You must set the collation of the new database to match the collation of the old application database. To see the collation of the old database, open it in the old Dynamics NAV Development Environment version, then choose File > Database > Alter > Collation.

2. Make sure the database includes a valid Business Central license.

   For more information, see Uploading a License File for a Specific Database

3. Import the new merged application object text files (.TXT) from the Result folder into the new database.

   There are three ways to import the files:

   • Use the Dynamics NAV Development Environment for Business Central.

     For more information see To import objects by using the development environment UI.

   • Use the finsql.exe to run the ImportObjects command.

     For more information, see To import objects by running finsql.exe with the ImportObjects command .

   • Use the Dynamics NAV Development Shell (or Microsoft.Dynamics.NAV.Model.Tools.psd1 module).

     The shell includes the Join-NAVApplicationObjectFile cmdlet and Import-NAVApplicationObject function. The Join-NAVApplicationObjectFile cmdlet combines multiple application object text files into one text file. The Import-NAVApplicationObject function runs the ImportObjects command to import an object file.

     This means that you can run a command similar to following to create a single text file from the merge application text files in the Result folder:

     Join-NAVApplicationObjectFile –Source C:\Upgrade\RESULT\*.txt -Destination C:\Upgrade\all-merged.txt
     

     Then, you can run this command to import the text file:

     Import-NAVApplicationObject –DatabaseServer MyServer –DatabaseName "My Upgraded App" –Path C:\Upgrade\all-merged.txt  
     

4. Connect the new Business Central Server instance to the database.

   You can do this with the Business Central Server Administration tool or the Set-NAVServerConfiguration cmdlet in the Dynamics NAV Administration Shell. In addition, you must add the service account that is used by the Business Central Server instance as a member of the db_owner role in the Business Central database on SQL Server.

   For more information about how to do this using the Business Central Server Administration tool, see How to: Connect a Microsoft Dynamics NAV Server Instance to a Database and Giving the account necessary database privileges in SQL Server.

5. Compile all the newly imported objects. Choose to synchronize later.

   You can use the Dynamics NAV Development Environment or finsql.exe. For more information, see Compiling Objects.

   If you use the Dynamics NAV Development Environment, you will first have to set it to use the Business Central Server instance that connects to the database. For more information, see Change the Server Instance Used in C/SIDE.

   When you compile the objects, an error is thrown for each code conflict, and you can use the tools that are available in the development environment to resolve the conflicts.

Task 6: Check/change the application family and version

The application and tenant databases are tagged with Family and Version. To perform the data upgrade, the Family on the application must match that tenant's Family. The Version of the application must be greater than or equal to the tenant's Version. The easiest way to ensure that Family and Version of the upgraded application are compatible for data upgrade is to set Family to the same value as the old application, and set the Version to a higher value than the old application.

To get the Family and Version, use the Get-NAVApplication cmdlet, for example:

Get-NAVApplication -ServerInstance BC

To set the Family and Version, use the Set-NAVApplication cmdlet. For example, to set the family, run the following command:

Set-NAVApplication -ServerInstance <ServerInstanceName> -ApplicationFamily <Family> 

To increase the version by 1, run the following command:

Set-NAVApplication -ServerInstance <ServerInstanceName> -IncrementApplicationVersion

Or, to specify change to another version, run the following command:

Set-NAVApplication -ServerInstance <ServerInstanceName> -ApplicationVersion <N.N.N.N> -Force

Task 7: (Dynamics NAV upgrade only) Configure pages and reports to be searchable

The MenuSuite is no longer used to control whether a page or report can be found in the search feature of the Web client. This is now determined by specific properties on the page and report objects. This task is not required at this point, and can be done after the data upgrade as well.

For more information, see Making Pages and Reports Searchable After an Upgrade.

Task 8: Build object search index

Build the object search index to make objects able to be searched from Tell Me in the client. If you completed step 7, you can skip this step.

In the Tools menu of the Dynamics NAV Development Environment, select Build Object Search Index.

For more information, see Making Pages and Reports Searchable After an Upgrade.

Task 9. (Dynamics NAV upgrade only) Transition the custom code from old codeunit 1 to use the new implementation

Because codeunit 1 has been deprecated in Business Central, you must move any custom logic that was included in the old codeunit 1 into the management codeunits and methods described in the article Transitioning from Codeunit 1.

You now have a new database with a fully upgraded application. For a multitenant deployment, you can start the data upgrade. For this, you will use the new server instance that connects to the upgraded application database. See Upgrading the Data.

Task 10: (Single-tenant mode only) Export all objects

With a single-tenant deployment, export all objects of the new database to a .fob type file, such as objects.fob file. You will use this .fob file as part of the data upgrade process. The export must include customized objects, upgraded reports, and all other Business Central objects.

As with exporting objects in Task 1, you can use either the development environment, finsql.exe, or Dynamics NAV Development Shell.

With the Dynamics NAV Development Shell, you can run a command that is similar to the following:

Export-NAVApplicationObject c:\Upgrade\objects.fob -DatabaseName "My Upgraded App" -DatabaseServer [server_name]\[database_instance]

This completes the upgrade of the application code for single-tenant deployment. Next, you must upgrade the data in the database. See Upgrading the Data.

Task 11: (Multitenant mode only) Import the upgrade toolkit objects

The upgrade toolkit includes upgrade codeunits for handling the data upgrade.

For W1 versions, you can find the default upgrade toolkit objects in the UpgradeToolKit\Data Conversion Tools folder on the Business Central installation media (DVD). Choose the FOB that matches the Dynamics NAV version from which you are upgrading:

From	To Business Central April 2019	To Business Central October 2018
Microsoft Dynamics NAV 2015	Upgrade80014x.FOB	Upgrade800130.FOB
Microsoft Dynamics NAV 2016	Upgrade90014x.FOB	Upgrade900130.FOB
Microsoft Dynamics NAV 2017	Upgrade100014x.FOB	Upgrade1000130.FOB
Microsoft Dynamics NAV 2018	Upgrade110014x.FOB	Upgrade1100130.FOB
Business Central Fall 2018	Upgrade13x14x.FOB	Not applicable

For local versions, you will find the upgrade toolkit objects in the UpgradeToolKit\Local Objects folder. The files follow the same naming convention except they include the 2-letter local version, such as Upgrade110014x.DK.fob for Denmark, Upgrade110014x.DE.fob for Germany, or Upgrade90014x.IN.fob for India.

For information about importing objects, see Importing Objects.

Task 12: (Multitenant mode only) Publish extensions

1. Unpublish the existing system, test, and application symbols by using the Unpublish-NAVAPP cmdlet:

   Unpublish-NAVApp -ServerInstance <ServerInstanceName> -Name <name> -Version <n.n.n.n>
   

2. Publish the system and test symbols.

   Symbols are a prerequisite for extensions. If you installed the AL Development Environment, you can find the symbol files where your installed the environment, which by default is C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\NNN. Otherwise, you can find the files in the ModernDev folder on the installation media.

   To publish the symbols, open the Business Central Administration Shell as an administrator, and run the following command for each of the symbol files:

   Publish-NAVApp -ServerInstance <ServerInstanceName> -Path <SymbolFilePath> -PackageType SymbolsOnly
   

3. Generate the application symbol references by using the finsql.exe file as follows:

   1. Make sure that Enable loading application symbol references at server startup (EnableSymbolLoadingAtServerStartup) is set on the Business Central Server instance.

      For more information, see Configuring Dynamics NAV Server.

   2. Open a command prompt as an administrator, change to the directory where the finsql.exe file has been installed as part of Dynamics NAV Development Environment, and then run the following command:

      finsql.exe Command=generatesymbolreference, Database="<MyDatabaseName>", ServerName=<DatabaseServerName>\<DatabaseInstance>
      

      Replace values for the Database and ServerName settings to suit.

      If the application database contains test objects (ID 130000-139999), then make sure to exclude these objects when generating symbols. You can do this by using the -Filter parameter and running the command twice:

      finsql.exe command=generatesymbolreference, ServerName=<DatabaseServerName>\<DatabaseInstance>, Database=<MyDatabaseName>, filter="Object ID=1..129999"
      

      finsql.exe command=generatesymbolreference, ServerName=<DatabaseServerName>\<DatabaseInstance>, Database=<MyDatabaseName>, filter="Object ID=140000..1999999999"
      

      Note

      This command does not generate a file. It populates the Object Metadata table in the database.

   3. When you run the command, the console returns to an empty command prompt, and does not display or provide any indication about the status of the run. However, the finsql.exe may still be running in the background. It can take several minutes for the run to complete, and the symbols will not be generated until such time. You can see whether the finsql.exe is still running by using Task Manager and looking on the Details tab for finsql.exe.

      When the process ends, a file named navcommandresult.txt is saved to the Dynamics NAV Client connected to Business Central installation folder. If the command succeeded, the file will contain text like [0] [06/12/17 14:36:17] The command completed successfully in '177' seconds. If the command failed, another file named naverrorlog.txt will be generated. This file contains details about the error(s) that occurred.

   For more information about generation symbols, see Running C/SIDE and AL Side-by-Side.

4. Publish new versions of the Microsoft extensions.

   The Business Central installation media (DVD) includes several new versions of Microsoft extensions (that is, extensions that have Microsoft as the publisher). If your old deployment uses these extensions, you have to upgrade the old versions to the new versions.

   Important

   For Denmark (DK), German (DE), and India (IN) versions. Some of the local functionality has been moved from the base application to extensions.

   If you are upgrading from a Denmark (DK) version of Dynamics NAV 2017 or earlier, you must publish and install the following extensions to get the local functionality:

   Name	Extension package
   OIOUBL	OIOUBL.app
   Payroll Data Import Definitions (DK)	ImportDKPayroll.app
   Payment and Reconciliation Formats (DK)	FIK.app
   Tax File Formats (DK)	VATReportsDK.app

   If you are upgrading from a German (DE) version of Dynamics NAV or Business Central October 2018 (Cumulative Update 2 or earlier), you must publish and install the following extensions to get the local functionality:

   Name	Extension package
   ELSTER VAT Localization for Germany	Elster.app

   If you are upgrading from an India (IN) version of Dynamics NAV 2016, you must publish and install the following extensions to get the local functionality:

   Name	Extension package
   India Tax Base	IndiaTaxBase.app
   India Tax Engine	IndiaTaxEngine.app
   India Tax GST	IndiaTaxGST.app
   India Upgrade Tables	IndiaUpgradeTables.app
   India TCS	IndiaUPGTCS.app
   India TDS	IndiaUPGTDS.app
   Fixed Asset Depreciation for India	INFADepreciation.app
   India Gate Entry	INGateEntry.app
   India Voucher Interface	INVoucherInterface.app
   India Data Migration	UPGIndia.app

   The new versions are found in the \Extensions folder of the installation media.

   To publish the new extension version, run the Publish-NAVApp cmdlet:

   Publish-NAVApp -ServerInstance <ServerInstanceName> -Path <ExtensionFileName> 
   

See Also

Upgrading the Data
Upgrading to Business Central