Creating a Service in AX 2012 / Consuming a Service in Visual Studio 2010

Hi There!

As promised, in this post we’ll see how to create a simple demo service using AX 2012. Please refer to my last post about AX 2012 Service Documents Types and A Simple Introduction to AX 2012 Services Architecture to get a more detailed explanation to AX 2012 Services.

Also, I would like to point out that AX 2012 services are hosted on the AOS, and that both internal and external applications will be authenticated through the AOS.  With this being said, the following example will be an internal application that will get the customer name from AX services.

If I wanted to have an external application executing the same operation I would have to host the services in IIS. For more information on services please refer to this white paper.

Further, when working with AX 2012 WCF services, we will have to dive into data contracts. In this sample service will use a DataContractAttribute. The string DataContractAttribute indicates that this class is a Data Contract. The square brackets [] indicate that this string is an attribute. We are also going to be using Data Members, which would help us define the default values for our data contracts.

If you are new to this, don’t worry, you can find a lot of information about Data Contracts and Data Members out there.

Another concept that we’ll be exposed on this example is the SysEntryPointAttribute, which helps with authorization checks and how they are performed for a method that is called on the server. Further, this is a very important class when working with Services in AX 2012 as we have to use it for all service operations.

So, let’s start working on our simple service. (Please note that I’m working on a project that involves a lot more detail. When done I will share it with you, so we can understand many other concepts about AX 2012 that won’t be covered in this post)

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.

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.

Ok, so at this point we should have our new AX 2012 service already working. The next step is to learn how to use this service from Visual Studio 2010. Please refer to this article if you are new to adding services references to Visual Studio. It will help you understand the underlying concepts of this operation.

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.

6.       Select the service and then click OK.

NOTE: The address format in step 5 is http://<machinename>:8101/DynamicsAx/Services/Xpp. 

7.       Invoke the service from the client.

8.       Click F5 to run the service.

As you can see, when you run the service, the first customer name that are available in your system will be presented as an output.  There is a lot more to services and you can start learning more about it by going to partner source and/or downloading the new AX 2012 white papers focusing on services.

I will be posting a lot more on this later soon, so keep reading my blog as there is a lot more to come.

Take Care and have a great weekend!



A Simple Introduction to AX 2012 Services Architecture



Hi there!

I hope that everyone is having a super productive and challenging week.  On this thought, I thought on challenging myself and talk a bit more about the AX 2012 services architecture. Please refer to my post about AX 2012 Services Types for more information on services.

Ok, so what’s new in AX 2012 around services? Well, I have to say that things have change quite a bit for the better as in Ax 2012 we see that Microsoft has expanded the support for WCF beyond the basic HTTP and HTTPS bindings.  In fact, the Microsoft Message Queuing (MSMQ) and BizTalk Server adapters provided in AX 2009 have been removed, but cheer up; Microsoft is providing the same functionality through WCF.

The following diagram depicts the new AX 2012 architecture.

As we can see in the above diagram, the AOS is the WCF service host in AX 2012. This idea extends even further, the services that are hosted by the AOS work both with internal and external applications. So does this mean that we don’t need IIS anymore?

Well, yes and no. If you are planning to have only internal application using the WCF services, then you no longer need IIS. However, if the services are going to be consumed by external application, then you have to host the services on IIS.

Also, it is important to point out that the WCF services in AX 2012 are contained in a single WSDL file. This simplifies the use of services when using visual studio for example. The reason is because we would just need to add one single reference instead of 90, which is cool and smart.

Another cool new architectural change of AX 2012 services are the data contracts, and the business operation framework.

AX 2012 now supports the use of .NET and X++ types as data contracts to use as service operation inputs, and to also return parameters.  The following are the new changes:

o   You can pass complex data types without having to explicitly implement XML serialization and deserialization from them.

o   The data contract serialization and deserialization is now handled by Windows Communication Foundation (WCF).

o   X++ provides support for data contract functionality through the DataContractAttribute and DataMemberAttribute attributes (which I will cover in my next post)

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

