Walkthrough: Creating and Consuming a Codeunit Web Service

This walkthrough provides an overview of how to create and consume a simple Web service with Microsoft Dynamics NAV. The walkthrough illustrates to the following tasks:

Creating a codeunit from within Microsoft Dynamics NAV.
Exposing the Web service.
Verifying the Web services availability.
Consuming the Web service from a console application that is created in Visual Studio.

Prerequisites

To complete this walkthrough, you will need:

Microsoft Dynamics NAV 2009 with a developer license.
Visual Studio 2005, Visual Studio 2008, Visual C# 2008 Express Edition, or any version of Visual Studio that supports adding Web references. You can also use service references instead of Web references or the Web service proxy generating tools (svcutil.exe or wsdl.exe) that are supplied in the Microsoft .NET Framework SDK.

The first step is to create a codeunit that can be published and used as a Web service. You will create a codeunit called Letters that takes a lowercase input string and returns a string that is converted to uppercase letters.

To create a codeunit

Open the Classic client and connect to the CRONUS International Ltd. demonstration company.
On the Tools menu, click Object Designer.
In Object Designer, click Codeunit, and then click New.
On the View menu, click C/AL Globals.
In the C/AL Globals window, click the Functions tab, and then enter Capitalize as the function name.
In the C/AL Globals window, click the Locals button.
On the Parameters tab, enter inputstring in the Name field, and then select Text in the DataType field. Set the length to 250.
On the Return Value tab, enter outputstring in the Name field, and then select Text in the Return Type field. Set the length to 250.
Close the C/AL Locals window, and then close the C/AL Globals window.
In the Capitalize method, insert the following line of code:
Copy Code
outputstring := UPPERCASE(inputstring);
Save and close the C/AL Editor.
When prompted, give the codeunit the ID 50000 and the name Letters.

	Copy Code
outputstring := UPPERCASE(inputstring);

After the codeunit is created and saved, register and publish it using the RoleTailored client.

To register and publish the Web service

Open the RoleTailored client and connect to the CRONUS International Ltd. demonstration company.
In the navigation pane, click Departments, click Administration, click IT Administration, click General, and then click Web Services.
In the Web Services page, click New.
In the Object Type column select Codeunit, and then enter 50000 in the Object ID column ID and Letters in the Service Name column.
Click to select the field in the Published column.
Click OK to close the New - Web Services page.

You should verify that the Web service that you published is available to consumers. Check that Web services are running, and then browse to the WSDL document to ensure that your Web service is available.

Note
When exposing a Web service, you must open the port for other consumers of your Web service to access it. Have your system administrator open the port through Windows Firewall on the computer running Microsoft Dynamics NAV Server. The default port is set to 7047 and can be configured in the CustomSettings.config file on Microsoft Dynamics NAV Server. For more information, see Configuring Microsoft Dynamics NAV Server.

Note

When exposing a Web service, you must open the port for other consumers of your Web service to access it. Have your system administrator open the port through Windows Firewall on the computer running Microsoft Dynamics NAV Server. The default port is set to 7047 and can be configured in the CustomSettings.config file on Microsoft Dynamics NAV Server. For more information, see Configuring Microsoft Dynamics NAV Server.

To start the Microsoft Dynamics NAV Business Web Services service

Click Start on the computer, point to All Programs, point to Administrative Tools, and then click Services.
In the Services tool, right-click Microsoft Dynamics NAV Business Web Services, and then click Start.
Close the Services tool.

If the service is already running, then you must restart it. For information on starting, stopping, and configuring Windows services, see How to: Configure Windows Services.

To verify availability of the specific Web service

Start Internet Explorer.
In the Address field, enter the following address where the keys are replaced with the values that are specified in the CustomSettings.config file: http://<Server>:<WebServicePort>/<ServerInstance>/WS/<CompanyName>/services. An example WSDL URL is:

http://localhost:7047/DynamicsNAV/WS/CRONUS%20International%20Ltd./services

Note

The company name is optional and case-sensitive.

The page should list the Web service that you just published (Codeunit/Letters).
Close the browser.

