Chapter 5: Services and Application Integration

CHAPTER 5: SERVICES AND APPLICATION

INTEGRATION
Objectives
The objectives are:

Understand how clients can use services to interact with Microsoft

Dynamics AX 2012 and retrieve system information.

Learn how integration ports help to streamline service deployment.

Learn about the architectural changes in the Services and Application

Integration Framework (AIF).

Introduction
In Microsoft Dynamics AX 2012, improvements to the Services and Application
Integration Framework (AIF) allow for easier creation and deployment of
Services and align Microsoft Dynamics AX Services with industry standards for
web services. Microsoft Dynamics AX 2012 introduces integration ports for
streamlined deployment of the Services and AIF and provides several benefits to
system administrators through the following features and improvements:

Services hosted on the Application Object Server (AOS)

IIS service hosting without BC.Net

Services as a first class programming model

Integration ports

Performance improvements in Services and AIF

In Microsoft Dynamics AX 2012, improvements to the services framework result

in significant changes in functionality, configuration, database schema, and
document schemas (XSDs) and help simplify the setup. Some of the new
integration features are as follows:

Support for non-XML file formats

Out-of-the box integration templates

Support for large messages import (10 MB limit removed)

Support for flexible error handling on large imports such as rollback

and halt

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

5-1

What's New - Technical in Microsoft Dynamics AX 2012 for Development

Services
All Microsoft Dynamics AX services are Windows Communication Foundation
(WCF) based services that clients can use to interact with and retrieve system
information. In Microsoft Dynamics AX 2012 the following three service types
are supported:

Document services

Custom services

System services

Document Services
In Microsoft Dynamics AX 2012, the services framework is improved to use
several of the infrastructure features added in Microsoft Dynamics AX. Each
document service is built on top of a query that is used to produce the data
contract for that service. The services framework handles scenarios to produce a
usable data contract schema. These scenarios are described in the following list:

Replacement of Surrogate Foreign Keys (SFK) with Natural Keys

Support for Microsoft Dynamics AX Views as part of the data

contract

Support for Dimensions in the data contract

Table Inheritance

Date Effectivity

Improved document service wizards

Custom Services
AIF in Microsoft Dynamics 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. Service contracts describe
the methods that you want exposed to the end-user. Data contracts declare the
data structure that an end-user must comply with, to exchange data with your
service. Data members are the individual fields that comprise your data contract.
An AIF service is a Microsoft Dynamics 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.
Microsoft Dynamics AX classes exposed as services are declared public and
must be registered in the AOT services node.
Data contracts are typical Microsoft Dynamics AX classes decorated with the
[DataContractAttribute] attribute. Data members inside the class must be
decorated with the [DataMemberAttribute] attribute.

5-2

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

Chapter 5: Services and Application Integration

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

Metadata service: You can use this to query for the metadata in
your system. You can retrieve metadata for labels, menus, tables,
extended data types, data types, enums, queries, web menus,
information parts, and services. The metadata service should be used
when you want to return information about the structures in
Microsoft Dynamics AX to a client application. For example, if you
wanted to return information about a table such as what indexes exist
on that table, you can use the metadata service.

Query service: You 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 ADO.net dataset and implements a
paging mechanism so that you can manage queries that return large
amounts of data. When you call the query service, you can specify
the query to run in one of three ways:
o
o
o

Static query: A query that is already defined in the AOT under

the Queries node.
User-defined query: A query that is defined by using the
QueryMetadata class which is found in the metadata service.
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.

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

Service Groups
With services you can expose business logic that is written in X++ as a service to
be consumed by other applications. The introduction of a service group to the
AOT helps to make the management of services easier. In earlier Microsoft
Dynamics AX releases services are managed at an individual service level. The
service group is a collection of services that are frequently consumed and
managed together. All services in a service group are published in a single Web
Services Definition Language (WSDL). You only have to add a reference to a
single WSDL to gain access to the service proxies of all the services in that
service group. Service groups activate type sharing for types that are common
across various services in a service group. For example, if two services within the
same service group take a parameter of type Address, that type is shared between
the two and can be seamlessly passed between the two services.

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

5-3

What's New - Technical in Microsoft Dynamics AX 2012 for Development

