Upgrading the Application Code in Dynamics NAV

Article
10/17/2017

Applies to: Microsoft Dynamics NAV 2018. See Microsoft Dynamics NAV 2017 version.

Typically, customers want all the customizations that have been implemented in their existing Dynamics NAV databases to be migrated to their new Microsoft Dynamics NAV 2018 databases. Depending on the version of Dynamics NAV 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.

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 Dynamics NAV database:

Version	Description
Original version	This is the baseline version of the solution that you want to upgrade, such as the original release of Microsoft Dynamics NAV 2016 or Microsoft Dynamics NAV 2017.
Modified version	This is the version that you want to upgrade, such as a customer's Microsoft Dynamics NAV 2016 or Microsoft Dynamics NAV 2017 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 Microsoft Dynamics NAV 2018 database.

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

Different ways of upgrading application code

You can use any tool or set of tools to help you compare and merge code. Dynamics NAV includes Windows PowerShell cmdlets and sample scripts that can help you upgrade your application. The cmdlets are available through the Microsoft 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

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

Version	Tool/Component
Old Dynamics NAV version	Microsoft Dynamics NAV Development Environment or Dynamics NAV Development Shell This is not available in Microsoft Dynamics NAV 2013 and Microsoft Dynamics NAV 2013 R2
Microsoft Dynamics NAV 2018	Microsoft Dynamics NAV Server Microsoft Dynamics NAV Development Shell Microsoft Dynamics NAV Administration Shell Microsoft Dynamics NAV Development Environment

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 Microsoft 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 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 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

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 Microsoft Dynamics NAV 2016 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 Microsoft Dynamics NAV 2018.
- 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.
Export all application objects from the original version of the old database, such as the original Microsoft Dynamics NAV 2017 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 (10-0)" –Path C:\Upgrade\ORIGINAL\OldBaseVersion.txt -Filter 'Id=1..1999999999'
```
Export all application objects, except system tables, from the old modified version, such as the customer's customized Microsoft Dynamics NAV 2017 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 "MyCustomerNAV2017Database" –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 Microsoft Dynamics NAV 2018.
Export all application objects, except system tables, from the new base version, such as the original Microsoft Dynamics NAV 2018 database. Name the file NewBaseVersion.txt, and then save the file in the TARGET folder that you created earlier.

For example, using the Microsoft Dynamics NAV Development Shell for Microsoft Dynamics NAV 2018, run the following command:
```
Export-NAVApplicationObject –DatabaseServer MyServer –DatabaseName "Demo Database NAV (11-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 must 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. Additionally, the Dynamics NAV product media contains sample scripts provide examples of how you can use the Merge-NAVApplicationObject cmdlet to merge application objects. For more information, see How to: 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 How to: 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

Run the Microsoft Dynamics NAV Development Shell for Microsoft Dynamics NAV 2018 as an administrator.

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  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 Microsoft Dynamics NAV 2018 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 development environment. 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 Microsoft Dynamics NAV 2018 development environment, and resolve the conflicts there.

Note

We recommend that you use development environment to resolve conflicts because this will ensure that the proper code page (text encoding) is used for text strings like captions. If you use another tool, such as Notepad or Visual Studio Code, make sure that the proper text encoding is used.

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) 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 Microsoft Dynamics NAV 2018 development environment and resolve the conflicts there.

Create a new Microsoft Dynamics NAV 2018 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 How to: Create Databases.
Make sure the database includes a valid Microsoft Dynamics NAV 2018 license.

For more information, see How to: Upload the License File
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 Microsoft Dynamics NAV 2018 development environment.
  
  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 Microsoft 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  
```
Connect a Microsoft Dynamics NAV 2018 Server instance to the database.

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

For more information about how to do this using the Microsoft Dynamics NAV 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.
Compile all the newly imported objects. To save time, it is recommended that you choose to run schema synchronization later when compiling the objects.

You can use the development environment or finsql.exe. For more information, see Compiling Objects.

If you use the development environment, you will first have to set it to use the Microsoft Dynamics NAV Server instance that connects to the database. For more information, see How to: Change the Microsoft Dynamics NAV Server Instance or Database Information.

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.
If not already done, run schema synchronization. For more information, see How to: Synchronize the Tenant Database with the Application Database.

You now have a new database with a fully upgraded application.

Task 6: Export All Objects

Now, you must export all objects of the new database to an objects.fob file so that you can import them when performing the data upgrade. The export must include customized objects, upgraded reports, and all other Microsoft Dynamics NAV 2018 objects.

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

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

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

This completes the upgrade of the application code. Next, you must upgrade the data in the database. For more information, see Upgrading the Data.