Sunday, April 22, 2012

AX 2012 Services Document Types - Powerful/Agile/Simple

AX 2012 Services

I have been asked a lot about what's new in AX 2012 for services. I always try to explain my customers in a graphical way so they can see the differences between AX 2009 and 2012.

In this port I would like to point out the main improvements that Microsoft has made to AX 2012 services. In addition, please keep reading my blog this week as I will post about creating services in AX 2012 and how to consume then from C#. I also will post about the specific architecture of AX 2012 services and how it leverage the .NET framework.

In a nutshell, I believe that the improvements to services and AIF in AX 2012, are allowing us to easily create and deploy services. I also think that these improvements are helping AX align with industry standards for web services.

So what are the changes that AX 2012 introduces?

There are two key points on this:

1.       Integration ports for streamlined deployment of the Services and AIF
2.       Provides benefits to system administrators through the following improvements:
o   Services are hosted on the Application Object Server (AOS)
o   IIS service hosting without BC.Net
o   Services as a first class programming model
o   Integration ports
o   Performance improvements in Services and AIF

Now, it is really fair to say that the improvements to the services framework resulted in significant changes in functionality, configuration, database schema, and document schema (XSDs), and II strongly believe that they have helped simplify the setup tremendously.

It is important to point out that as developers/architects we are going to have to really understand the new integration features. Please see below.

o   Support for non-XML file formats: This means any file (boy .. this is good). We just need to create a .NET DLL to convert the files into a structure readable for the services.
o   Out-of-the box integration templates: Microsoft has created 90 out-of-the-box services. In AX 2009, they only had around 50 (if I'm not mistaken).
o   Support for large messages import (10 MB limit removed)
o   Support for flexible error handling on large imports such as rollback and halt

To finish this post I would like to describe the 3 services types that are supported in AX 2012.

Document Services 

One of the most important things to remember about this service type is that each document service is built on top of a query that is used to produce the data contract for that service. Further, the services framework handles scenarios to produce a usable data contract schema. These scenarios are described in the following list:

o   Replacement of Surrogate Foreign Keys (SFK) with Natural Keys
o   Support for Microsoft Dynamics AX Views as part of the data contract
o   Support for Dimensions in the data contract
o   Table Inheritance
o   Date Effectivity
o   Improved document service wizard.

Custom Services 

It is clear by now that AX 2012 aligns itself more with the .NET vision of creating services, in the sense that classes are marked with attributes that define service contracts, data contracts, and data members.

o   Service contracts describe the methods that you want exposed to the end-user.
o   Data contracts declare the data structure that an end-user must comply with, to exchange data with your service.
o   Data members are the individual fields that comprise your data contract.

Let's keep exploring more, a custom AIF service will be an AX class that has some special attributes added before the method declaration. These attributes tell Microsoft Dynamics AX which class methods that you want to expose as service contracts. AX classes exposed as services are declared public and must be registered in the AOT services node. So we have the following two attributes when creating a custom service:

o   Data contracts are typical Microsoft Dynamics AX classes decorated with the [DataContractAttribute] attribute.
o   Data members inside the class must be decorated with the [DataMemberAttribute] attribute.

System Services 

System services are general purpose services that ship as part of the framework. These system services include:

o   Metadata service: We can use this to query for the metadata in our system. We can retrieve metadata for:

o   Labels, menus, tables, extended data types, data types, enums, queries, web menus, information parts, and services.
o   The metadata service should be used when we want to return information about the structures in Microsoft Dynamics AX to a client application. For example, if we wanted to return information about a table such as what indexes exist on that table, you can use the metadata service.

o   Query service: We can use this to issue a query for data without using an AIF document service or creating a custom service. The query service returns data in an dataset and implements a paging mechanism so that we can manage queries that return large amounts of data. When we call the query service, we can specify the query to run in one of three ways:
o   Static query: A query that is already defined in the AOT under the Queries node.
o   User-defined query: A query that is defined by using the QueryMetadata class which is found in the metadata service.
o   Dynamic query: A query that is defined in an X++ class that extends the AifQueryBuilder class. All query logic is contained in the query builder class.

o   User Session service: We can use this so that a client can read configuration properties for the current user like configured language, default company and default currency.

That's all for this post, and remember to come back to read about how to create a service and a more details description on AX 2012 services architecture.

Have a great and productive week!


  1. Thanks for sharing your info. I really appreciate your efforts and I will be waiting for your further write ups thanks once again.

    1. Hi!

      Thanks for reading my blog and your comment. I really appreciate it.

      Yes! This week I'll dive into services and publish some really cool stuff.

      Have a great day, and thanks a lot!

  2. This comment has been removed by the author.

  3. Hi,

    I am trying to deploy Services on windows 7 getting below error

    "The port 'UserSessionService' could not be deployed.\nError:
    error CS0008: Unexpected error reading metadata from file 'c:\Program Files\Microsoft Dynamics AX\60\Server\AX2012Standard\bin\XppIL\Dynamics.Ax.Application.dll' -- 'Index not found.'"

    Can u help me in this.
    This is single environment on windows7(AOS/DB/Client all)

  4. Hi Nagaraj,

    Were you able to resolve this issue?

    Sanjivkumar kori

  5. Hi Nagaraj,

    I have the same problem. Could you solve this problem ?

  6. This comment has been removed by a blog administrator.

  7. This is very nice and informative blog thanks for sharing this informationare Service Contracts fully insured to provide your belongings the extra cushion that they might need during the transit and giving you the peace of mind that your valuable possessions are in good hands.


Thank you for your thoughts. Your comment will appear in my blog shortly after review.

Have a great day!