AX2012: Role of attributes in data contracts

Hi Friends,
In continuation to my previous post on Basics of attributes, I would like to take this journey further  to discuss the use DataMemberAttribute and DataContractAttribute classes provided by AX2012. My idea in this post is not to show how to create a new service or a batch process using attributes but it is to understand the underlying reason for using attributes in these areas.

In short DataMemberAttribute and DataContractAttribute classes are used to define data contracts. However I would like to talk about data contracts in this post so that we clearly understand the meaning of one liner said above .So let's begin with some initial questions which come to mind when we hear a term like "Data Contract":

What is a data contract? 
If try to understand it word by word in a simple way, contract means an agreement to exchange something between two parties, similarly data contract means that data is being exchanged between two parties.

Who are the two parties which exchanges data?
Now let's start moving towards technology, the parties involved in a data exchange are client and a service.

Who provides framework for data contract?
WCF (Windows Communication Foundation) provides the framework for data contracts.

In which format the data is exchanged?
Data exchange happens in XML. The data is serialized and deserialized (converted to and from XML) during the process of data exchange.

Who does data serialization and deserialization?
There is a serialization engine called "Data Contract Serializer" which used by WCF to convert the data to and from XML.

So now when we know about the basics of data contract along with a technical flavor so the next questions which come to mind are:

How system identifies what data needs to be exchanged?
Here comes the roles of Attributes. There are 2 attributes which are used to decorate/mark/tag/identify the data which needs to be part of a data contract. These attributes are DataContractAttribute and DataMemberAttribute.

Where to define DataContractAttribute?
To keep it simple DataContractAttribute is defined on classes. More details can be found on MSDN.

Where to define DataMemberAttribute?
DataMemberAttribute is defined on each of the members of the class which needs to be exchanged.

How to define these attributes?
In the same way we define a normal attribute. You can refer to my last post Basics of attributes as well.

Standard AX2012 out of the box provides us with these attribute classes:

DataMemberAttribute 

DataContractAttribute


Examples can be found in standard AX where these attributes are used, an example is shown below:

DataContractAttribute and DataMemberAttribute also play vital role in SysOperationFramework introduced in AX2012 and there are some very good blogs available to understand how we use these attributes in SysOperationFramework and creation of services. Some really nice articles I would recommend are:

• daxmusings
• artofcreation
• Axilicious

I hope now we are able to realize the power of attributes. They have wide area of applicability and with the ability to create your own custom attributes it is seamless. 

Thanks for reading the blog.

Cheers!!!!!

AX2012 : Understanding Attributes

Hi Friends,
I would like to discuss about the concept of attributes with an example of how we use them in AX2012. This post will be interesting to those who are new to Attributes concept. It is important to understand that Attributes come from .NET platform they are not simply implemented as language elements.To summarize the general introduction of attributes:

• Attributes are declarative information used to add metadata information to the code.
• Attributes are stored as metadata in an assembly. They are NOT part of executable code.
• Attributes information can be extracted through reflection at run time/compile time/design time.
• Attributes are extensible, you can create you own custom attributes.

An attribute can be attached by simply typing the name of the attribute enclosed in square bracket before the declaration of class/function where it needs to be applied.

In AX 2012, SysAttribute class is an abstract base class for all attribute classes. So if you have to create your own attribute class then it should be a non abstract class and must inherit from SysAttribute class. 

Attributes can be used in many different scenarios, one of the common practice is to use them in creating batch jobs through SysOperation framework.

Let's jump into some practical way to use attributes, I'll use SysObsoleteAttribute in the below example to get a feel of using attributes:

I created a new class "SampleCalculator" and a method to add two numbers:

Then I created a job to call this method

This is simple, nothing interesting till now. 

In the current method, there is a limitation that it accepts only 2 integers, there can be situations where a person wants to add n number of integers, so to improve the design and usability I thought to create a new function which accepts a list as a parameter so that we can add any number of integers, the new method looks  like below:

We test this method through job, it works good:

Now I want that if any other developer is using the class "SampleCalculator"  to perform the addition calculations, he should prefer using the new function "addMultipleNum()" instead of the old function "add2Num()".

Also, I do not want to delete the previous function as it may lead to compilation errors in system in case the previous function is used somewhere. So what do I do ??? The answer in such situation is use ATTRIBUTES. 

AX2012 provides us with an Attribute class SysObsoleteAttribute for such situations.

I can decorate my first function add2Num() with SysObsoleteAttribute and to do this I simply have to add the attribute in function definition as shown below:

Now the question is how does it impacts the overall process, to know this just compile the job and you will notice that the compiler gives a warning and immediately tells me that this function which I am using in my job is Obsolete.

This is Okay but does it tells me what to do if this function is Obsolete? No not now. 

Can I add some more information to the attribute I attached? YES :)

While defining SysObsoleteAttribute you can see that we can define two optional parameters:

So now I added the explanation in the first parameter for the attribute, notice that value in second boolean parameter "_isError" is passed as false for now.

Now if I compile the job, the warning is more informative, it tells me which function should I use:

This is cool. Now I can inform someone other developers to use the new function, when the try to use the old one.

Now let us change second Boolean parameter "_isError" value to true, compile the code and see what happens:

You will notice that compiler gave an error instead of warning. This is quite helpful in situations where we want to avoid use of some function. This is an example of attributes behavior at compile time.  

This attribute class "SysObsoleteAttribute" is also helpful for ISV's when they release new hot fixes  versions of there product and want there partners to start using new functions when they customize the solution.

An example of SysObsoleteAttribute can also be found in SysDictClass 

There are many attribute classes provided by default in AX. You can get the list by simply looking the type hierarchy browser of SysAttribute class and start playing with them :).

Thanks for reading the post!!!!!