Microsoft Dynamics AX 2012 already provides a number of services out of the box. These services, together with additional services that can be developed, can be divided into three types. Each of the service types has its own characteristics and a different approach to create it.
Document services use documents to represent business objects such as purchase and sales orders, customers, and vendors.
A document service is composed of the following components:
Document query: This is a query that is created in the Application Object Tree (AOT) and contains all the tables that are related to the business object that you want to expose. Based on this query, the Document Service Generation Wizard can be used to generate the other artifacts that make up the document service.
AxBC classes: This class is a wrapper for a table and contains business logic that is needed for the Create, Read, Update, and Delete (CRUD) operations.
Document class: The purpose of this class is to contain business logic that is associated with the creation and modification of the business entity itself. For example, the
AxdCustomerclass could contain logic to handle a customer's party information.Document service class: This is the actual service implementation class and extends the
AifDocumentServiceclass. This class implements the service operations that are published through the service contract.
When creating document services, developers need to make sure that the business object is mapped correctly to the document query. The document services framework will handle all other things, such as the serialization and deserialization of XML and date effectiveness.
Document services can be deployed using the integration ports and all available adapters can be used.
Custom services were already available in Microsoft Dynamics AX 2009, but support for Extended Data Types (EDTs) was limited, which resulted in developers having to provide custom serialization and deserialization logic. Microsoft Dynamics AX 2012 introduces the concept of attributes.
Attributes provide a way to specify metadata about classes and methods. Two of these attributes are used when creating data contracts: the DataContractAttribute and DataMemberAttribute attributes.
The DataContractAttribute attribute is used to define that a class is a data contract. The DataMemberAttribute attribute is added to methods of data contracts representing data members that have to be exposed. This way of defining data contracts is very similar to other programming languages such as C#.
Support for more complex datatypes such as collections and tables has been added so that these types can be serialized and deserialized without developers having to provide the logic themselves.
In a typical custom service, you will find the following components:
Service contract: A service contract is an X++ class that contains methods with the
SysEntryPointAttributeattribute. This identifies methods that will result in a service operation contract when the service is exposed.Data contracts: A data contract is an X++ class that is attributed with the
DataContractAttributeattribute. It contains parameter methods that will be attributed as data members for each member variable that needs to be part of the data contract.
Custom services can be deployed using the integration ports and any available adapter can be used.
These services are new since the release of Microsoft Dynamics AX 2012. The main difference between these services and the previous two types is that they are not customizable and are not mapped to a query or X++ code. They are not customizable because they are written by Microsoft in managed code. One exception is the user session service, which is written in X++ code but is generally considered as a system service.
There are four system services available for use in Microsoft Dynamics AX 2012: the query service, the metadata service, the user session service, and the OData query service.
The query service provides the means to run queries of the following three types:
When queries are called by a service, the AOS authorization ensures that the caller has the correct permissions to retrieve the information. This means that unpermitted fields will be omitted from the query result. Furthermore, when joined data sources are not allowed to be used, the query call will result in an error that can be caught by the calling application.
The resulting rows will be returned as an ADO.NET DataSet object. This can be very useful when you make use of controls in your application that can be bound to a DataSet object.
The query service can be found at the following link: net.tcp://<hostname:port>/DynamicsAX/Services/QueryService
This system service can be used to retrieve metadata information about the AOT. Consumers of this service can get information such as which tables, classes, forms, and menu items are available in the system. An example use case for this service is when retrieving information about the AOT and using it in a dashboard application running on the Microsoft .NET Framework. We will create an example dashboard application in Chapter 7, System Services, where we will use this service to look up queries in the AOT.
The metadata service can be found at net.tcp://<hostname:port>/DynamicsAX/Services/MetaDataService.
The third system service is the user session service. With this service, you can retrieve information about the caller's user session. This information includes the user's default company, language, preferred calendar, time zone, and currency.
The user session service can be found at the following link: net.tcp://<hostname:port>/DynamicsAX/Services/UserSessionService
The OData query service is a REST-based service that uses the OData protocol to expose the results of a query object in the AOT in an Atom feed. Open Data Protocol (OData) is a web protocol that allows CRUD operations, but the Microsoft Dynamics AX 2012 implementation only supports reading data.
The OData query service can be found at the following link: http://<hostname:port>/DynamicsAX/Services/ODataQueryService
Tip
What is a RESTful web service?
Representational State Transfer (REST) represents a set of design principles by which web services are developed. For more details about REST, you can go to the following link: http://www.ibm.com/developerworks/webservices/library/ws-restful/
Now that it is clear what types of services Microsoft Dynamics AX 2012 has to offer, the question arises as to when each type of service should be used. There is no simple answer for this due to the fact that every type has its strengths and weaknesses. Let us take a look at two factors that may help you make the right decision.
Both document services and custom services can handle any business entity complexity. The document services framework parses the incoming XML and validates it against an XML Schema Definition (XSD) document. After validation, the framework calls the appropriate service action.
Custom services, on the other hand, use the .NET XMLSerializer class and no validation of data is done. This means that any validations of the data in the data contract need to be written in code. Using custom services, you not only have to code all validation, but also all the other business logic. When working with data from the database, this puts custom services at a disadvantage because document services use AxBC and document classes that already contain a lot of the logic needed for CRUD operations.
Document services have service contracts that are tightly coupled with the AOT Query object. This means that when the query changes, the schema also changes. Data policies allow you to control which fields are exposed. When using custom services, this cannot be done by setup, but has to be done at design time.
Custom services have flexibility towards the service contract, while document services lack such flexibility. Here, the developer is in full control of what is in the contract and what is not. The operations, input parameters, and return types are all the responsibility of the developer.
Another benefit of using custom services is the ability to use shared data contracts as parameters for your operations. Think of a company-wide software solution that involves the use of Microsoft Dynamics AX 2012 together with SharePoint and .NET applications that are all linked through BizTalk. You could opt to share data contracts to make sure that entities are the same for all of the components in the architecture.
In that scenario, you're able to create a data contract in managed code and reference it in Microsoft Dynamics AX 2012. Then you can use that .NET data contract in your service operations as a parameter.
There will probably be more factors that you will take into consideration to choose between the service types, but we can come to the following conclusion about when to use which type of service:
Custom services: These should be used when exposing entities that have a low complexity or data contracts that need to be shared between other applications. They are also ideal when custom logic needs to be exposed that may have nothing to do with data structures within Microsoft Dynamics AX.
Document services: These should be used when exposing entities that have high complexity and when validation of the data and structure would require a lot of work for developers to implement on their own.
Query service: This should be used only when read operations are needed and there is no need for updates, inserts, or delete actions. It can be used when writing .NET Framework applications that leverage the data from Microsoft Dynamics AX and are returned as an ADO.NET DataSet.
Metadata service: This service should be used when metadata information about objects in the AOT is required.
User session service: This should be used when user-session-related information is required.
OData query service: The OData query service can be used when you want to expose data from AX over HTTP using the OData protocol. This allows for compatibility with other applications that support OData, such as the PowerPivot add-in for Microsoft Excel.