You must add your service to a service group to make the service available for
client consumption. Individual services cannot be published by themselves.
A developer can create a service group in the AOT. When creating service
groups, developers can use the AutoDeploy property to decide whether a service
group is deployed and activated when it is created. You must manually deploy
and activate service groups that are not automatically activated by developers.

FIGURE 5.1 AOT SERVICE GROUPS

Procedure: Create a Service

To create a service from custom X++ code, follow these steps:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

5-4

Open the AOT .

Create a new class.
Enhance the class by adding the [DataContractAttribute] attribute.
Create a new method.
Enhance the class by adding the [DataMemberAttribute]attribute.
Create another class.
Create a method that instantiates the class created in Step 2.
Enhance the class that uses the [SysEntryPointAttribute] attribute.
Right-click the Services node in the AOT and select New Service.
Enter a name into the Name property.
Set the Class property to the class created in Step 6.
Expand the new service node.

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

Chapter 5: Services and Application Integration

13. Right-click the Operations node and select Add Operations.
14. Right-click the Services Group node in the AOT and select New
Service Group.
15. Enter a name into the Name property.
16. Drag-and-drop the service created in step 9 under the service group
node.
17. Right-click the service group and select Deploy service group.

Procedure: Use the Service

To use the service in Visual Studio, follow these steps:
1. Select File > New > Project to create a new project of type Console
Application.
2. Enter a name into the Name field and then click OK.
3. Right-click the Service reference node under the project.
4. Select Add Service Reference.
5. Enter the address and then click GO.
NOTE: The address format is
http://<machinename>:8101/DynamicsAx/Services/Xpp.
6. Select the service and then click OK.
7. Invoke the service from the client.
8. Click F5 to run the service.

Procedure: Debug the Service

To debug the X++ code from Visual Studio, follow these steps:
1. Make sure that the "Enable just my code" is unchecked in Tools >
Options > Debugging > General.
2. Make sure that "Attach to Process:" is set to Managed (v4.0) code.
3. Attach to Ax32Serv.exe.
4. Open the X++ method from the Application Explorer.
5. Select a line and press F9 to set the breakpoint.
6. Click F5 .
7. Verify the process stops at the breakpoint within the X++ code.

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

5-5

What's New - Technical in Microsoft Dynamics AX 2012 for Development

Lab 5.1 - Create a Service

In this lab you will review how to create a service from custom X++ code so that
the functionality that is provided by the X++ code is made available from
managed code and works with concepts such as data contracts and attributes.
Scenario
Isaac, the Developer, wants to create a web service that returns an address in X++
code.

Challenge Yourself: Create the Service

Use the information that is provided to create a web service in X++ code that
returns an address.

Challenge Yourself: Create the C# Project

Use the information that is provided to create a Console Application that uses the
service created in the previous steps.

Need a Little Help?

1.
2.
3.
4.
5.
6.

Create a new Data Contract class.

Create a new Service class.
Create a new Service and add Operations.
Create a Service Group and link the service to the service group.
Create a new project in Visual Studio and add the service reference.
Invoke the service from the client.

Step by Step: Create the Data Contract Class

1.
2.
3.
4.
5.

5-6

Open Microsoft Dynamics AX 2012.

Open a Developer workspace.
Open the AOT.
Create a new class named AddressFinder.
Enhance the class by adding the [DataContractAttribute] attribute.

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

Chapter 5: Services and Application Integration

6. Enter a method called Address which returns the address.
7. Enhance the method by adding the [DataMemberAttribute]
attribute.
[DataMemberAttribute]
public str address()
{
return "Demo Address";
}

Step by Step: Create the X++ Service Class

1. Create a new class named AddressUtility. This is the service class.
2. Create a public method named getNearestLocation. This method
instantiates the AddressFinder object and returns the
AddressFinder object.
3. Enhance the class by adding the [SysEntryPointAttribute] attribute.
[SysEntryPointAttribute]
public AddressFinder getNearestLocation()
{
AddressFinder addressFinder = new AddressFinder();
return addressFinder;
}

Step by Step: Create the Service

1. Right-click the Services node in the AOT and select New Service.
2. Change the Name property to AddressService.
3. Set the Class property to AddressUtility.

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

5-7

What's New - Technical in Microsoft Dynamics AX 2012 for Development

4. Expand the AddressService service node.
5. Right-click the Operations node and select Add Operations.

FIGURE 5.2 ADD SERVICE OPERATIONS

