Merging Application Objects using Windows PowerShell

Merging Application Objects using Windows PowerShell

Rate This
  • Comments 7

Upgrading a Microsoft Dynamics NAV solution is time consuming. 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 move the existing data around so that it fits the new database schema. In Microsoft Dynamics NAV 2013 R2, we started delivering Windows PowerShell cmdlets and sample scripts that can help you automate different parts of the upgrade process. In the latest cumulative update, we introduce a new set of Windows PowerShell cmdlets that can help you through the code upgrade.

You can use the new cmdlets to modify application object source files in the Microsoft Dynamics NAV 2013 R2 Development Shell, or by importing the Microsoft.Dynamics.NAV.Model.Tools.psd1 module into the Windows PowerShell Integrated Scripting Environment (ISE). The new application merge utilities install when you choose the Developer option in Microsoft Dynamics NAV 2013 R2 Cumulative Update 9 Setup, or if you add the development environment to another installation option.

The application merge utilities include the following Windows PowerShell cmdlets:

Name

Description

Merge-NAVApplicationObject

Compares the changes that have been made between two sets of Microsoft Dynamics NAV application objects, and applies the difference to a third set of application objects. The result of the merge is a number of text files with the merged application objects. Any conflicts that the cmdlet cannot merge are identified in conflict files.

Compare-NAVApplicationObject

Compares text files that contain Microsoft Dynamics NAV application objects, and then calculates the delta between the two versions. The result of the comparison is a number of text files with the calculated delta.

Update-NAVApplicationObject

Applies a set of deltas to the specified application objects. The files that describe the delta are generated by the Compare-NAVApplicationObject cmdlet.

Join-NAVApplicationObjectFile

Combines multiple application object files into one text file

Split-NAVApplicationObjectFile

Splits a text file that contains two or more application objects into separate text files for each application object.

Get-NAVApplicationObjectProperty

Gets Microsoft Dynamics NAV application object properties from the specified application object text files.

Set-NAVApplicationObjectProperty

Sets Microsoft Dynamics NAV application object properties in the specified application object text files.

Getting started

You will be able to read more about the cmdlets and how to use them in the MSDN Library after the release of Microsoft Dynamics NAV ‘Crete’, but for now, you can also type Get-Help "NAV" in the Windows PowerShell ISE the Microsoft Dynamics NAV Development Shell.

If you don’t want to use the Microsoft Dynamics NAV Development Shell, use the Windows PowerShell ISE. But before you can access the cmdlets, you must import the Microsoft.Dynamics.Nav.Model.Tools.psd1 module. Here is an example of the command you can type:

Import-Module "${env:ProgramFiles(x86)}\Microsoft Dynamics NAV\71\RoleTailored Client\Microsoft.Dynamics.Nav.Model.Tools.psd1" -force

Get-Help "NAV"

Now you can see the Help for the cmdlets and take a closer look at the examples for how to use them. You can also see detailed Help for each cmdlet by typing the following command:

Get-Help cmdletname -detailed

And you can concentrate on the examples by typing the following command:

Get-Help cmdletname -examples

For all of the new cmdlets, the starting point is 3 versions of application objects that you want to merge. The following table describes the three versions of the Microsoft Dynamics NAV application that you want to compare and merge.

Version

Description

ORIGINAL

The baseline of the application merge. For example, the Microsoft release of MicrosoftDynamics NAV 2013 R2.

MODIFIED

The updated version of the original. For example, this can be Microsoft Dynamics NAV 2013 R2 Cumulative Update 9. Alternatively, it can be a small add-on.

In many cases, the modified application is the version that contains fewer changes to the original than the version that is the target of the merge. This is because you want to apply fewer changes to a large application rather than applying a large change to a small application.

TARGET

The version of the application that you want to apply the difference between the original and the modified application to. For example, this can be your solution that you want to apply a cumulative update to. Alternatively, it can be a new major release from Microsoft that you want to apply your modified solution to.