Note
The company name is optional and case-sensitive.

Now that the Web service is available, you can create an application to call the Web service.

To call the Web service

In Visual Studio, on the File menu, point to New, and then click Project.
Expand the Visual C# node, select Windows, and then, under Visual Studio installed templates, select Console Application. Enter the name UsingLettersService for the application.

The sample code in this walkthrough expects this exact application name, so do not change it.
Click OK to close the New Project page.
In Solution Explorer, right-click the References node in the project, and then click Add Service Reference.

Note

If you are using Visual Studio 2005, then click Add Web Reference instead.
In Visual Studio 2008, click the Advanced button, click the Add Web Reference button, type or paste the URL that you used when checking the WSDL, such as http://localhost:7047/DynamicsNAV/WS/Services, and then click Go.

Note

In Visual Studio 2005, type or paste the URL in the Add Web Reference window, and then click Go.
When the Letters service is displayed, click View Service, rename localhost to WebService, and then click Add Reference.

Note
If you are using Visual Studio 2005, then click Add Web Reference instead.

Note
In Visual Studio 2005, type or paste the URL in the Add Web Reference window, and then click Go.

On the Program.cs tab, replace the existing code with the following code:

C#	Copy Code
using System; using System.Collections.Generic; using System.Text; namespace UsingLettersService { // Import newly generated Web service proxy. using WebService; class Program { static void Main(string[] args) { // Create a new instance of the service. Letters ws = new Letters(); // Use default credentials for authenticating // against Microsoft Dynamics NAV. ws.UseDefaultCredentials = true; ws.Url = "http://localhost:7047/DynamicsNAV/WS/CRONUS%20International%20Ltd./Codeunit/Letters"; // Declare variables to work with. string inputstring, outputstring; inputstring = "microsoft dynamics nav web services!"; // Call the Microsoft Dynamics NAV codeunit Web service. outputstring = ws.Capitalize(inputstring); // Write output to the screen. Console.WriteLine("Result: {0}", outputstring); // Keep the console window open until you press ENTER. Console.ReadLine(); } } }

C#

Copy Code

using System;
using System.Collections.Generic;
using System.Text;

namespace UsingLettersService
{
	// Import newly generated Web service proxy.
	using WebService;

	class Program
	{
		static void Main(string[] args)
		{
			// Create a new instance of the service.
			Letters ws = new Letters(); 	 
		
			// Use default credentials for authenticating 
			// against Microsoft Dynamics NAV.
			ws.UseDefaultCredentials = true;
			ws.Url = "http://localhost:7047/DynamicsNAV/WS/CRONUS%20International%20Ltd./Codeunit/Letters"; 

			// Declare variables to work with.
			string inputstring, outputstring;   
			inputstring = "microsoft dynamics nav web services!";
		
			// Call the Microsoft Dynamics NAV codeunit Web service.
			outputstring = ws.Capitalize(inputstring);  

			// Write output to the screen.
			Console.WriteLine("Result: {0}", outputstring);  

			// Keep the console window open until you press ENTER.
			Console.ReadLine();  
	}
}
}

Press F5 to run the application in debug mode. You should see a console window that prints the text 'MICROSOFT DYNAMICS NAV WEB SERVICES!' in uppercase letters.
Press Enter to close the application.

This walkthrough illustrated how you can publish a codeunit as a Web service from Microsoft Dynamics NAV and write a program that uses the Web service. The next step is to expose a page as a Web service and then interact with data from that page. For details, see Walkthrough: Registering and Consuming a Page Web Service.

Tasks

How to: Register a Web Service
Walkthrough: Configuring Web Services to Use SSL

Concepts

Working with Web Services
Microsoft Dynamics NAV Web Services
Examples of Web Services

About This Walkthrough

Prerequisites

Creating a Codeunit

To create a codeunit

Registering the Web Service

To register and publish the Web service

Verifying the Web Services Availability

To start the Microsoft Dynamics NAV Business Web Services service

To verify availability of the specific Web service

Consuming the Web Service

To call the Web service

Next Steps

See Also

Tasks

Concepts