Microsoft Dynamics AX: Consume an AX AIF Document Service from .NET

This article appears in the Third Party Products and Tools section. Articles in this section are for the members only and must not be used to promote or advertise products in any way, shape or form. Please report any spam or advertising.

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.