Merging Application Objects using Windows PowerShell

Merging Application Objects using Windows PowerShell

Rate This
  • Comments 13

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 3 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)....?

  • I agree with <Kai Kowalewski>. Splitting of object file slows down considerably at the end. Using Split-NAVApplicationObjectFile the whole procedure is about 3-5, using an old vb scripts the same thing is clear and done in about 10 seconds??!!

  • Please be careful using these cmdlets, unless you know all your customizations! Check grumpynav.wordpress.com/.../caution-the-merge-cmdlets-might-merge-incorrectly for more info.

  • I've got another Problem with merge process.

    If i've customized a subpage with some fields at the end of the list of fields and merge RU 12 into that customized objects at Page 46 there is a subgroup after the field "Line No.". This is the same Position where my new fields were placed in Target database. After merge process runs my fields are placed right after that group which results in not displaying any of my fields.

    Please help.

  • So far as we know - "it works if the comments in the code bla bla bla... it does not work if bla bla bla".

    Dear Vedbaek, if it has those IFs - this is not a tool, this is not a product... This is just "one of thse buggy things". Moreover, you didn't document those "ifs" even...

    I can't believe Microsoft is spending hundreds if not thousands of hours doing absolutely useless "tools", instead of providing new functionality and fixing tremendous amount of issues the system is experiencing...

    The budget is needed to be spent - the budget is being spent. What it is being spent on? Who really cares... Congratulations.

  • Not sure if I am doing something stupid, but...

    I am trying to use the merge cmdlet to upgrade a customer objects from 2009 to 2015 - so I have a set of Cronus objects from 2009 as original, the customer 2009 mods as modified and 2015 base as target. When I do the merge I am losing some functions in 2015 - i.e. in table 36 the SynchronizeForReservations function has been dropped from the result set. I have also tried running the merge with the modified pointing to the 2015 files and target as customer 2009 but same result. Anyone point me in the right direction here?

  • Managed to figure out what was wrong - the customer version was showing as 2009R2 and so this was the version I had used for the Original files, but this was incorrect.Changed the Original files to be from 2009 (R0) and merge tool now working as expected.

Page 1 of 1 (13 items)