Localize Objects with PowerShell and VSCode

In this article I will explain how you can use PowerShell to extract the right objects and merge those objects, and how to use Visual Studio Code to resolve most of the conflicts in the merged objects.

In a previous article, I explained how you can use PowerShell to create the environments. The script in this article actually use the variables that are assigned in the other one. What I should really do is create a configuration file and load that from both scripts. I wanted to share what I have so far though, without a handy configuration file but hopefully helpful nonetheless.

We start off with the 4 environments that were created in our last article: ORIGINAL, MODIFIED, TARGET, and RESULT. The first two environments contain the standard W1 and the ISV product. Target and RESULT are identical at this point, and they both contain the standard NA localization. All environments are in the same build number (NAV 2017 CU2 in this case). Because I have a developer license that has insert rights in the ISV number range, my strategy is to merge the product modifications into the NA database. If you do not have those insert rights, then a better strategy would be to merge the NA localization into the product environment instead. Microsoft has recently added insert capabilities for the standard object ranges to regular developer licenses, for this particular purpose. As I was working through the conflict objects of this assignment, I was thinking that this may even be the best default strategy anyway.

Due to a limited amount of time, and a limited amount of PowerShell skill, I decided to approach this task pragmatically:

  • Manually move the ISV specific objects to the RESULT environment
  • Use PowerShell to export all the objects
  • Manually eliminate the unmodified objects
    • NOTE: as I learned later, Waldo’s PowerShell modules actually have logic to remove these after the merge, so this can be scripted as well
  • Use PowerShell to merge the objects
  • Use Visual Studio Code (AKA VSCode) to resolve the conflicts as much as possible
  • Use PowerShell to join the objects
  • Use C/SIDE to resolve any remaining conflicts

The conflict resolution is something that has to be done manually. Everything else can be scripted in PowerShell. During this process I’ve asked Waldo for some help, and he explained that most of what I am doing here is already part of the merge sample scripts. In the Cloud Ready Software PowerShell module, there is a folder called “PSScripts”, and in that folder you will find a large number of scripts that you can use as an example to get started on your task. As you gain experience in using PowerShell, you will recognize a lot of useful features in those scripts, and you can modify them to your specific needs.

Alright, on to the details. The first part is to use PowerShell to extract the objects into their own folders. I also added commands to create the folder structure itself:

At this point, you will have an “Objects” folder in your working folder, with full object files for ORIGINAL, MODIFIED, and TARGET. Those object files have then been split into individual object files in the ORIGINAL, MODIFIED, and TARGET folders. Before using PowerShell to merge those objects, I used a text compare tool (I like Scooter Software’s Beyond Compare) to eliminate unmodified objects. Remember, I only want to work on the modified objects, so I don’t have to worry about getting confused by objects that were not changed for the ISV product.

Now that we only have modified objects in all three object folders, we’ll use the merge Cmdlet to do the actual merging of the objects.

If you notice, the output of the “Merge-NAVApplicationObject” Cmdlet is loaded into the variable “$MergeResult”. This object is then piped into the “Merge-NAVApplicationObjectProperty” Cmdlet. The first Cmdlet is a standard NAV PowerShell Cmdlet, and the second one comes with the Cloud Ready Software modules. The standard merge Cmdlet does not merge the Version List property, it simply takes the Version List from one of the three environments. We can have a discussion about whether the Version List is even important anymore, especially if you use Source Code Management. The reality is that most NAV developers depend on proper tags in the Version List, so it is useful to merge those as well. All you need to do is specify the prefixes that you want to merge (In my case NAVW1 and NAVNA) and it will find the highest value for those prefixes. All other prefixes will be simply copied into the RESULT objects.

At this point, we have all merged files in the RESULT folder. This includes the objects that were merged successfully, but also the objects that the merge Cmdlet could not resolve, for instance when code was added at the same position in MODIFIED and in TARGET. Since we are going to have to learn how to use VSCode, I decided to use that to resolve the conflicts.

With VSCode installed, you can open the RESULT folder and see the content of this folder inside the file browser at the left hand side. In the upper right hand corner is a button that you can use to split the screen into two (and even three) editor windows. This is very useful for resolving merge conflicts, because you can open the conflict file in one side, and the object file in the other side. You are editing the actual object file here, so you may want to take a backup copy of the folder before you get started.

