Comparing and merging application object source files

When you create or modify application objects, you use the Dynamics NAV Development Environment, and you import and export objects as .fob files. But you can also export objects as text files and use other tools, such as the Dynamics NAV Development Shell, to make general changes to the objects. For example, you can use Windows PowerShell cmdlets to merge changes from an upgrade with your Business Central solution.

You can export all application objects to a single text file. Optionally, you can split the large text file into separate text files for each application object. You can also use an external source control system to store the text files, such as Visual Studio Team Foundation Server, but this isn't required by the Business Central cmdlets.

The application merges utilities that are available in the Dynamics NAV Development Shell install when you choose the Developer option in Business Central Setup, or if you add the development environment to another installation option.

Comparing and merging application objects

Business Central includes Windows PowerShell cmdlets that help you apply changes to Business Central solutions. You can use Business Central cmdlets to modify application object source files in the Dynamics NAV Development Shell, or by importing the Microsoft.Dynamics.NAV.Model.Tools.psd1 module into the Windows PowerShell Integrated Scripting Environment (ISE).

When Microsoft releases a new version of Business Central, you want to upgrade your solution. Similarly, you want to update your solution with cumulative updates and other smaller changes to the application. Each time you want to update your solution, you have to compare the original version to the new version, and then you have to apply the difference to your own solution. Or you compare the new version to your own solution and merge the changes into your solution. In both cases, you compare different versions of application objects to calculate and apply the difference. The Merge-NAVApplicationObject cmdlet compares the changes that have been made to application objects between two sets of Business Central application objects, and applies the difference to a third set of application objects, the target of the merge. The result of the application object merge is a fourth set of application objects that make up your new, updated solution.

In the Dynamics NAV Development Shell, you can also use other Windows PowerShell cmdlets that help you with manage application object files. But the recommended way to update your application is to use the Merge-NAVApplicationObject cmdlet. The other option is a two-step process using the Compare-NAVApplicationObject and Update-NAVApplicationObject cmdlets.

You can use the application merge utilities to merge and update the following application object types:

• Tables

• Pages

• Reports

• Codeunits

• MenuSuites

• Queries

• XMLPorts

You can't use the cmdlets to modify dataports, forms, or reports with classic report sections. Also, some parts of some object types require special attention from the tool or from you as described in the following list:

• Application object properties

  Each of the application object properties in the application object files often calls for hands-on handling. The text files specify the Modified, Date, Time, and VersionList properties for each object. When you run the Merge-NAVApplicationObject cmdlet, you can set parameters that are specific for application object properties. But two cmdlets are available specifically for post-processing of object properties: Get-NAVApplicationObjectProperty and Set-NAVApplicationObjectProperty.

  Often handling or setting application object properties is done at a later time than the merge itself. For example, you run the merge, resolve the conflicts, and once you're done, you want to stamp the current date and time on all objects. To do that, use the Set-NAVApplicationObjectProperty cmdlet to change the values of the Version List, Date, Time, or Modified properties in the specified text files. You can use the Set-NAVApplicationObjectProperty cmdlet to extract information about the application objects before you change them.

• Documentation triggers

  In each object, the documentation trigger is used for many different purposes. Documentation, of course, but also for tracking changes with date or history semantics built into it. You can use the cmdlets to modify the contents of the documentation section. If you want to be explicit about how the content of the documentation triggers is merged, you can set the -DocumentationConflict parameter when you run the Merge-NAVApplicationObject cmdlet. Set this parameter when you're merging objects with the same type of content in the documentation trigger, such as technical descriptions or a version list. By default, conflicting lines of documentation are merged into the result file with the content from the modified object listed first. This is particularly useful when the objects contain version history in the documentation triggers.

• ControlID

  Sometimes, developers in-house or external partners create objects in the same ID range as you. This surfaces in the merge process as conflicts and hence as work to do. The application merge utilities provide ways to handle that, depending on your needs and requirements. To reduce noise, by default the Merge-NAVApplicationObject cmdlet suppresses conflicting modifications on non-functional incidents such as the ordering of variables and methods that are sometimes referred to as control IDs. If you set the*–Strict* parameter, these occurrences are treated like any other conflicts and reported accordingly. Significant IDs, such as table and field IDs, are fully considered during compare and merge.

• CaptionML

  Captions are an integral part of the solution, but when you compare two versions of the same object with two different languages, you'll see extensive differences. You can choose to export captions into text files before you compare or merge application objects. For example, you can use the Export-NAVApplicationObjectLanguageWindows PowerShell cmdlet to export specific languages from the objects before you merge them. You can then use the Import-NAVApplicationObjectLanguage cmdlet to import the captions after the merge. Other Windows PowerShell cmdlets support joining and splitting application object language files.

When you merge application changes by running the Merge-NAVApplicationObject cmdlet or the Update-NAVApplicationObject cmdlet, the differences are applied automatically if possible. However, when conflicts are detected, they're captured in CONFLICT files that clearly identify where two parties such as you and Microsoft have changed the same object or parts of it. For more information, see Handling Merge Conflicts.

Scenario: Updating your solution to the next cumulative update

In the following example, you have built a solution that is based on Microsoft Dynamics NAV 2017, MySolution. Microsoft then releases Microsoft Dynamics NAV 2017 Cumulative Update 1 that includes hotfixes and two regulatory features for your country/region. To help you apply the cumulative update to your solution, you use the Business Central cmdlets. The cmdlets calculate the modifications that Microsoft made between the original release and the cumulative update, and apply these to your solution. Then, you must manually resolve any conflicts, such as both you and Microsoft modified a report object or a table. You must also validate the automatically applied modifications through testing and maybe code review. The following table describes the three versions of the Business Central application that you want to compare and merge.

The Business Central cmdlets calculate the modifications made from ORIGINAL to MODIFIED, capture these, and then apply automatically as many as possible to the TARGET application. The resulting application is stored in a RESULT folder. Some application objects can't be merged automatically; these conflicts are described in separate text files that you can analyze for further processing.

See also

Merge Application Changes
Compare and Update Application Object Source Files
Handling Merge Conflicts
Merging Application Objects using the Example Scripts
Business Central PowerShell Cmdlets