Walkthrough: Creating and Using a Codeunit Web Service (SOAP)

Article
09/24/2014

Web services provide easy communication and data exchange in a secured environment. In Microsoft Dynamics NAV 2013 R2, you can create, publish, and use web services. For example, you can publish a web service that lists all your customers and have that web service be immediately available for authorized requests over the network.

About This Walkthrough

This walkthrough provides an overview of how to create and use a simple SOAP web service. The walkthrough illustrates to the following tasks:

Creating a codeunit in Microsoft Dynamics NAV.
Publishing the codeunit as a web service.
Verifying web service availability.
Using the web service from a console application that you create in Visual Studio.

Note

You can publish codeunits only as SOAP services, not as OData web services.

Prerequisites

To complete this walkthrough, you will need:

Microsoft Dynamics NAV 2013 R2 with a developer license.
CRONUS International Ltd. demonstration database.
Visual Studio 2012 or Visual Studio 2010. You can use any edition of Visual Studio that supports adding web references. In this walkthrough, you will use Visual Studio 2012. You also have the option of using service references instead of web references, or of using the web service proxy generating tools svcutil.exe and wsdl.exe, which are included in the Microsoft .NET Framework SDK.

Creating a Codeunit

In this procedure, you create a codeunit called Letters that takes a lowercase input string and returns an uppercase string.

To create a codeunit

Open the Microsoft Dynamics NAV development environment and then connect to the CRONUS International Ltd. company.

Object Designer opens automatically in the development environment.
In Object Designer, choose Codeunit, and then choose New

The C/AL Editor opens.
On the View menu, choose C/AL Globals.
In the C/AL Globals window, choose the Functions tab, and then enter Capitalize as the function name.
In the C/AL Globals window, choose the Locals button.
On the Parameters tab, type 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 C/AL Editor, under Capitalize, add the following line of code:
```
outputstring := UPPERCASE(inputstring);
```
Choose Save from the File menu.
When you are prompted, enter 50000 for the codeunit ID, then enter Letters for the name, make sure the compile check box is checked, and then choose OK.

Publishing the Web Service

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

To publish the web service

Open the RoleTailored client, and then connect to the CRONUS International Ltd. company.
In the Search box, enter Web Services, and then press Return.
In the Web Services page, choose New.
In the Object Type column, select Codeunit, then in the Object ID column enter 50000, and then enter Letters in the Service Name column.
Mark the check box in the Published column and choose OK to close the New - Web Services page.

Verifying Web Service Availability

Note

After publishing a web service, verify that the port that web service applications will use to connect to your web service is open. The default port for SOAP-based web services is set to 7047. You can configure this value by using the Microsoft Dynamics NAV Server Administration Tool.

To verify availability of the web service

Start Windows Internet Explorer.
In the Address field, enter an address in the following format: http://<Server>:<WebServicePort>/<ServerInstance>/WS/<CompanyName>/services.

For example:

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

Note

The company name is case-sensitive.

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

Using the Web Service

In this walkthrough we use Visual Studio 2012 to call and use the web service.

To call the web service

In Visual Studio, on the File menu, select New, and then choose Project.
Under Installed Templates, expand the Visual C# node, select Windows, and then, select Console Application.
Enter the name UsingLettersService for the application and choose OK to close the New Project page.The sample code in this walkthrough expects this exact application name, so do not change it.
In Solution Explorer, right-click the References node in the project, and then choose Add Service Reference.
In the Add Service Reference window, choose the Advanced button.
In the Service Reference Settings window, choose the Add Web Reference button, type or paste the URL that you used when you checked the WSDL, such as https://localhost:7047/DynamicsNAV/WS/Services, and then choose Go (the green button with the arrow).
When the Letters service is displayed on the discovery Page, choose View Service, then in the Web reference name text box, rename localhost to WebService, and then choose Add Reference.

In Solution Explorer, choose Program.cs and replace the existing code with the following code:

using System;
using System.Collections.Generic;
using System.Text;
namespace UsingLettersService
{
    // Imports newly generated web service proxy.
    using WebService;
    class Program
    {
        static void Main(string[] args)
        {
            // Creates a new instance of the service.
            Letters ws = new Letters();           

            // Uses default credentials for authenticating 
            // with Microsoft Dynamics NAV.
            ws.UseDefaultCredentials = true;
            ws.Url = "https://localhost:7047/DynamicsNAV71/WS/CRONUS%20International%20Ltd./Codeunit/Letters";    
            // Declares variables to work with.
            string inputstring, outputstring;   
            inputstring = "microsoft dynamics nav web services!";

            // Calls the Microsoft Dynamics NAV codeunit web service.
            outputstring = ws.Capitalize(inputstring);  
            // Writes output to the screen.
            Console.WriteLine("Result: {0}", outputstring);  
            // Keeps the console window open until you press ENTER.
            Console.ReadLine();     
        }
    }
}

On the Build menu, select Build Solution to build your project and then, from the Debug menu, choose Start Debugging 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.

Next Steps

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 Using a Page Web Service (SOAP).

Share via