Developing with Services and AIF
Important
This content is archived and is not being updated. For the latest documentation, see Microsoft Dynamics 365 product documentation. For the latest release plans, see Dynamics 365 and Microsoft Power Platform release plans.
Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012
Microsoft Dynamics AX supports integration with the Application Integration Framework (AIF) components using the Microsoft Dynamics AX services programming model. You can customize the document services that are included with Microsoft Dynamics AX, create new custom services, and consume external web services. To support a range of option for customization and programmability, Microsoft Dynamics AX provides the following types of services:
Custom Services are services that you create to expose X++ logic through a service interface. You can use the business logic with inbound or outbound transfers.
Document Services represent data and business logic within Microsoft Dynamics AX. You can use or customize the over 70 standard Axd document services that are included with Microsoft Dynamics AX. If none of the standard document services meet your needs, you can create a new document service by using the AIF Document Service Wizard. Each document is represented by a class; the name of a document class is preceded by Axd. For example, AxdSalesOrder is the name of the document and also the name of the document class. The terms "document" and "Axd document" and "document class" are used interchangeably.
System Services cannot be customized. The Query Service, Metadata Service, and User Session Service are Windows Communication Foundation (WCF) services included with Microsoft Dynamics AX. They provide access to data returned in queries, metadata for AOT objects such as tables and extended data types (EDTs), and data about the calling user such as default language and default company.
Microsoft Dynamics AX enables you to consume external web services from X++ code, and to consume web services hosted by Microsoft Dynamics AX from .NET Framework languages such as Microsoft Visual C#.
Security for document services called from an external client is based on the role-based security that is used in Microsoft Dynamics AX. For more information, see About role-based security in services and AIF and Security best practices for services and AIF.
Microsoft Dynamics AX supports application integration and data exchange in both intranet and Internet-facing scenarios. Services based on WCF classes are hosted on the AOS for applications to integrate within the intranet of a company. To consume or expose services over the Internet, you must install and use Internet Information Services (IIS). For more information about Microsoft Dynamics AX web services on IIS see Install web services on IIS.
Distinguishing Between Service Types
The three types of services provided by Microsoft Dynamics AX can be used by Microsoft Dynamics AX components and third-party applications. You can use system services out-of-the-box to retrieve data in a query, metadata for objects in the AOT, and information about the calling user. You can use document services to exchange data for business entities defined by the standard documents in Microsoft Dynamics AX. For any custom requirements for application integration, you can customize existing documents, or create new document services and custom services.
The following table provides information about how to distinguish between the service types, based on deployment and usage parameters.
Document Services |
Custom Services |
System Services |
|
|---|---|---|---|
Service Definition and Data Contracts |
Auto-generated based on underlying query and options entered in the AIF Document Service Wizard. |
Defined by the developer. |
Fixed and cannot be changed. |
Deployment Mode |
Integration Ports |
Integration Ports |
Stand-alone service that is running at fixed address on the AOS |
Hosted Location |
AOS or IIS |
AOS or IIS |
AOS only |
Transport Protocol |
Any supported adapter (for a list of supported adapters, see Adapters) |
Any supported adapter (for a list of supported adapters, see Adapters) |
Only NetTcp adapter |
Usage |
Use to expose a business entity through a service interface. All AIF framework artifacts can be applied on these services. |
Use to expose any custom (including simple business entities) through a service interface. AIF framework supports transforms but not pipelines, schema constraints, or other data processing options. |
Use to return metadata, data in a query, or user information. Metadata includes information about AOT objects in Microsoft Dynamics AX such as tables, services, extended data types (EDTs), enums, and so on. |
Exposing Business Entities as Services
Microsoft Dynamics AX installs with over 70 document services. The document services framework provides the AIF Document Service Wizard that generates a document service from the query that defines the business entity. To expose business logic through services, you use serialization with the Data Contract class and custom attributes.
The following table contains information that can help you to decide whether to use document services or custom data contract–based services.
Characteristic |
Document Services |
Custom Services |
|---|---|---|
Entity complexity |
The AIF Document Service Wizard handles queries of any complexity and size and generates the service seamlessly. For example, some queries contain data sources and relationships that include dimensions, polymorphism, date-effective information, and so on. The document services framework handles these types of queries seamlessly. |
Suitable when the entity complexity is low. The schema can be written as a data contract class and relevant data member attributes set. If tables and relationships are used in a data contract, then any feature around dimensions, polymorphism, and so on, must be handled in code by the developer. |
Performance requirements |
The incoming XML is passed to the document services framework, which parses the XML to validate the AxD schema, and then invokes the relevant operation. The framework enables customization to handle any complex pattern in the underlying query. |
Custom services use the underlying .NET XML Serializer to serialize and de-serialize the XML into a data contract object. No other logic is present. For simple entity schemas, this approach is faster than document services. For complex schemas, you may have to write a lot of custom code. |
Integration requirements |
All integration stack elements such as pipelines, transforms, and schema constraints can be applied to document services. |
Schema constraints and value substitution are not honored for custom services. However, transforms that convert between the AifXMLMessage format and other formats and pipelines for preprocessing and postprocessing of XML messages can be used. |
Flexibility in service contracts |
Because the document service is derived from a query, changes to the query object or the data source schema might require a change the service contract. The tight coupling between the service contract and the underlying query-table schema could be limiting for certain scenarios. |
The data contracts are written by developers and can be controlled to make sure that the underlying schema changes do not have any effect on them. The control that a developer has in defining the service contracts can be good for service clients. |
Microsoft Office Add-ins support |
Office Add-ins tools, included with Microsoft Dynamics AX, have built-in support for consuming document services for updating data. |
No preinstalled integration with Office add-ins exists. |
Common Usage Scenarios
The following table summarizes some of the key scenarios for all the service types in Microsoft Dynamics AX.
Service Type |
Common Scenarios |
|---|---|
Custom Services |
Use to expose very simple business entities as a service, or to expose custom logic from Microsoft Dynamics AX. |
Document Services |
Use to expose business entitles with varying degrees of complexity, or to support medium-to-complex integration scenario involving business entities. |
System Service: Query Service |
Use to implement read operations for any Microsoft Dynamics AX, ad-hoc, or existing AOT query. |
System Service: Metadata Service |
Use to retrieve information about the structures in Microsoft Dynamics AX for a client application. For example, if you want to return information about a table such as what indexes exist on that table, you can use the metadata service. |
System Service: User Session Service |
Use to retrieve information about the user session. |
For more information, see the following white papers: