Walkthrough: Creating and Interacting with a Page Web Service (OData)

Article
10/08/2019

This walkthrough illustrates how you can publish a Dynamics NAV page as an OData V3 web service, use it in a Visual Studio console application, and change data in Dynamics NAV through the web service.

About This Walkthrough

This walkthrough provides an overview of how to expose a page as a web service and how to use the web service in a C# console application. The walkthrough illustrates the following tasks:

Publishing a Dynamics NAV page as a web service.
Verifying web service availability from a browser.
Adding the published web service as a service reference in a console application that you create in Visual Studio.
Changing the data in the console application.

Prerequisites

To complete this walkthrough, you will need:

Microsoft Dynamics NAV 2018 with a developer license.
CRONUS International Ltd. demonstration database.
ODate Services and V3 Endpoint enabled on the Microsoft Dynamics NAV Server.
Visual Studio 2015 or later.

You can use any edition of Visual Studio that supports adding web references. In this walkthrough, you will use Visual Studio 2017. You also have the option to use service references instead of web references, or use the web service proxy generating tools svcutil.exe and wsdl.exe, which are included in the Microsoft .NET Framework SDK.
OData Connected Service installed in Visual Studio.

This tool generates code to facilitate the consumption of OData services. To install OData Connected Service you can either download it from OData Connected Service and follow the instructions, or do the following in Visual Studio:
1. On the Tools menu, select Extensions and Updates > Online
2. Search for OData Connected Service, select it in the results, and choose Download.
3. Close Visual Studio to start the installation.

Publishing a Page as a Web Service

You publish a web service by using the Microsoft Dynamics NAV Windows client or the Microsoft Dynamics NAV Web client.

Open the client and connect to the CRONUS International Ltd. company.
In the Search box, enter Web services, and then choose the related link.
In the Web Services page, choose New.
In the Object Type column, select Page. In the Object ID column, enter 21, and in the Service Name column, enter Customer.
Select the check box in the Published column.
Choose the OK button.

Verifying Web Service Availability

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 OData web services is 7048. You can configure this value by using the Microsoft Dynamics NAV Server Administration Tool.

Start an Internet browser.
In the Address field, enter the Dynamics NAV OData endpoint.

The endpoint has the format: https://<Server>:<WebServicePort>/<ServerInstance>/OData. For example:

https://localhost:7048/DynamicsNAV/OData
- Server is the name of the computer that is running Microsoft Dynamics NAV Server.
- WebServicePort is the port that OData is running on. The default port is 7048.
- ServiceInstance is the name of the Microsoft Dynamics NAV Server instance for your solution. The default name is DynamicsNAV110.
  
  The browser should show the web services that you have published, including the Customer, in a format of an AtomPub document:

Creating the Console Application

Next, you create a C# console application in Visual Studio. The console app will return a list of customers from Dynamics NAV and create a new customer.

Create the C# project

In Visual Studio, on the File menu, point to New, and then choose Project.
In the pane on the left, select Installed > Visual C# > Windows (Classic) Desktop > Console App (.NET Framework).
Set the Name and Solution Name for the application to Customers , and choose OK to exit the New Project page.

Add a connected service for the OData web service

In the Solution Explorer pane, right-click the Customers project, and then choose Add > Connected Service.
On the Configure Endpoint page, you can keep the Service name of OData Service or change it as you like.
In the Address field, enter the endpoint URI for your OData web service.

This is the endpoint that you verified in an earlier step. The endpoint has the format https://<servercomputer>:<odataport>/<serverinstance>/OData/, for example:

https://localhost:7048/DynamicNAV/OData/

Important

In this example, we use the HTTP protocol to illustrate the use of OData web services. We recommend that you use the more secure HTTPS protocol when you consume web services.
Choose Next.
On the Settings page, you can keep the file name Reference or change it as you like.

The project is created, and your OData web service is added as a connected service reference. Next, you add the code that will show a list of existing customers, add a customer and then rename the new customer.

Add code to the console application

In the program.cs file of your solution, add the using statement after the namespaces that are automatically added to your project:
```
using NAV;  
```

After the Main method, add the following method to return a list of customers whose name start with Cust:

private static void PrintCustomersCalledCust(NAV.NAV nav)  
  {  
    var customers = from c in nav.Customer  
                    where c.Name.StartsWith("Cust")  
                    select c;  

    Boolean customerFound = false;  
    foreach (Customer customer in customers)  
    {  
      customerFound = true;  
      Console.WriteLine("No.: {0} Name: {1}", customer.No, customer.Name);  
    }  

    if (!customerFound)  
    {  
      Console.WriteLine("There are no customers that start with 'Cust'.");  
    }  
  }

The PrintCustomersCalledCust method reads the OData web service that you created, Customer, and creates a list of customers where the customer name begins with the letters Cust. Next, you add code to the Main method that uses the web service to write to Dynamics NAV.

In the Main method, add the following code to establish the connection to Dynamics NAV through the OData web service:
```
NAV.NAV nav = new NAV.NAV(new Uri("https://localhost:7048/DynamicsNAV/OData/Company('CRONUS%20International%20Ltd.')"));
nav.Credentials = System.Net.CredentialCache.DefaultNetworkCredentials; 
```
This implementation will authenticate users on their Windows credentials.

In the example, the name of the Dynamics NAV company that you modify data for is CRONUS International Ltd.. You must replace this with the name of the company that you have access to. To find the correct URI, you can paste the following URI into your browser and then see the exact URI that you must use: https://localhost:7048/DynamicsNAV/OData/Company.

Add the following code to the method:

Console.WriteLine("Printing list of current customers:");  
PrintCustomersCalledCust(nav);  

Console.WriteLine("Adding new customer.");  
Customer newCustomer = new Customer();  
newCustomer.Name = "Customer Name";  
nav.AddToCustomer(newCustomer);  
nav.SaveChanges();  

Console.WriteLine("Printing list of current customers:");  
PrintCustomersCalledCust(nav);  

newCustomer.Name += "Changed";  
nav.UpdateObject(newCustomer);  
nav.SaveChanges();  

Console.WriteLine("Printing list of current customers:");  
PrintCustomersCalledCust(nav);

In this code, the customer is created and then renamed. The code prints a list of the customers that currently exist in the Customer table when each change has been made.

Build and run the project.

To verify the inserted and modified data in Dynamics NAV

Open the Microsoft Dynamics NAV Windows client or the Microsoft Dynamics NAV Web client.
Open the list of customers, filter for a customer with the name Customer NameChanged.

This is the customer that the console application created.

Next Steps

You have built a console application that uses an OData web service to modify Dynamics NAV data. You can use similar OData web services in other applications when you want to allow users to modify data outside Dynamics NAV.