Upgrading the Application Code
Typically, customers want all the customizations that have been implemented in their existing Microsoft Dynamics NAV databases to be migrated to their new Microsoft Dynamics NAV 2015 databases. Depending on the version of Microsoft Dynamics NAV that a database is being upgraded from, the amount of code changes between the two versions is large or small. 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 identify which changes you have to make, you have to upgrade the application objects and the application code, and you might have to upgrade data so that it fits the new database schema. You can use any tool or set of tools to help you compare and merge code. For example, Microsoft Dynamics NAV includes Windows PowerShell cmdlets and sample scripts that can help you upgrade your application. For more information, see Comparing and Merging Application Object Source Files.
You must analyze and process code changes by comparing and evaluating three separate versions of the Microsoft 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 2013. |
Modified version |
This is the version that you want to upgrade, such as a customer's 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 2015 database. |
When you merge the application objects from these three versions, you can import the result into a new Microsoft Dynamics NAV 2015 database that then contains the upgraded application. At the end of the process, you export the merged Microsoft Dynamics NAV 2015 objects from this database to a .fob file that you will use during the data upgrade.
The following list describes the main steps of upgrading the application code:
Prepare the application object text files.
Merge versions.
Resolve conflicts
Import and compile the merged application objects.
Export all objects.
When you upgrade to Microsoft Dynamics NAV 2015, we recommend that you use the Windows PowerShell cmdlets and sample scripts that are included on the product media. During the code upgrade, Windows PowerShell cmdlets can make it faster to merge most changes. For example, you can combine several steps in a command that uses a cmdlet such Merge-NAVApplicationObject. The following section describes how you can use the Merge-NAVApplicationObject cmdlet and other Windows PowerShell cmdlets. For information about other ways of upgrading your code, see Upgrading the Application Code for Microsoft Dynamics NAV 2013 R2 in the MSDN Library.
To begin, create four folders on the computer and name them as follows:
ORIGINAL
This folder must contain the application objects from the baseline version, such as the original release of Microsoft Dynamics NAV 2013.
MODIFIED
This folder must contain the application objects from the modified version, such as the customer's database.
TARGET
This folder must contain the application objects from Microsoft Dynamics NAV 2015.
RESULT
This folder will contain the application objects that are the result of the application merge. It will also contain zero or more .CONFLICT files that describe conflicting code.
Preparing the Text Files
The Microsoft Dynamics NAV cmdlets take text files as input. You must prepare three sets of text files that contain application objects as describes in the list above. You can export application objects to text files from the development environment, or by running the ExportObjects command. The following list describes the main steps of preparing the text files that you must provide as input for the application merge process.
First, export all application objects from the original version, such as the original Microsoft Dynamics NAV 2013 database. Do not export system tables. Name the file OldBaseVersion.txt, and then save the file in the ORIGINAL folder that you created earlier.
For example, the Microsoft.Dynamics.Nav.Model.Tools.psd1 module includes a function, Export-NAVApplicationObject, that runs the ExportObjects command. This means that you can run a command such as the following:
Export-NAVApplicationObject –DatabaseServer MyServer –DatabaseName "Demo Database NAV (7-0)" –Path C:\Upgrade\ORIGINAL\OldBaseVersion.txtNext, export all relevant application objects from the modified version, such as the customized Microsoft Dynamics NAV 2013 database. Do not export system tables. Name the file OldCustomVersion.txt, and then save the file in the MODIFIED folder that you created earlier.
Tip
In some cases, existing customizations might be irrelevant after the upgrade because they correspond to new functionality in Microsoft Dynamics NAV 2015. For a description of new application functionality in Microsoft Dynamics NAV 2015, see What’s New: Application Changes for Microsoft Dynamics NAV.
Finally, export all application objects from the new base version, such as the original Microsoft Dynamics NAV 2015 database. Do not export system tables. Name the file NewBaseVersion.txt, and then save the file in the TARGET folder that you created earlier.
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.
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. For more information, see How to: Merge Application Changes.
Merging Versions
You must now merge the three sets of application objects to create the application for the new database.
The sample scripts on the Microsoft Dynamics NAV product media provide examples of how you can use the Merge-NAVApplicationObject cmdlet to merge the three sets of application objects. The following example illustrates the type of command that you can run.
Merge-NAVApplicationObject -OriginalPath .\ORIGINAL -TargetPath .\TARGET -ModifiedPath .\MODIFIED -ResultPath .\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. The RESULT folder will contain a text file for each application object. The result of the merge is shown when the cmdlet completes, including a description of any application objects with conflicting code. These conflicts are stored in .CONFLICT files in the RESULT folder. You can import all objects in the RESULT folder into the new Microsoft Dynamics NAV 2015 database, or you can analyze the conflicts before you import the objects.
Handling Conflicts
Depending on the application that you are upgrading, you can choose to analyze 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 RESULT folder. Subfolders 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. Alternatively, you can import the merged files into the development environment, and resolve the conflicts there. For more information, see Handling Merge Conflicts.
Importing and Compiling Merged Objects
After you have completed the merge, import the new custom version into the new Microsoft Dynamics NAV 2015 database, and then compile all objects. You must resolve any compilation errors before you can continue. The text files with the merged application objects include successfully merged code, and code that is partially merged. You can import the partially merged objects into the Microsoft Dynamics NAV 2015 development environment and resolve the conflicts there.
For example, the Microsoft.Dynamics.Nav.Model.Tools.psd1 module includes a function, Import-NAVApplicationObject, that runs the ImportObjects command. This means that you can run a command such as the following:
Join-NAVApplicationObject –Source C:\Upgrade\RESULT\*.txt -Destination C:\Upgrade\all-merged.txt
Import-NAVApplicationObject –DatabaseServer MyServer –DatabaseName "My Upgraded App" –Path C:\Upgrade\all-merged.txt
In this example, you first join the many text files into a single file, which you then import into an existing, empty database. 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.
You now have a new database with a fully upgraded application.
Exporting All Objects
Now, you must export all objects 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 2015 objects.
This completes the upgrade of the application code. Next, you must upgrade the data in the database. For more information, see Upgrading the Data.