Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

David Roys

December 2008

Learning to fish

Give a man a fish and you feed him for a day; teach him to use the Internet, and he won't bother you for weeks!

This is going to be a real challenge for the one that wants to play with the new technology that Web services enablement brings, but is a little unsure where to start. A good number of people that are experienced NAV consultants and C/AL developers are going to need to learn some new technologies if they want to start experimenting with the new extensibility options in Dynamics NAV 2009, or even simply understand what options are available for their new solution designs or sales presentations. This article is going to be all about practical examples—real sample applications that you can create for yourself. Some of these examples start off with one set of requirements that evolve as we progress through the design process. The examples are deliberately kept this way to help you to understand that the path to your final working solution is not always the shortest. Sometimes you get an idea for an application and as you proceed with the design, you think of things that would be better or easier to use. Sometimes your initial design simply won't work when you start to try it out. It's important to realize that designs are not precious and it's OK to change your mind. There are a couple of important issues to consider: always ensure you are solving the business problem, and don't get carried away gold-plating your design. Keep it simple, and once it is working and meets the initial requirements, you can then go back and add the bells and whistles (but you'd better check with whoever is paying the bills first).

If you aren't a .NET programmer, and you have never created a web site or Web service in your life, this article is not a place to tell you the best way to do these things, but instead is a place to show you that with a very limited knowledge of .NET, a web browser to do some research, and enough time, you can create pretty much anything you can imagine.

First of all, let's get some theory out of the way so that we have a basic understanding of what we're dealing with.

What's a Web service?

Web services have been around for a few years now but they are new to NAV (well, sort of— but more on that later). A good way to distinguish between technical and non-technical NAV consultants is to ask them if NAV supports Web services and watch to see if their eyes glaze over. There's no wonder some NAV consultants struggle to understand Web services as a concept; if you're not a developer and you have never worked with Web services, learning the basics might be more than a little bit scary. Here's a typical definition you might find on the Web; don't be put off by the geek-speak.

A scary geeky definition of a Web service

A 'Web service' (also Web Service) is defined by the W3C as 'a software system designed to support interoperable machine-to-machine interaction over a network'. Web services are frequently just Web APIs that can be accessed over a network, such as the Internet, and executed on a remote system hosting the requested services.

There are a lot of acronyms and jargon phrases to learn if you want to talk the talk, but let's take a look at what a Web service is in simple terms.

To start with, let's consider a comparison between web sites, something we are all familiar with, and Web services.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

One might like to think that a Web service is to a computer what a web site is to a person. If you want to know what's on TV tonight, you can type the URL for a TV Listings site into a web browser and bring up a page with details. It's not going to take you long to find the required information, but what if you wanted to write a computer program to send an e-mail when your favorite TV show was about to start, how would you go about that? This is a more complex problem, we know the data is there on the web site, freely available to all humans, but we can't just tell our computer to go off and read the web site (well we can—but deciphering it may require a fair amount of clever programming). Wouldn't it be great if there was a computer-friendly version of the data on the web site that allowed computers to ask for information and get answers back? Wouldn't it be great if you could write your program to make the call to this service without the need to install any special software components on your computer? Yes, it is great, and that's why Web services came into being and have now become so popular.

It's not just for the Web

It's not immediately obvious why we would want to expose our precious company data that we keep locked up in our ERP system on the Web, but just because they're called Web services doesn't mean they're just for the World Wide Web. Let's consider the intranet compared to the internet. It didn't take long for companies to realize that the popularity of internet sites and the ease of use that everyone was experiencing through the world wide web could provide great benefits within the boundaries of a company's safe internal network—a kind of mini-internal-internet or intranet. For Dynamics NAV, the analogy between Web Sites and Web services works even better when we consider an intranet. What if different departments could pull data directly from the ERP system and use it in their own specialist applications? This is where the real value of Web services enablement in Dynamics NAV 2009 comes into its own. It is now possible to take any functionality from within the ERP solution and expose it to other applications as Web services; it's not just possible, it's dead easy!

What can we do with them?

OK, so it's easy to expose NAV functionality, so what? Well if you can call any Codeunit or Page from within NAV with pretty much any software package that you can extend, there are limitless possibilities to create fantastic productivity applications for the business. Here are just a few examples:

  • Let staff submit their expenses from Excel, or from their mobile phone, without needing to re-key them into the finance system.
  • Allow users to create new customer accounts from within Word or from an intranet web page.
  • Provide a Vista Sidebar gadget that shows the number of documents requiring approval and allows the user to approve the document without needing to open the ERP.
  • Provide a simple single-task Windows application that will let staff see where stock is.

These examples are just a few that spring immediately to mind, but if you have the know-how, you can do pretty much anything. So how easy is it to expose NAV functionality as a Web service? Let's find out.

Calling a NAV Web service

There is a great series of articles on MSDN by Manuel Oliveira that explain how to expose NAV functionality as a Web service. If you have never read these, you may want to skim through them after reading this example to see just how easy we have it with the new version of NAV.

Talking with NAV—the hard way!

Visit http://msdn.microsoft.com/en-us/library/ms952182.aspx and http://msdn.microsoft.com/en-us/library/ms952079.aspx for a couple of examples that explain the multiple hoops we needed to jump through in order to access NAV functionality using Web services. That's before NAV 2009 came along!

Since these early examples of NAV extensibility, the Windows Communication Framework has made things easier, and Kris Rafnsson has provided a blog posting and sample application that allows you to call NAV functionality as a Web service without using message queues. This example is pretty amazing, but there is still a fair amount of work required to get this up and running and build new solutions. Although this is a big improvement on the Message Queue approach, it is nothing compared to the simplicity and elegance of the NAV 2009 Web services enablement. You can read through Kris's post at http://blogs.msdn.com/nav/archive/2008/04/15/using-web-services-toaccess-microsoft-dynamics-nav-5-0.aspx.

In Manuel's first example (although not actually a Web service), he creates a simple NAV function that will accept a text string and return the text string back but converted to upper case. This example spans 15 printed pages and uses a lot of geeky stuff. As a bare minimum, we are going to need a Codeunit to expose and a .NET program to call the thing, so let's forget about these and just compare the components that are needed to take care of the plumbing:

  • Microsoft Message Queue
  • Navision Communication Component
  • XMLDOM automation control
  • Navision Application Server
  • A lot of complicated C/AL code using InStreams and OutStreams and XML manipulation

Manuel's examples were written in 2004 and, although they're very well written, the whole thing is just too hard! After reading the articles, you'll understand why there hasn't been a glut of NAV components on the market using Web services exposed by NAV. Our example by contrast requires the following (again ignoring the Codeunit we are exposing and the .NET program needed to call it):

  • Dynamics NAV 2009 Business Web services
  • A new record in a table with a check in a box

Creating a Web service

Let's start by creating our very simple Codeunit. In this example, I have created Codeunit 50001 called NAV Codeunit, which has a single function called ConvertStrToUpperCase that takes a 50 character text field and returns a 50 character text field that has been converted to upper case.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

It wasn't absolutely necessary for this example, but I put some code in the OnRun() trigger of the Codeunit that will demonstrate the Codeunit working when run. Here is the output from running the Codeunit in NAV:

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

Now we can expose this Codeunit as a Web service. In the Classic client, select Administration | IT Administration | General Setup | Web Services.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

This is just a regular NAV form, so fill in the details on a new record with Object Type as Codeunit, Object ID as 50001, and Service Name as NAV Codeunit. To publish the Web service, tick the Published field. I just happened to give the Web service the same name as the Codeunit, but this is not necessary, you can call it whatever you like.

We have now exposed NAV functionality as a Web service—how easy was that?

Calling the Web service

The .NET program to call the Web service is going to be a little harder. We're going to create a simple C# console application using Microsoft Visual Studio 2008 Professional Edition. (This is installed on the Marketing Beta release of the product which all partners can download from PartnerSource.)

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

Create a new Console Application, let's call this one SayHelloToNAV2009.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

The project gets created with a Program.cs file with enough code generated for you to allow the project to compile and run. There's no way I can teach you to program in C# in this article, there are whole books dedicated to the subject; instead what I'll do is give you the details you need to be able to recreate our examples for yourself. If you like what you see, maybe you'll go on to do some more .NET programming and your next book will be one on C#. The great thing about .NET languages and Visual Studio is there's a huge amount of knowledge freely available on the Web.

The first thing we need to do is add our Web service to the project. To do this, right-click on the References node in the Solution Explorer window and select Add Service Reference.

Visual Studio 2005 is different
These instructions are for adding a web reference using Visual Studio 2008. In 2005, things work a little differently. Instead of selecting References | Add Service Reference | Advanced | Add Web Reference, you simply selected Add Reference | Add Web Reference.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

In the dialog that is displayed, click the Advanced button, and then click the Add Web Reference button.

In the Add Web Reference dialog form, enter http://nav-srv-01:7047/DynamicsNAV/ws/CRONUS_International_Ltd/Services as the URL for the Web service. This will display the group of Web services that are exposed by NAV.

Where do I find that URL?
The format of the URL is quite straightforward. Let's break it up into chunks.

URL Part



tells the browser which protocol to use (Hypertext Transfer Protocol)


is the name of the computer on which the web services run


identifies the port on which the service is listening for service calls-this can be specified in the CustomSettings.config file by changing the value of the WebServicePort key value.


is the name of the Dynamics NAV Server service and can be changed by setting the ServerInstance key value in the CustomSessiongs.config file.


needed to identify this as a web service call.


This is the company name with spaces and full stops and minus signs removed and replaced with an underscore. I find this a little unpredictable, but thankfully there is a SystemService web service that has a Companies() operation that will return a list of company names in the correct format.


tells the system to return a list of services available. We could use page followed by the name of the page web service or codeunit followed by the codeunit service name.

You may need to alter the given URL to use the machine name that is running the Microsoft Dynamics NAV Business Web services, but for the Marketing Beta VPC image, this one will work just fine.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

The form shows two available services: SystemService and the Codeunit we added called NAV_Codeunit. Click on the View Service link for the NAV_Codeunit service.

The form changes to show the Methods available for the NAV_Codeunit Web service.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

The web reference name on the right of the window (not shown in the screenshot) is set to nav-srv-01 (or whatever the computer name happens to be for you), which is a little bit confusing as to me this represents a computer, but we are using it as the name of our web reference to our NAV Codeunit. You cannot actually use this suggested name, so let's overtype it with NAV_Codeunit_Reference. Click the Add Reference button to add the web reference to our project.

Now we have our web reference, we can write our code. Here is what my code looks like in Visual Studio:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace SayHelloToNAV2009
using NAV_Codeunit_Reference; // NAV_Codeunit_Reference
// is the name
// of our web reference
// the using command means
// we don't
// need to type it.
class Program
static void Main(string[] args)
// Create a new instance of our Codeunit Web Service
NAV_Codeunit navCU = new NAV_Codeunit();

// Set the Web Service to use default credentials.
// NAV Web Services need the Windows credentials
// of a valid NAV user otherwise they won't work.
navCU.UseDefaultCredentials = true;

// Declare a string variable to feed into the Codeunit
// and initialize it.
string myString = "hello nav2009!";

// Output the string to the console.
Console.WriteLine("Input : {0}", myString);

// Output the results of my Codeunit function
Console.WriteLine("Output : {0}",

// Keep the console window open until enter key pressed.
Console.Write("nPress ENTER to Continue...");

We're being a bit lazy here as we are not trying to trap any exceptions that may be thrown by calling the Web services. For example, we defined ConvertStrToUpperCase function to accept a 50-character text variable as input, but in the method description for the web reference, it was simply shown as a string. If you were to change the code to assign myString with text that is longer than 50 characters, you would get an exception when the code is run. It's good practice to put your call to the Web service within a Try/Catch statement so that you can handle the exception in a nice way. Once you have got this working, why not change the preceding code to use a myString value that is larger than 50 characters and see what happens?

New tricks for old dogs

The .NET programming environment is fantastic compared to the C/SIDE, but if you're not used to Visual Studio.NET, you may find yourself pressing F5 to bring up a list of methods and fields. This key-press will actually attempt to compile and run your solution. The Visual Studio equivalent of the C/SIDE F5 key is called intellisense, and will pop up automatically as you type full stops after objects, or you can use the Ctrl+K, L key combination.

Let's run our example (press F5) and see what happens:

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

We did it! We did it! We did it! Yeah! (I think my kids have brainwashed me with too many hours of Dora the Explorer.)

That was really quite easy. Now let's take a deep breath and do some real-world examples.

WinForms application

Our first example was more a proof of concept than anything else—a simple demonstration of how easy it is to expose NAV functionality as a Web service and create a .NET application that will consume it. Now we want to make something that could be of some use. I thought of this example when watching warehouse workers try and use NAV for the first time. All they wanted to do was find out where some stock was, and they had a tiny17-inch monitor that was showing NAV 5.0's large menu structure where they had to navigate through several layers in order to be able to search through the item card and find the bin contents.

Now we have NAV 2009, and the RoleTailored experience means the few simple functions that a warehouse worker needs can be exposed on the role center, but maybe there would be some simple activities that don't really warrant having a full NAV license tied up. This 'Stock Look-up' application is intended to provide that functionality. As always, before we start writing code, we need to define what the functional requirements for our application are.

Item look-up requirements

Our application will have a single input field that allows a user to type a piece of text that can represent an item number, part of an item number, or part of an item description, and hit a search button (a bit like using a web search page). The system will apply some wildcard filters around the words so that the users don't have to be bothered with learning about wildcards, and display a list of potential matches including the Item No., Item Description, Unit of Measure Code, and Quantity available. Possible extensions to this application would be to allow the Quantity to be interrogated further to show which bin locations the stock was in, using Warehouse Management functionality. For now, we'll keep it simple to see if we can use a page type Web service and create a WinForms application.

Exposing the Web service

We know that our requirements will mean using a Page type Web service since we are going to need to set filters and bring back multiple records. It makes sense to use the Item Card page (Page ID=30) since this has all the fields we need: No., Description, Base Unit of Measure, and Inventory. If you've read through the sample Web service call at the beginning of this article, it should be no surprise to learn that exposing our Item Card Page as a Web service is as easy as 1, 2, 3.

  1. Open Administration | IT Administration | General Setup | Web Services in the Classic client.
  2. Create a new record for Object Type = Page, Object ID = 30, Service Name = Item Card.
  3. Tick the Published field.

    Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

Now we have our page exposed as a Web service, let's see if it shows up by entering http://nav-srv-01:7047/DynamicsNAV/ws/CRONUS_International_Ltd/Services in our web browser.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

Bingo! Now let's take a look at the WSDL for that service and see what methods and properties we have available. Whoa—lots of code—over 500 lines, way too much to include here. Instead of digging in to the WSDL, we'll create our WinForms application.

New Windows application project

Start up Visual Studio.NET and select the option to create a new project using the Windows Forms Application template.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

Give the project a name, let's call this one Item_Lookup.

Visual Studio makes a new project for us with a Form1.cs class that is our Windows Form. You could run this form now by pressing F5 but since it has no controls on it, you won't be able to do anything other than resize it, move it around, and close it.

The first thing to do is add our web reference. You can follow the same steps as we did for our Hello NAV 2009 example, but use the URL for the new page Web service instead. If you get it right, you should see the following service description:

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

Once again, we are going to change our service reference to something other than the machine name ( Item_Card_Ref), and click the button to add it to the project.

Now we can add some controls to our form. We take a look down the list of controls and find one called DataGridView that sounds right. Let's drag one of these on to the form.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

When we drag this control on to a form we get a nice little pop-up window asking where our data will come from.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

You can expand the tree nodes until you find the Item_Card_Ref Web service reference, and there in the list is our Item_Card data source. Select it and a new BindingSource control is added to the form.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

With the DataGridView Tasks window still open, you can remove the tick from the Enable Adding, Enable Editing, and Enable Deleting check boxes; we really don't want our warehouse staff accidentally deleting our inventory items.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

Now we can drag our DataGridView control so that it fills the bottom part of the screen, and in the properties pane, change the Anchor property to Top, Bottom, Left, Right. This is a bit like setting Horizontal Glue and Vertical Glue properties in C/SIDE to both so that the control will resize when the form is resized.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

Now we need to change the columns on the DataGridView so it only shows the four fields we are interested in. Click the tasks button, and from the DataGridView Tasks form, select the Edit Columns option.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

With well over a hundred fields to remove and no multi-select option, the best thing you can do is press Alt+R to remove the current field and keep the keys held down until all fields are removed. Once all fields are gone, click the Add button to bring up the Add Column dialog.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

The list works in the same way as the lists in the C/SIDE environment in that if you want to find a specific item, you can jump to the first item by pressing the starting letter; if it's not the column you want, you need to keep pressing the start letter until the required column appears.

Add the No, Description, Base_Unit_Of_Measure, and Inventory columns, and close the form.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

You can use the Edit Columns form to change the appearance of the columns. For instance, we want to change the DefaultCellStyle property of the Inventory field so that it is formatted as a number and is right-aligned. Click the ellipsis (three dots) to the right of the field.

Set the Format property to N0 (that's N for numeric and 0 for zero decimal places), and set the Alignment property to MiddleRight.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

It's suggested you also set the HeaderText property for the Base_Unit_Of_Measure field to something a little shorter (like UOM), and set the AutoSizeMode property for the Description field to Fill.

Now's a good time to run the form with F5 to check that everything looks as it should. You can try resizing the form and see that the DataGridView expands and contracts and the Description field expands to fill the new space.

Getting some data

OK so we have a control to display our data, all we need now is something to put in it. As always we're going to take things one step at a time, so rather than trying to build all the functionality for matching strings in multiple fields with wildcards, we'll just get something to display to make sure everything is hooked up properly. Now it's time to add some code to our form; so double-click on the form and the Form1.cs code editor window will open with a new Form1_Load method created. We're going to put some code in there to find the first 100 records, but in order to do that we'll need to create a new method. The following is how your code should look:

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
namespace Item_Lookup
using Item_Card_Ref; // Item_Card_Ref is our Web service
// reference

public partial class Form1 : Form
// declare our Web service variable
private Item_Card_Service ItemCardService;

public Form1()

// Instantiate our Web service
ItemCardService = new Item_Card_Service();

// Use the default credentials
// (i.e. the NAV Windows User)
ItemCardService.UseDefaultCredentials = true;

private void Form1_Load(object sender, EventArgs e)
// OnLoad we'll display the first 100 records with
// no filter

// New method to find item records based on a filter
// string and display them
private void FindRecords(string filterString)
// Create a new item card instance
Item_Card itemCard = new Item_Card();
// Create a new List of Filters to be used to
// filter the records
List<Item_Card_Filter> filters =
new List<Item_Card_Filter>();

// Create a new filter on the No. field and add it
// to the filter list
Item_Card_Filter noFilter = new Item_Card_Filter();
noFilter.Field = Item_Card_Fields.No;
noFilter.Criteria = filterString;

// Find the records and set the resulting records as
// the datasource for the grid
dataGridView1.DataSource =
null, 100);

If all has gone well, you should now be able to press F5 to compile and run the application and see something like this:

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

There're a few things to tidy up (like the starting columns sizes, the name of the form in the title bar, and the icon for the form), but these can all wait. The good news is we are displaying data from NAV 2009 in a Windows Application. Now let's add our filter text box and button to do the search.

Filter Box and Find Button

Drag a textbox and a button control on to our form and change the Text property for the button from button1 to Find.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

Double-click on the Find button so we can add some code to run when the user clicks the button. Not too much code to add this time; since we already have our method to do the work, we just need to call it with the contents of the text box.

private void button1_Click(object sender, EventArgs e)

Testing time

Press F5 to run the application one more time so we can test our new search functionality. Since I'm watching the New Zealand men's soccer team get beaten by Brazil in the Olympics, let's search for some items with an Olympic feel. Type ????-? into the text box (meaning any four characters followed by a minus sign followed by any character) and click the Find button.

Extending the Application using Microsoft Dynamics NAV 2009 (Part 1)

Hmmmm, the 2008-S B EIJING Bar Stool, grey doesn't seem to be there. Come to think of it where's the 1912 Summer Olympics in Stockholm or the 1916 games in Berlin? Phew, I checked the data in the Classic client and the problem is in the test data and not our form. Everything is working perfectly.

WinForms application summary

The product team has definitely made it easy for us with the thought they have put into the NAV Page Web services. There are some things that are just so easy when doing development in C/SIDE compared to .NET. For example, when you're editing data on a page, you don't need to worry about whether another user is trying to edit the same data. If you were to extend our example to include the ability to edit the data, you need to consider whether the data has been edited by someone else, possibly even deleted, and what you will do to handle the exception.

See if you can keep extending our little application to include all of the features described in the requirements section.


In this article we learned about Web service, what's it all about and how to create and use it.  We also saw how easy it is to expose NAV functionality as a Web service and create a .NET application that will consume it. In addition to this, we created a WinForms apllication using NAV 2009.

We will explore the use of web services further in the Next Article.

You've been reading an excerpt of:

Implementing Microsoft Dynamics NAV 2009

Explore Title