Walkthrough: Creating a Web Service using Extension Codeunits

This walkthrough shows how you can publish and consume a Microsoft Dynamics NAV 2009 page as a Web service and how you can extend the default set of operations that are available on a page with codeunit functionality. Adding an extension codeunit to a page is useful if you want to perform operations other than create, read, update, or delete.

This walkthrough illustrates the following tasks:

  • Registering and publishing a page as a Web service.

  • Creating an extension codeunit.

  • Connecting the extension codeunit to the published page.

  • Verifying the service's availability.

  • Calling the Web service from a console application created in Visual Studio.

Prerequisites

To complete this walkthrough, you need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • The CRONUS International Ltd. demo data company.

  • 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.

You register and publish a Web service using the RoleTailored client.

To register and publish a page as a Web service

  1. Open the RoleTailored client and connect to the CRONUS International Ltd. demonstration company.

  2. In the navigation pane, click Departments, click Administration, click IT Administration, click General, and then click Web Services.

  3. In the Web Services page, click New.

  4. In the Object Type column, select Page, and then enter 21 in the Object ID column ID and PageWithCapitalization in the Service Name column.

  5. Click to select the field in the Published column.

  6. Click OK to close the New - Web Services page.

    Do not close the RoleTailored client or navigate away from the Web Services page.

After you publish the page, you create a codeunit that extends its functionality. Follow the steps in this procedure to create a codeunit called CapitalizeName, which takes a customer name as input and outputs the same customer name capitalized. The codeunit must take the record type of the page as the first parameter.

To create an extension codeunit

  1. Open the Classic client and connect to the CRONUS International Ltd. demonstration company.

  2. On the Tools menu, click Object Designer.

  3. In Object Designer, click Codeunit, and then click New.

  4. On the View menu, click C/AL Globals.

  5. In the C/AL Globals window, click the Functions tab, and then enter CapitalizeName as the name of the function.

  6. From the C/AL Globals window, click the Locals button.

  7. On the Parameters tab, enter Cust in the Name field, and then select Record in the DataType field.

  8. In the SubType field, click the arrow to open the Table list window and select Customer.

  9. Click OK to close the Table list window.

  10. Close the C/AL Locals window, and then close the C/AL Globals window.

  11. In the CapitalizeName method, insert the following lines of code:

    Cust.Name := UPPERCASE(Cust.Name); 
    Cust.MODIFY(TRUE);
    
  12. Close the C/AL Editor.

  13. When prompted, give the codeunit the ID 50012 and the name CapitalizeName.

After the codeunit is created and saved, register it under the published page so that the codeunit extends the published page. The codeunit itself should not be marked as Published.

To connect the codeunit to the exposed page

  1. Switch back to the RoleTailored client and the Web Services page.

  2. Click New.

  3. In the Object Type field, select Codeunit, and then select object ID 50012. In the Service Name field, enter PageWithCapitalization, which is the same name that you gave the page Web service.

  4. Clear the Published check box.

  5. Click OK to close the New - Web Services page.

You should verify that the Web service is available to consumers. Start the Microsoft Dynamics NAV Business Web Services service, and then browse to the WSDL document to ensure that your Web service is available.

NoteNote

When exposing a Web service, you must open the port for other consumers of your Web service to access it. Have your system administrator add 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

  1. Click Start on the computer, point to All Programs, point to Administrative Tools, and then click Services.

  2. Right-click Microsoft Dynamics NAV Business Web Services, and then click Start on the shortcut menu.

  3. Close the window.

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 Web service

  1. Start Internet Explorer.

  2. 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

    NoteNote

    The company name is optional and case-sensitive.

    The page should list the Web services that you have published: Page/PageWithCapitalization and Codeunit/PageWithCapitalization.

  3. Close the browser.

Now you can create an application that uses both the page and the codeunit Web services. When you add a reference in Visual Studio, methods from both the page and the extension codeunit are available.

To call the Web services

  1. In Visual Studio, on the File menu, point to New, and then click Project.

  2. Expand the Visual C# node, select Windows, and then, under Visual Studio installed templates, select Console Application. Enter the name UsingExtensionCodeunit for the application.

    The sample code in this walkthrough expects this exact application name, so do not change it.

  3. Click OK to close the New Project page.

  4. In Solution Explorer, right-click the References node in the project, and then click Add Service Reference.

    NoteNote

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

  5. 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.

    NoteNote

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

  6. When the services are displayed, select the Page service (Page/PageWithCapitalization). Do not select the Codeunit service (Codeunit/PageWithCapitalization). Then click View Service.

  7. Rename localhost to WebService, and then click Add Reference.

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

    using System;
    using System.Collections.Generic;
    using System.Text;
    
    namespace UsingExtensionCodeunit
    {
        using WebService;
    
        class Program
        {
            static void Main(string[] args)
            {
                // Create instance of service and set credentials.
                PageWithCapitalization_Service service = new PageWithCapitalization_Service();
                service.UseDefaultCredentials = true;
                
                // Create instance of customer. 
                PageWithCapitalization cust = new PageWithCapitalization();
                cust.Name = "Louis Taylor";
                
                // Insert customer using the default operation.
                service.Create(ref cust);
                Console.WriteLine(cust.Name);
    
                // Call extension codeunit to capitalize customer name.
                service.CapitalizeName(cust.Key);
                        
                // Refresh customer.
                cust = service.Read(cust.No);        
                Console.WriteLine(cust.Name);
                Console.ReadLine();
                service.Delete(cust.Key);
            }
        }
    }
    
  9. Press F5 to run the application in debug mode. You should now see a console window that creates a new customer using a default page operation and then capitalizes the customer name using the extension codeunit.

Community Additions

ADD
Show: