Microsoft Dynamics AX 2012 - A Dive into Services, Custom Services (Part II)

I wanted to continue today, with my dive into services, for Microsoft Dynamics AX 2012, where I left of with Microsoft Dynamics AX 2012 - A Dive into Services, Custom Services (Part I).

Today's focus for this area, will be around DataContracts, a look into a simple one, as well as working with collections through SysEntryPoint methods, or Operations of service contracts, for DataContracts.

With that, we left of in Part I, with the showing the basic parts that make up a given custom service. This includes: an X++/Xpp class, that represents the logic of exposed business logic through SysEntryPoint tagged methods. Then we have a service node, that is tied to said class, with the ability to turn SysEntryPoint methods into operations. Finally we have a Service Group node, that the new custom service resides in, as a publishing point so the service can be consumed.

Now that we have this base understanding, lets look at what we would most likely be making use of, through such SysEntryPoint service operations.

When you think of Services, and specifically WCF services, then you start to also think in terms of DataContracts. This did not exists prior to AX 2012, however has been a major part and concept of WCF, since WCF was introduced back in .Net 3.0 days.

It's a similar concept, in that the point of a DataContract is what the name implies, to offer a Contract, with set Properties or Attributes, that govern the interaction of the consumer and the service, for exchanging data. Mouth full huh?

So lets look at what enables a basic DataContract. First, a DataContract is an X++ class. Like the SysEntryPoint metadata tag for service operations, there are several metadata tags that enable a DataContract to exists. These metadata tags, or attribute tags define to AX what the purpose and point of a class, and it's methods are meant to be.

In turn AX 2012 can use this information, when the times comes to generate the Artifacts that enable the usage of said elements.

So lets look at a simple example. What we will do is create a DataContract class, and set that is has two Attributes or Properties, Name, Account. To do this, we need to create a new class, and within the Class declaration add DataContractAttribute metadata tag, as shown below.



Simply adding that given tag, will now enable this class to be used as a DataContract within AX 2012 and outside of AX 2012, when being exposed as part of a Service Operation.

Since we need to attributes, lets now take and add two class scope, private variables to the class declaration of our new DataContract.



Now that we have our class context, private Str variables, we can reference these in creating our attributes for the DataContract, as shown below.





You will notice that for each of these, we have to declare the give methods as DataMemberAttribute, so that for the given generation of the WCF Artifacts and WSDL, AX can know which methods on the DataContract are meant to act as such, and which are not.

On this same topic, you will also notice I supplied the Name, and Account in text as part of the DataMemberAttribute tag. The reason I do this, is so that those consumes outside of AX will see these as properties of the DataContract as Name and Account, vs. parmName and parmAccount.

Since properties don't exist in AX, we make use of the parm method concept that you see in the above pictures.

Now looking at our class from a higher level, we see that we declared the given element as a DataContractAttribute at it's class declaration, and then each property or DataMemberAttribute is declared using the parm Method concept.



That's It! Now you have a DataContract that can be used within a given AX Service Operation.

Lets do exactly that, with taking and creating a Service class, a SysEntryPoint that will represent an operation, and have it to where the DataContract is the required parameter of the method signature.



Now, if we took and deployed this as a service, contained within a service group, we would have a service operation called doWork that would require us to pass in the idbDataContract to operate off of.

That's pretty straight forward and easy huh? What about working with a collection, say a List of DataContracts? Now that is not as well documented yet, however very possible. This is enabled through the use of the AifCollectionTypeAttribute, as shown below.



Now, first thing you should notice is that we can have multiple metadata attributes applied to a given method, using , (commas) to separate the attribute tags. Next this AifCollectionTypeAttribute is an animal of it's own, lets me say that.

So what we are doing here is declaring the Parameter Name that will be used as part of this collection. Second, we are declaring the type of the parameter, which happens to be a class and finally we are telling AX what will live in this list, which happens to be our idbDataContract we created earlier.



The idea that this whole AifCollectionTypeAttribute enables, is because of the fact that X++ is not a strongly typed language, however when working with collections we have to give a strongly type collection. This is what we are doing when we work with the AifCollectionTypeAttribute. We are giving the generator of the artifacts a way to describe and create for use by external consumers, to interact with collection types, from X++.

So there you go, we now know how to take and create a basic custom service, a data contract and work with a collection of data contracts within AX and to expose that to the outside world.

My part of this series, I will show how these are called from within AX and outside of AX, and look at the differences and some other important supporting information in this area.

I hope you can see too, that this is the build up that we first touch upon as the vision some years ago in this post, Microsoft's strategy and vision for Dynamics AX and SOA, and one that we have been covering ever since.

That's all for now, check back soon as more to come! Till Next time!



"Visit the Dynamics AX Community Page today!"