Introduction
This article shows how a .NET client (in our case Windows Client) can consume an AX WCF document service. For this purpose, the service will be hosted on the AOS (Application Object Server) instead of IIS.
Scope
We take the class room (course rooms) administration module as an example. We want to expose a (document) service which makes it possible for external clients to exchange data (CRUD-operations) with AX.
Steps
The remainder of the document explains the different steps to meet our goals. This post assumes that the reader has some experience with the AX AIF (Application Integration Framework) which means that next steps briefly explains the creation, deployment and consumation of an AX document service.
Step 1: Create a document query
Each document service is based on a document query stored in the AOT (Application Object Tree) in AX. This document query holds the appropriate data objects which will be exposed by the service. The datasources of the document query will be exposed by the (WCF) service which will contain the appropriate XML message schema.
Step 2: Create a document service
The wizard takes the created document query (from the previous step) as input parameter and will create a corresponding service class (details omitted). This service class hosts the different methods to invoke CRUD (Create; Read; Update; Delete) operations on the datasource (in our case Course Rooms).
Step 3: Check generated service project
The service wizard created a service project. Besides the service itself, the project contains the service query, the service document class, and the data classes which hold the actual data. What’s interesting is that the service wizard also created a job: GenerateXSDSchema_AxdEMNU_AxdHRMCourse which provides the XML that will be sent over the wire to the consuming client. When you execute the job, you will get the corresponding XML file, as shown below:
Step 4: Expose the document service as a WCF WebService
Create an (enhanced) inbound port for the service (use inbound ports for messages which originate from within AX and should be consumed by external clients). In our demo case, we will expose the service as a tcp-ip service, which will be consumable by external clients from within the scope of the intranet. (If the service should be consumable from the internet, we should choose the Http adapter instead).
Step 5: Select the appropriate service operations
Once you have created an integration port, you must select the service operations which can be invoked by the consuming client.
Step 6: Consume the exposed document service by an external (.NET) client
The service can be consumed by an external client (in our case, a .NET winforms application) … but could be any other type of application … Just below, I briefly explain the interaction code within the .NET client (code executed when the user selects the load or save button). In our demo case, we expose the find, create, update & delete methods.
Step 6.1: .NET Winforms client
The service will be consumed by a simple (C#) .NET client. The client will load the data into a datagrid, make changes to the data (CRUD operations) and submit those changes to AX.
Step 6.2: Load data in .NET client
When the users “clicks” the “Load” button, next will happen:
- Set query criteria, in our case we will return all course rooms.
- Set the company from which data will be loaded.
- Call the repository
GetCourseRooms() method which returns all rooms from AX.
Step 6.3: Save the changes to AX
When the user “clicks” the “Save” button, next will happen:
- Apply last changes to the current
dataset (.NET DataSet holds the AX records) - Get all added, modified & deleted rows
- Call the repository
SaveCourseRooms() method which will update the data to AX.
.NET Data Repository
Implementing the "find" method in the repository class
Implementing the "create, update & delete" method in the repository class