6. Check the Add checkbox and click OK.

7. Right-click the Services Group node in the AOT and select New
Service Group.
8. Change the Name property to AddressServiceGroup.
9. Drag the service under the service group node.
10. Right-click the AddressServiceGroup service group and select
Deploy service group.

Step by Step: Create the C# Project

1. Open Visual Studio.
2. Select File > New > Project to create a new project of type Console
Application.
3. Enter AddressImportDemo into the Name field and then click OK.
4. Right-click the service reference node under the project.

5-8

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

Chapter 5: Services and Application Integration

5. Select Add Service Reference.
6. Enter the address and then click GO.

FIGURE 5.3 ADD SERVICE REFERENCE

NOTE: The address format is

http://<machinename>:8101/DynamicsAx/Services/AddressServiceGroup.
7. Select the service and then click OK.
8. Invoke the service from the client.
public static void Main(string[] args)
{
ServiceReference1.AddressServiceClient client = new
ServiceReference1.AddressServiceClient();
AddressFinder address =
client.getNearestLocation(null);
Console.WriteLine(address.address);
Console.ReadLine();

9. Click F5 to run the service.

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

5-9

What's New - Technical in Microsoft Dynamics AX 2012 for Development

Inbound and Outbound Ports

In Microsoft Dynamics AX 2012, integration ports provide simplified
administration of services and simplified administration of the Application
Integration Framework (AIF). The concept of integration ports consists of the
concept AIF endpoints and related configuration forms in earlier releases of
Microsoft Dynamics AX. An integration port is either an inbound port or an
outbound port. External applications consume an inbound port. An outbound port
is a destination for XML messages originating from the Microsoft Dynamics AX
system. Both inbound and outbound ports can be either basic or enhanced.

Basic Integration Port

A basic port can be an inbound or an outbound port. A basic port is an integration
port that is exposed at a specific Windows Communication Foundation (WCF)
endpoint on the AOS host. When developers create an automatically deployed
service group in the AOT, a basic inbound port is created and associated with the
service group being deployed. Some basic ports, such as the basic ports that are
used for system services, are always deployed and enabled by default.

Enhanced Integration Port

For advance integration capabilities, you must create an enhanced integration
port. An enhanced inbound or outbound port is an integration port. With this type
of port, you can group and administer multiple services as a single unit. An
enhanced port offers the following additional capabilities compared to a basic
integration port, and can:

Associate multiple services with the enhanced integration port.

Restrict service and data contracts. This is achieved by applying

service operation and operation parameter constraints.

Have extensible pre- and post-processing of the service requests and

service responses.

Host services on the AOS and IIS.

Support for Non-XML Files

AIF now supports the import and export of data in non-XML formats. This
means that you can import a file that is not XML, for example, a commadelimited or tab-delimited file. This feature provides developers the ability to
create custom transformations that are used to import non-XML data and
transform it into a format that can be consumed by the AIF document services.
The custom transformations can be implemented by using an XSLT or a .NET
DLL that implements the ITransform interface.

5-10

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

Chapter 5: Services and Application Integration

Troubleshoot Services and AIF
In Microsoft Dynamics AX 2009, the troubleshooting and logging of the AIF is
performed at the service operation level. In Microsoft Dynamics AX 2012,
services and the AIF troubleshooting and logging is performed at the integration
port level.

Architecture
Windows Communication Foundation (WCF) Adapter
This release of Microsoft Dynamics AX provides expanded support for WCF
beyond the basic HTTP and HTTPS bindings. The proprietary Microsoft
Message Queuing (MSMQ) and BizTalk Server adapters provided in the earlier
releases of Microsoft Dynamics AX are removed. Microsoft Dynamics AX 2012
provides equivalent functionality through the native WCF functionality.
NOTE: Custom adapters developed by customers and partners using the AIF
adapter framework remain supported in this release.

Services hosted on the Application Object Server (AOS)

The AOS is the WCF service host for Microsoft Dynamics AX 2012 services.
The AOS-hosted services are available to users and applications across the
intranet. To consume services over the Internet, you must host services on
Internet Information Services (IIS).
All the Microsoft Dynamics AX services hosted by the AOS are contained in a
single Web Services Definition Language (WSDL) file. This is also known as the
root WSDL. When adding a reference to a service from Visual Studio, use the
single WSDL.

Microsoft Dynamics AX SOAP Headers

In Microsoft Dynamics AX 2012, Simple Object Access Protocol (SOAP)
headers are extended. You can add these SOAP headers when calling a service to
pass data into the service. The following SOAP headers are supported:

Company: The calling users default company.

Company Time Zone: The calling users default company time

zone.

Currency: The currency associated with the users default company.

Language: The calling users default language.

Logon As Guest: Connects to the service with guest privileges. The

guest account must be activated in Microsoft Dynamics AX for the
service call to be successful.

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

5-11

What's New - Technical in Microsoft Dynamics AX 2012 for Development

Logon As User: Allows a client using BC.NET proxy credentials to

connect to the service as the specified Microsoft Dynamics AX user.

Preferred Calendar: The calling users preferred calendar.

User Time Zone: The calling users time zone.

Data Contract
Microsoft Dynamics AX supports the use of .NET and X++ types as data
contracts for service operation input and return parameters. You can pass
complex data types without having to explicitly implement XML serialization
and deserialization from them. The data contract serialization and deserialization
is now handled by Windows Communication Foundation (WCF). X++ provides
support for data contract functionality through the DataContractAttribute and
DataMemberAttributeattributes. Any .NET type that is serializable by WCF can
be used as a parameter or return type by a service in Microsoft Dynamics AX
2012.
NOTE: By default, WCF uses the DataContractSerializer to serialize and
deserialized data.

Business Operation Framework

With Business Operation Framework (BOF) you can execute business operations
synchronously or asynchronously. A business operation is a service operation
exposed from the AOS. BOF provides various methods for invoking business
operations from Microsoft Dynamics AX facilities, such as menu items and the
batch framework.
NOTE: The RunBase framework is still supported in Microsoft Dynamics AX
2012. However, it is recommended to use the new Business Operation
Framework instead because it provides a clean separation between the data
contract, user interface and the service operation.

Installation Considerations
In Microsoft Dynamics AX 2012, the Windows Communication Foundation
creates a dynamic WSDL based on the service contract for each service group or
integration port. With appropriate planning, you can have a single WSDL to
expose all the necessary services that are required for a specific integration
scenario.

5-12

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

Chapter 5: Services and Application Integration

Upgrade Considerations
When planning an upgrade from earlier releases of Microsoft Dynamics AX,
consider the following points.

You must recompile and test all interfaces that used the earlier
release of Microsoft Dynamics AX to work with services in
Microsoft Dynamics AX 2012.

Microsoft Dynamics AX 2012 replaces BizTalk adapters with

equivalent functionality available in WCF. You must re-create any
automated integration processes, such as the BizTalk Server
orchestration, that used these adapters.

The upgrade framework migrates AIF endpoints and related

configurations from earlier releases to integration ports in Microsoft
Dynamics AX 2012. You must configure the integration ports upon
successful completion of the upgrade process before you use
Microsoft Dynamics AX 2012 services and the AIF functionality.

Security
Microsoft Dynamics AX 2012 services rely on Windows Communication
Foundation (WCF) for security. You can change the WCF configuration to make
necessary security settings that are required by Microsoft Dynamics AX services.
WCF is responsible for authenticating the user. A service operation performs a
specific action on a document such as read, update, or delete. All service
operations are performed in the context of a valid Microsoft Dynamics AX user.
When the AOS receives a service call, the services framework retrieves the
Windows identity by using the ServiceSecurityContext class. This Windows
identity is used to initialize a valid Microsoft Dynamics AX session. This
Microsoft Dynamics AX session is used for all X++ operations and is released
when the call is completed.
Each service operation causes a Microsoft Dynamics AX logon and logoff.
Microsoft Dynamics AX uses session pooling to reduce the overhead of creating
and destroying a session on every call. By default, all external WCF service calls
are made in the context of the Microsoft Dynamics AX identity of the caller.
WCF allows for client credentials to be specified in WCF configuration or in the
code. Configuration based credentials (such as certificates) can be specified in
the WCF client configuration for the service.
Some client credential values cannot be set using the WCF configuration file,
such as the user name and password or the Windows user name and password.
Such credential values must be specified in the code.

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

5-13

What's New - Technical in Microsoft Dynamics AX 2012 for Development

Performance Improvements
The following list describes improvements for both services and AIF that result
in performance improvements.

To achieve scale and redundancy, configure AOS servers with the

Network Load Balancing (NLB) for Microsoft Dynamics AX
services.

Client applications can now access services through the WCF

runtime without using the .NET Business connector.

An intranet deployment does not require IIS because services are

now hosted on the AOS by default.

Services can be hosted on IIS for requests originating from the

Internet. However, the routing service on IIS dispatches these
requests to the AOS host. All service requests, regardless of the
origin, are processed on the AOS.

The services framework uses connection pooling to reduce the

overhead of creating and destroying a session on service calls.

All the services references are placed in a single web services

description language (WSDL) file. The single WSDL lets developers
reuse types when consuming Microsoft Dynamics AX services.

Services are compiled to Microsoft Intermediate Language and are

run through the Microsoft CLR.

Summary
In this chapter you learned how Microsoft Dynamics AX 2012 improvements to
services and the Application Integration Framework (AIF) simplify
implementation, administration, and deployment of services and align Microsoft
Dynamics AX services with industry standards for web services. Microsoft
Dynamics AX 2012 introduces integration ports for streamlined configuration of
services and the AIF and provides several benefits to system administrators
through the following features and enhancements.

5-14

Services hosted on the Application Object Server (AOS)

IIS service hosting without BC.Net

Services as a first class programming model

Integration ports

Performance improvements in Services and the AIF

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

Chapter 5: Services and Application Integration

In Microsoft Dynamics AX 2012, improvements to the services framework result
in significant changes in functionality, configuration, database schema, and
document schemas (XSDs) and help simplify the setup. Some new integration
features are as follows:

Support for non-XML file formats

Out-of-the box integration templates

Support for large messages import (10 MB limit removed)

Support for flexible error handling on large imports such as rollback

and halt

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

5-15

What's New - Technical in Microsoft Dynamics AX 2012 for Development

Test Your Knowledge

1. Which of the following concepts includes the concept AIF endpoints and
related configuration forms in earlier releases of Microsoft Dynamics AX?
( ) SOAP Header
( ) Service Groups
( ) Integration Ports
( ) Windows Communication Foundation (WCF) Adapter
2. Which framework is recommended instead of the RunBase framework and
you can use to execute business operations synchronously or
asynchronously?
( ) Business Operation Framework (BOF)
( ) Windows Communication Foundation (WCF)
( ) Document Schemas (XSDs)
( ) Application Object Server (AOS)
3. Which of the following concepts is recommended instead of the Microsoft
Message Queuing (MSMQ) and BizTalk Server adapters in Microsoft
Dynamics AX 2012?
( ) SOAP headers
( ) Windows Communication Foundation (WCF) Adapter
( ) Inbound Port Transformer
( ) Data contracts
4. Which of the following improvements affect the system administrators?
(Select all that apply)
( ) Configuration is not company specific
( ) Integration port
( ) Data policies are optional
( ) Surrogate Foreign Keys (SFK)

5-16

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

Chapter 5: Services and Application Integration

Quick Interaction: Lessons Learned

Take a moment and write down three key points you have learned from this
chapter
1.

2.

3.

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement

5-17

What's New - Technical in Microsoft Dynamics AX 2012 for Development

Solutions
Test Your Knowledge
1. Which of the following concepts includes the concept AIF endpoints and
related configuration forms in earlier releases of Microsoft Dynamics AX?
( ) SOAP Header
( ) Service Groups
() Integration Ports
( ) Windows Communication Foundation (WCF) Adapter
2. Which framework is recommended instead of the RunBase framework and
you can use to execute business operations synchronously or
asynchronously?
() Business Operation Framework (BOF)
( ) Windows Communication Foundation (WCF)
( ) Document Schemas (XSDs)
( ) Application Object Server (AOS)
3. Which of the following concepts is recommended instead of the Microsoft
Message Queuing (MSMQ) and BizTalk Server adapters in Microsoft
Dynamics AX 2012?
( ) SOAP headers
() Windows Communication Foundation (WCF) Adapter
( ) Inbound Port Transformer
( ) Data contracts
4. Which of the following improvements affect the system administrators?
(Select all that apply)
() Configuration is not company specific
() Integration port
() Data policies are optional
( ) Surrogate Foreign Keys (SFK)

5-18

Microsoft Official Training Materials for Microsoft Dynamics

Your use of this content is subject to your current services agreement