Now what you must understand is that the conflict files only contains the pieces that the merge Cmdlet could not figure out. In a total of 860 objects, with 6956 individual changes, it was able to merge 96.4% of those changes. An object that may have 4 conflicts can also have a ton of other changes that the merge Cmdlet merged successfully. All YOU have to do is focus on the ones that need manual attention. For instance, codeunits 80 and 90 had a TON of modifications, but it only needed help with 3 of them.

I had a total of 115 conflict files, and I could completely resolve 112 of them in VSCode. I made a note of the few that remained, and decided to import those unchanged into C/SIDE, so I can finish those off in the proper IDE.

The last PowerShell command that I used is to create a single object file, which can then be imported into C/SIDE. Then I finished the last few remaining object files, and was able to compile all objects from there.

I’ve done many of these merges completely manually. To say that I was skeptical that PowerShell would do a good job is putting it mildly. I flat out did not trust the merge Cmdlet, surely they could not do as good a job as I could do. I was wrong. I checked a bunch of objects to see if I could find any mistakes and I could not find any. Not only did the merge Cmdlet do a fine job at merging the objects, it did so in about 5 minutes flat.

You can download the scripts here.

Instead of having to manually merge almost 900 objects, all I had to do was focus on the conflicts. Usually, a vertical merge like this would take me anywhere from 2 to 4 weeks, and I was able to finish this one in less than two days. Figuring out the PowerShell scripts took me much longer, but I will be able to use those for the next merge task.

Create NAV Environment with PowerShell

If you kind of know about PowerShell, and you want to use it more, but you don’t really know where to start, then you should read on. I am going to explain to you how you can use PowerShell to create the environments that you need to localize a product.

One of the things that always seem to fall on my plate at my job is to take an ISV product and merge that into the North American localization. I call it ‘localizing a product’. It is not, because localizing a product is much more than simply merging the objects, but it’s what you have to do first. I’ve done a bunch of these manually, and I kind of enjoy the almost mindless nature of the task of working my way through hundreds of objects (sometimes even thousands, I once ‘localized’ a product that had more objects than standard NAV itself).

This time around, I wanted to use PowerShell to automate as much as I could. Lucky for me, I attended Waldo’s “PowerShell Black Belt” workshop at NAV Techdays (read my review of this fantastic event here) and I should have all the tools to get this started.

The first thing you need is to install Waldo’s PowerShell modules, I will be using those for just about everything. I could figure out how to script all of this stuff myself, but why would I if Waldo already did that for us, and he is sharing his scripts. For instructions read Waldo’s blog here.

This post focuses on creating the environments themselves, and for this task you really need just a few things:

  • A SQL backup for the product in the W1 version of NAV, and make sure that you know exactly which build this was developed in. For instance, the product that I am working with was provided as a SQL Backup, and it was developed in NAV 2017 CU2.
  • The DVD’s for standard W1 and NA for the same NAV build.
  • A Development license that has insert rights for the product’s number range. If you only have a regular developer license, or if the ISV refuses to provide you with a license (this happens more often than not) then you will have to merge NA into the product database. This works exactly the same, you just have to figure out which environments are your ORIGINAL, MODIFIED and TARGET.

Use the NA DVD that you just downloaded and install the NA Version with a demo database. I like to give the database a meaningful name, so I called it ‘NAV2017NACU2’. This is all the manual installing that we will do, everything else is PowerShell baby! Actually, you could even use Waldo’s PowerShell modules to do the install as well. You could even write a script that downloads the DVD for you as well, all using Waldo’s PowerShell modules.

If you understand the mechanics of localizing a solution, you will know that we need 4 databases in total: standard W1, Product database in W1, standard NA, and a copy of the standard NA database that will become the product database. In this case, standard W1 is ORIGINAL; product W1 is MODIFIED; standard NA is TARGET and product NA is RESULT. This will become important when we do the merge, which will be another blog post.

Now the goal is to have a re-usable script, so we’ll use variables instead of having to re-type values multiple times, as you can see in the picture.

Remember, I installed standard NA. I created the working folder and placed the three backup files into the ‘Backups’ folder. I like to keep things together, but I can imagine having a network location for the standard backup files. The nice thing about using these variables is you can set them however you need them :). My database server is called KERPLUNK, which is just a regular unnamed instance on my VM called KERPLUNK. You could also use a demo installation and then you’d have to set it to ‘KERPLUNK\NAVDEMO’. I will use the 4 names for the database names as well as the service tier names.

The rest of the script is surprisingly simple to put together, here it is:

The reason why I start with the ‘Copy-NAVEnvironment’ step is because this script turns on port sharing for both server instances, so I don’t have to take care of that step myself. This is one of Waldo’s script that looks at the first server instance and creates a new one just like it. It creates a SQL Backup from the service instance, restores that into a new database, and finally it creates a new server instance for that new database, and it enables port sharing by default. The ‘New-NAVEnvironment’ is also one of Waldo’s scripts, and it does all the heavy lifting of restoring the database, creating the service tier and setting up port sharing. The full script took maybe 2-3 minutes to run for me, not bad for something that used to take all morning.

This same script could also be used to create your environments for developing extensions. For that you only need a standard database for ORIGINAL and a development database for MODIFIED, both of which will then be used to create the DELTA files for the extension package. If you look at the screenshot of my environment you’ll see an APPDEV and an APPTEST database. Both of these were originally created as copies of the standard database, also using PowerShell.

I’m planning to also put this into a video but I actually have this work to deliver so I’ll focus on that first. Up next is getting the objects out and comparing them to create a set of merged objects. Stay tuned!

Update 4/22/2017: added link to the new article about localizing the objects, and you can download the scripts here.

Webinar – Dynamics NAV Dev Tools Preview

This morning I was part of a panel to host a webinar to show the development tools preview. It was my pleasure to provide the demo part and show the attendees a taste of what is to come in the new development tools for Dynamics NAV. The demo part was just about 25 minutes, and then we opened up the floor for questions. We had some good questions, and it was a lot of fun to be able to share that with everyone.

The webinar was recorded and uploaded to YouTube, and you can watch it here. Oh, my name is not Erik Ernst, not sure how that happened 🙂

Early Christmas Present – NAV Developer Tools Preview

At Directions in the US this year, Microsoft announced that they would release a preview of the new development tools for Dynamics NAV. Today, they have delivered on that promise, and you can try them out in your Azure subscription. Head on over to the Development Tools Preview for Dynamics NAV to read all about it. You will find instructions on how to get started there. Go to the New NAV Development Environment on MSDN to read more about the details.

If you decide to take the tools for a test run, and you find any issues with them, you can report on those issues in the AL Github issue tracker. Go to The Microsoft/AL Github page, click on the ‘Issues’ tab and create a new issue there. Microsoft is monitoring the issues there.

The important part to keep in mind about this preview is that it gives us a preview of how development for extensions is evolving. The goal is to simplify the process to where all we need to do is write the code and hit a build button, and all internals are taken care of by the environment.

Remember, this is just a preview of the tools. It is not supposed to be flawless. Microsoft is also working on many other tools to complement VSCode and provide a development experience that will meet the NAV developer’s needs.

NAV in VSCode – Hello World

Today marks something quite unique, at least for the NAV world. Microsoft is actually giving us a preview of a preview product that they have announced for Christmas.

During this year’s conference season, Microsoft has shown their vision of the future development tools for Dynamics NAV. We’ve seen various demonstrations of how we will be doing development for NAV in Visual Studio Code, a lightweight development tool. Today they have put some sample files on GitHub (Check it out here) for all of us to look at and to critique.

Visual Studio Code (VSCode for short) is available on Windows, but also on MacOS. Since my main computer is a MacBook, I wanted to see if it really does work. To be modifying NAV objects within VSCode on a MacBook is an almost surreal experience, but here’s proof:

screen-shot-2016-11-29-at-4-22-41-pm

The sample is a simple “Hello World” application, with a couple of codeunits and a so-called ‘page extension’ object. Part of the vision for future development is to make building extensions easier. Without going into any detail of why that is important, this will make extension and app development a LOT easier to do.

