Create Your First Custom Service [AX 2012]

As AX has advanced, so has its integration with WCF. One of the good concepts that MS has introduced in AX 2012 is custom services.
With custom services, anything and everything in AX can be exposed as Windows Communication Framework (WCF) service. This article concentrates on helping you create your first custom service.
For creating and exposing custom service, following steps are involved:

1. Create a DataContract class (If required. In this example we will skip this step. I will include this in next article)
2. Create a custom service class that utilizes the DataContract class and contains the required Business Logic
3. Create a new Service utilizing service class
4. Add the Service to service group
5. Deploy the service group
6. Verify the deployment ports
7. Consume in Visual Studio (C#)

Let us see how we can achieve this.
Simple Scenario: The scenario we will take in this examples is customers. We will write a service to fetch all customers from default company. Add these customers to a list. Now select a subset of customers, pass it back to Ax and get their names. With this we can see how we can set and get an array of values.
Create Custom Service Class
Do the following:

• In AOT –> Classes node, right click and create new class
• Name it as SamCustomServiceTest

/// <summary>

/// Custom service class to demonstrate the creation and consumption of WCF services from AX

/// </summary>

/// <remarks>

/// This is the custom service class for fetching customer ids and customer names

/// </remarks>

class SamCustomServiceTest

{

}

• Add a service operation method to retrieve customer ids as shown below

/// <summary>

/// Gets a list of customer ids from the specified company

/// </summary>

/// <returns>

///  List of customer Ids

/// </returns>

/// <remarks>

/// AifCollectionTypeAttribute is used to define strongly typed containers for data

/// </remarks>

[AifCollectionTypeAttribute(‘return’, Types::String), SysEntryPointAttribute(true)]

public List retrieveCustomerIds()

{

    List resultSet = new List(Types::String);

    CustTable   custTable;

    while select custTable

    {

        resultSet.addEnd(custTable.AccountNum);

    }

    return resultSet;

}

• Add a service operation method to retrieve a combination of “Customer Ids and names” for the supplied list of customers as shown below

/// <summary>

/// Gets a list of customer ids from the specified company

/// </summary>

/// <param name=”_custList”>

/// The list of customer ids; Mandatory

/// </param>

/// <returns>

///  List of customer Ids

/// </returns>

/// <remarks>

/// AifCollectionTypeAttribute is used to define strongly typed containers for data

/// </remarks>

[SysEntryPointAttribute(true),

 AifCollectionTypeAttribute(‘return’, Types::String),

 AifCollectionTypeAttribute(‘_custList’, Types::String)]

public List retrieveCustomerNames(List _custList)

{

    ListEnumerator  listEnum = _custList.getEnumerator();

    List resultSet = new List(Types::String);

    CustTable   custTable;

    while (listEnum.moveNext())

    {

        select firstOnly custTable

            where custTable.AccountNum == listEnum.current();

        if (custTable)

        {

            resultSet.addEnd(custTable.AccountNum + “: “+ custTable.name());

        }

        else

        {

            resultSet.addEnd(listEnum.current() + “: Customer not found”);

        }

    }

    return resultSet;

}

Note: There are many metadata attributes specifed here. The first one is the AifCollectionTypeAttribute. This class has been developed to create strongly typed collections for data that you need to communicate. Here the return type if List (A collection object). AifCollectionTypeAttribute defines the type of data the list holds. When this service operation is exposed, the return type for the operation will be corresponding data type array (in this case a string array). The SysEntryPointAttribute indicates what authorization checks are performed for a method that is called on the server. This attribute must be set for all service operations. Value ‘true’ indicates authorization checks are performed on the calling user for all tables accessed by the method. Value ‘false’ indicates authorization checks are not performed on any tables accessed by the method. (You may have noticed that processReport method for any Data Provider class has this value set to false).
The service operations should not be named as create, read, update delete, find etc. These names are exclusively reserved for methods on AIF Service classes. If you use these method names in your custom service, you will face errors while deploying them.
Create Custom Service

• In AOT –> Services Right click and add new service
• Name the service as SamCustomService, ExternalName = SamCustomService and specify Class = SamCustomServiceTest

• Expand the newly created service node.
• Right click on operations and select “Add service operations”
• This opens an intermediate form, select both the service operation methods

Save the service and your service is ready now.

Create and Deploy Service Group

• In AOT –> Service Groups Right click and add new service group
• Name the group as SamCustomServiceGroup, Description = “Custom services for test” and AutoDeploy = Yes (Starts this service every time that the AOS is restarted)
• Save the service group and then right click and Select “New Service Node Reference”
• Type Name = SamCustomService and Service = SamCustomService
• Save the Service group
• Right click and select “Deploy Service Group”

Verify the Deployment

• Open the Inbound ports form from System Administration –> Setup –> Services and Application Integration Framework –> Inbound ports.
• Ensure that the SamCustomServiceGroup has a green check mark next to it. This means the port is active. If it is not, select SamCustomServiceGroup and then click Activate to activate the basic port.
  
• You an use IE to view the WSDL file at the address specified in WSDL URI field of the Inbound ports form.

Consuming Custom Service in Visual Studio (C#)
Now that the custom service is ready, let us go ahead and use that in a .Net Application. For that open your Visual Studio 2008 or 2010 development environment and do the following

• Create new project of Type “Windows Application” for language Visual C#

• Add a new form and then add two buttons and two List boxes as depicted below

• In the solution explorer for the new project, select Service References node and right click. Click on “Add Service Reference”
• In the subsequent dialog box set following: Address = WSDL URI from inbound port
• Click on Go. This will display the available services from the port
• Select SamCustomService and set Namespace = SamCustomAXService
• Click Ok

• Now double click on first button “Get Customers” and add following code there

private void button1_Click(object sender, EventArgs e)

{

    SamCustomAXService.SamCustomServiceClient servClient = new SamCustomAXService.SamCustomServiceClient();

    string[] custIds = servClient.retrieveCustomerIds(new SamCustomAXService.CallContext());

    listBox1.Items.Clear();

    foreach (string custId in custIds)

        listBox1.Items.Add(custId);

}

• Now double click on second button “Get Select Cust Names” and add following code

private void button2_Click(object sender, EventArgs e)

{

    SamCustomAXService.SamCustomServiceClient servClient = new SamCustomAXService.SamCustomServiceClient();

    string[] strItem = null;

    int i = 0;

    strItem = new string[listBox1.SelectedItems.Count];

    //Get selected customer ids and prepare a string array

    foreach (Object selecteditem in listBox1.SelectedItems)

    {

        string item  = selecteditem as string;

        strItem[i++] = item;

    }

    //Use the string array to get the “Customer Id: Customer Name” Combo data

    string[] custIds = servClient.retrieveCustomerNames(new SamCustomAXService.CallContext(), strItem);

           

    listBox2.Items.Clear();

    foreach (string custId in custIds)

        listBox2.Items.Add(custId);

}

• Now run the application, click first button “Get Customers”. The first list box fills up, then select some customers and click second button “Get Select Cust Names”. The second list box fills up as well

This concludes the session on creating custom services. To conclude, this is something really cool that MS has introduced in AX. Happy servicing the AX guys . Next stop Data Contracts in Services.