ax2012 enus wn dev 05

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

5-1

Microsoft Official Training Materials for Microsoft Dynamics

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

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




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 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.

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.

5-3




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. Open the AOT . 2. Create a new class. 3. Enhance the class by adding the [DataContractAttribute] attribute. 4. Create a new method. 5. Enhance the class by adding the [DataMemberAttribute]attribute. 6. Create another class. 7. Create a method that instantiates the class created in Step 2. 8. Enhance the class that uses the [SysEntryPointAttribute] attribute. 9. Right-click the Services node in the AOT and select New Service. 10. Enter a name into the Name property. 11. Set the Class property to the class created in Step 6. 12. Expand the new service node.

5-4




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://: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.

5-5




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. Create a new Data Contract class. 2. Create a new Service class. 3. Create a new Service and add Operations. 4. Create a Service Group and link the service to the service group. 5. Create a new project in Visual Studio and add the service reference. 6. Invoke the service from the client.

Step by Step: Create the Data Contract Class

1. Open Microsoft Dynamics AX 2012. 2. Open a Developer workspace. 3. Open the AOT. 4. Create a new class named AddressFinder. 5. Enhance the class by adding the [DataContractAttribute] attribute.

5-6




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.

5-7




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




5-9

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://: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.




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 comma-delimited 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




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.

5-11




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




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.

5-13




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.

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

5-14




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

5-15




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




Quick Interaction: Lessons Learned Take a moment and write down three key points you have learned from this chapter

1.

2.

3.

5-17




5-18

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)


Chapter 5: SERVICES AND APPLICATION INTEGRATIONObjectivesIntroductionServicesDocument ServicesCustom ServicesSystem ServicesService GroupsProcedure: Create a ServiceProcedure: Use the ServiceProcedure: Debug the ServiceLab 5.1 - Create a ServiceScenarioChallenge Yourself: Create the ServiceChallenge Yourself: Create the C# ProjectNeed a Little Help?Step by Step: Create the Data Contract ClassStep by Step: Create the X++ Service ClassStep by Step: Create the ServiceStep by Step: Create the C# ProjectInbound and Outbound PortsBasic Integration PortEnhanced Integration PortSupport for Non-XML FilesTroubleshoot Services and AIFArchitectureWindows Communication Foundation (WCF) AdapterServices hosted on the Application Object Server (AOS)Microsoft Dynamics AX SOAP HeadersData ContractBusiness Operation FrameworkInstallation ConsiderationsUpgrade ConsiderationsSecurityPerformance ImprovementsSummaryTest Your KnowledgeQuick Interaction: Lessons LearnedSolutions

ax2012 enus wn dev 05

Documents