Some of my thoughts:

  • Microsoft is finally taking NAV development into a professional development tool. Hopefully this will inspire (or at least not deter) a new generation of NAV developers
  • json files for configuration and for the app signature will make automating deployment much easier
  • No more control ID’s, which means those will no longer cause upgrade headaches
  • I would like to also get rid of object ID’s, which they have said that they are looking into. Current licensing is based on object ID’s though, so I’m not holding my breath
  • It will be interesting to see if there is any automatic sorting by control type. For instance will you be able to mix fields and functions in a table object, or will the compiler automatically sort this for you. There’s potential to really mess up the object’s readability
  • This is Visual Studio Code, not Visual Studio. It is still to be seen whether C/AL will be a fully functioning .NET language, and it is still unknown whether we’ll have access to other .NET goodies from this editor
  • Lastly – we are getting just a preview of the tool. Nothing was said with certainty about when this is ready for prime time. What is REALLY cool though is that Microsoft is inviting everyone to participate in the process

Go check out the files for yourself, and if you’d like you can even contribute to the GitHub project. For me, this is a very exciting prospect, and I can’t wait to see what happens next.

The Skinny on Extensions

Earlier this month I wanted to write about what’s new in NAV 2017, and my fellow MVP and good friend Eric ‘Waldo’ Wauters beat me to it. So, my next plan was to write something comprehensive about extensions. I am signed up for a deep dive workshop next month, and I want to be well prepared. Again, as I am collecting information, this guy publishes a large post about extensions, and judging from the title it looks like it was the first of three posts. So…. instead of doing the work myself, I waited for him to post number three, and give you the links in here: Part 1, Part 2, and Part 3.

I could try and say something intelligent about these posts, but I’d make myself look foolish. After the workshop I’ll have plenty to share anyway. Enjoy 🙂

Extensions! Extensions! Extensions!

Just a quick post today about something that is probably the most important thing to learn as a NAV developer, which is Extensions.

I remember going to an event where Steve Ballmer did the keynote. It was a technical conference, and he started his talk by almost screaming “DEVELOPERS! DEVELOPERS! DEVELOPERS!”. It was meant to make the people in the audience, who were almost all developers, like the most important people on the face of the earth. He kept hammering on the point that developers were THE MOST IMPORTANT to Microsoft, and showed us all kinds of evidence that this was the case.

This past year or so has seen a big push toward this new thing in NAV development called ‘Extensions’. Rather than modifying the base code of the product, which is what most of the NAV partner channel is doing for their customers, extensions allows you to create custom functionality without actually touching the base code itself. Coming back from Directions this year, it has become clear that Microsoft is ALL IN on moving NAV development toward extensions. My fellow MVP and good friend Eric ‘Waldo’ Wauters wrote about extensions as well this week, so I won’t bother repeating that part.

What I want you to know about extensions is that as a technical NAV professional it is essential for you to learn about extensions. Your ability to keep your relevance in this industry will depend on whether you are able to effectively use extensions to develop a custom solution for NAV. Apps for Dynamics 365 are only possible with extensions, but it might even become necessary to use extensions for on prem implementations.

I’m signed up for a full day pre-conference workshop at NAV Techdays this year, which will hopefully give me the necessary skills to get that started for me. What are you planning?

Import Flat Files with XMLPorts

After reading this blog and watching this YouTube video, you should have enough information to start figuring out how to use XMLPorts to import flat text files, even when this file contains data for multiple tables.

When I first got started as a NAV developer, I was assigned a senior whose job it was to educate me about what it takes to be an effective NAV developer. Whenever I had a question he would always challenge me to figure it out myself, while maybe giving me a tiny little push in the right direction. At first I thought that was very annoying, but it forced me to develop what is probably the most important skill as a developer: the skill of “figuring out how stuff works”. Once he was satisfied that I had spent an adequate amount of time and brainpower to a problem, he would take the time to give me a lesson. Sometimes he would make these lessons up on the spot, because he had to figure it out himself. Those lessons are my favorite memories of my time learning how to be a NAV developer, and oddly enough most of them weren’t even about syntax or objects, but about “how to figure stuff out”.