Each of these versions can be any version that you want to do a three-way merge between. ORIGINAL can be your add-on, MODIFIED can be a customization of your add-on, and TARGET can be a new release of Microsoft Dynamics NAV from Microsoft. But for the purposes of this blog post, we'll keep the definitions as described in the table above.

As input to the cmdlets, you can provide a text file, a list of text files, or a folder with text files. So you need to export the relevant application objects as text files. Optionally, you can use the development environment command ExportObjects. You can export each application object to a separate text file, or you can export all objects to a single text file. Optionally, you can use the Join-NAVApplicationObjectFile and Split-NAVApplicationObjectFile cmdlets to structure the text files in the way that works better for you. Also, depending on your scenario, you can work with a subset of your application, such as all codeunits, objects within an ID range, or a specific group of objects. Use the tools to get the text files that you need, and take a look at the sample scripts for inspiration.

The Windows PowerShell sample scripts are available in the attached compressed archive. Start by opening the HowTo-Start-Import-NAV-Module.ps1 script in the Windows PowerShell ISE, navigate the command prompt to the folder where you placed the samples, and then run the script. Then open one of the other scripts, such as HowTo-Merge-1-General.ps1, and follow the guidance in the script.

The sample script package includes a folder with four subfolders that can help you get started with the scripts. The demonstration data in the ORIGINAL, MODIFIED, and TARGET folders illustrate the text files that are the input to the cmdlets. For clarity, we have chosen to have one application object in each file, but you can use the Join-NAVApplicationObjectFile cmdlet to combine all the text files in the MODIFIED folder in a single file, for example, before you run the script. That way you can see how the Merge-NAVApplicationObject cmdlet identifies the application objects in the combined text file. We find it easier to work with one object in each file, but the cmdlets are there so you can configure the text files in the way that works better for you.

We suggest that you open each of the sample scripts in the Windows PowerShell IDE and read through them to get acquainted with the new cmdlets. Then, set up a small test environment of your own where you can safely use the cmdlets on your own application objects to upgrade your solution to Microsoft Dynamics NAV 2013 R2 Cumulative Update 9.

For more information, see the Merge Application Object Source Files whitepaper, which you can download from the blog post that announced the availability of Cumulative Update 9 here: http://go.microsoft.com/fwlink/?LinkId=403646.

Attachment: MicrosoftDynamicsNAV2013R2CU9ApplicationMergeUtilitiesSamples.zip
Leave a Comment
  • Please add 1 and 8 and type the answer here:
  • Post
  • Hi, the only thing wasn't clear for me - maybe helps to others - the new "Microsoft.Dynamics.Nav.Model.Tools" stuff (ps1, dlls) is not included in the Cumulative update files, you need to copy from the DVD...

  • Hello,

    Sorry for any confusion! The Microsoft.Dynamics.Nav.Model.Tools.psd1 module installs with the client when you choose the Developer option in Setup. The sample scripts are on the product media for Cumulative Update 9 and attached to this blog post.

    Best regards,

    the NAV team

  • Is it possible to use the "Microsoft.Dynamics.Nav.Model.dll" directly for .txt modification projects? Also commercial projects?

  • The split cmdlet shows a strange behaviour. At first it is very fast (approx. for 95% of the objects), and for the last few objects it keeps getting slower and slower, the last 5% take even longer than the 95% before. The other NAV object splitters which are available work much quicker since they sustain the same speed right up to the end. I've tried it out which all sorts of packages, from 400 to 4500 objects , but the effect is always the same.

  • Hi

    I haven't seen any information if these cmdlets works with previous versions (pre cumulative update 9) or do they only work från CU 09 and forward?

  • @Capone: The cmdlets do work with previous versions as well, with limitations only on obsoleted data types like forms in NAV 2009.

  • This is pretty great - has been a big time saver for me already.

    On my wishlist: an option to merge version lists.  Either by concatenating all distinct substrings (assuming comma-separated); or a 'maximal' merge (common substring + substring only in first version list + substring only in second)....?

Page 1 of 1 (7 items)