Another new enhancement of AX 2012 is the Business Operation Framework, which is a service operation exposed from the AOS. Remember that in AX 2009 we would have to use the RunBase batch class to execute AIF calls asynchronously? In AX 2012, we can now use the business operation framework, which support both synchronously and asynchronously operations. In addition, although the RunBase framework is still supported in AX 2012, Microsoft recommends using the new Business Operation Framework instead because it provides a clean separation between the data contract, user interface and the service operation. 

This is all for now and I hope this post can be helpful to you. Please check my blog again later this week as I will be posting how to create services in AX 2012 and consume them from C# this week soon.

Take care!

A Simple Exploration to Table Inheritance in AX 2012

Hi There!

On this post I would like to explore table inheritance in AX 2012. Microsoft has made a lot of changes to the table structure in this new release and it is important that we understand the core rules of this new concept.

In a nutshell, a table in AX 2012 can be extended (as a base table) to other tables. On this same thought, a table also can derive from another table.  So how does AX 2012 support this? Well, tables in AX 2012 have two new properties; (1) SupportInheritance property, and (2) the Extends property, which together control table inheritance.

So, when do we know we can use table inheritance?  First of all, we need to define which table will be the proposed base table, and the proposed derived table.  In addition, the following conditions (From a Microsoft Source) will tell us whether we can use inheritance between two tables:

1. There is no thought that there might be a 1-to-many or many-to-many relationship between the two tables.
2. An existing row in the proposed base table, and the corresponding row in the derived table, both refer to the same item in the real world.
3. Each row in the proposed base table has exactly one corresponding row in the derived table.
4. If one row is ever deleted from either table, the corresponding row must also be deleted.
5. The base table probably has at least two tables that derive from it.
1. The two derived tables have fields for different kinds of things.
2. The two derived tables refer to different variations of the general items that are tracked together in the base table. 
6. No item that is represented in a base table would ever be represented in more than one of its derived tables.
7. The derived table is not meant for performance tuning of the physical database, such as placing an image column in its own table.

Moving right along, let’s see an example of this. Let’s take a dealership that sales Cars and Trucks.  The dealership knows that both the cars and trucks have a Make and a Model. However, at the same time, the dealership wants to know a specific “thing” about the car and the truck that is not part of both.

In the following example, the dealership puts together a spreadsheet with two columns (one for the car and one for the truck). They identify that a Car and a Truck can be in one entity sharing the model and the make, but they need to also track how many passengers a car can sit in a car, and how much weight a can be loaded into a truck.

Vehicle – Car	Vehicle - Truck
Model	Model
Make	Make
Number of passengers	Maximum Weight

This is the perfect example to implement table inheritance as we can recommend to the dealership to create two separate tables for the two different conditions that they need to track (number of passengers and weight)

So, this is how table inheritance would work; The RecId system field has been added to each table as the primary key. Also, the system field InstanceRelationTypeId has been added to the base table, and its values refer to derived tables.

Car – Truck Table

Vehicle Make	Vehicle Model	InstantRelationTypeId	RecId
Toyota	Scion	50011	1234567890
Mac	Loader	50012	1234567891
Freightliner	Speed King	50012	1234567892
Ferrari	Diablo	50011	1234567893

Weights Table (Instant Relationship type 50012)

Weight	RecId
658 lbs	1234567891
1569852 lbs	1234567892

Passengers Table (Instant Relationship type 50011)

MaxPassengers	RecId
5	1234567890
2	1234567893

In the example above, the Car-Truck Table holds the common data for both cars and trucks’ make and models. The field InstanceRelationTypeId defines which table will be inherited from, and the RecId field defines the related record on the derived tables.

There is a lot more to learn about this topic, and I encourage you to visit partner source and/or the Microsoft resources about it.

This is all for now, but check my blog later this week to learn about creating services in AX 2012 and consuming them from an external C# application.

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 ADO.net 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!