Every day, I make my rounds through the online communities, in search of questions to answer. Sometimes, I find a question that makes me wonder myself how something works. When this happens, I take a standard NAV database, and spend some time in the evening hours to figure it out. The past few days there’s been a question about how to import data for multiple tables into the RTC from a flat file, using an XMLPort. Now, at my work, all the developers attend a weekly conference call. On these weekly calls one of us presents a technology, or some tips on how to do certain things. We had recently held one about XMLPorts for the RTC, so I felt confident that this one would not be too big of a problem for me.

While my wife took my daughter to dance class, I worked on a couple of XMLPorts for the RTC, to import Purchase Invoice information into NAV. The YouTube clip below describes the results of those efforts. Hopefully this will help you understand how this works.

First published April 24, 2012

NAV2013 Beta – OData Introduction

With NAV 2013, Microsoft has added the capability to expose data from your NAV system as OData Web Services. Where that differs from regular Web Services (which in the NAV Server management snap-in is now identified as ‘SOAP Services’), is that OData only exposes data feeds, and within the context of Dynamics NAV is read-only. Click here to read all about OData, and here for an overview of OData in NAV 2013.

I’ve put together a new YouTube clip to show you where to find the OData Web Services in the NAV Server Management tool and the Web Wervices table from the RTC, as well as a couple of examples of how to consume them. As you will find out fairly quickly in this video, I have a LOT to learn about OData. I wanted to share what I do know though, and give you an idea of where to start looking.

This provides a new way to expose data from NAV, in an industry standard way, although I am sure that true OData experts will find missing pieces. It is another possibility for us to expand the reach of the ERP application that we know and love. I hope you enjoy the video, and that you will be inspired to start learning about it, and maybe even get some ideas about how to use them for your business.

First published May 23, 2012

New and Improved Page Design in NAV 2013

In NAV 2013, Microsoft has introduced some very nice new features to make designing Page objects for the RTC much easier than we were used to in NAV 2009.

Remember the good old days, when we had a wysiwyg designer for the Form objects, and we could put anything we want, anywhere on the form? This made for some really ‘creative’ (ahem) solutions, but essentially we were used to having complete control over the look and feel of the forms. When the RTC was introduced, we got the first step into a completely independent display target. Instead of defining x and y positions, display elements are now defined by metadata, and the display target should then be smart enough to interpret the metadata when the object is rendered. The intention was to ultimately have a situation in which it doesn’t matter where the page is displayed. The page object itself can be identical, and the display target then decides how to display certain elements based on the capabilities of the display target. For instance, the RTC displays exactly the same page as the Web Client or the Sharepoint Client, they just display the same page differently.

Unfortunately, when all you see is metadata, developing Pages becomes a very abstract exercise. Since there is no direct connection between the development tool and the rendered object, what we had to do was save the object, and hope for the best from there. We had to actually run the page to see what it would look like, and finding individual elements was a very painful thing to do. Lucky for us, the NAV team in Denmark cares a great deal (a GREAT deal) about what we think of the product, and they are VERY proud of the tools. When they were receiving many complaints about the Page Designer, they decided to enhance the development experience in NAV 2013 and address some of the most-frequently-complained-about issues. In my opinion the result is a HUGE improvement over NAV 2009.

What I want to do is focus on two new capabilities in the Page Designer. The first one is the ability to preview the Page right from the Page Designer, without saving the object first. My favorite feature of this capability is that there is a link between the ‘metadata designer’ and the ‘page previewer’. When you click on an element in the ‘metadata designer’, it is highlighted in the preview, and vice versa. You can see a rendered version of the metadata before saving it, and have a visual clue of what you are doing. The second (there is an ‘A’ and a ‘B’ here) is the ability to add columns to the Page object, through a Grid Layout and/or a Fixed Layout. These two new types of group elements make it possible to display multiple columns on the Page.

The NAV 2013 online help has a lot of good information about Page design, with walkthroughs and other tutorials. I’ve created a YouTube video in which I take you through the various screen elements of the NAV 2013 RTC, and then into the Page Designer to show you these new capabilities. I hope you’ll enjoy the video, and hopefully you’ll feel a bit more confident in using the Page Designer.

First published May 31, 2012