Microsoft Dynamics AX 2012 - UnitOfWork Class and it's usage

With the release of Microsoft Dynamics AX 2012, a new class is going to be introduced that did not previously exist. This is the UnitOfWork Class. This object, being a system class, contained within the System Documentation, is described by Microsoft as.:

"Giving the ability to manage the operation sequence and transaction integrity for row-based database operations."

In short, this gives the ability, for any insert, updates or deletes, that might need to take place for a set of rows, of data, and register that with a given instance of the UnitOfWork class. After performing, and gathering up all the needed inserts, update or delete actions for a given set of rows of data, a sigle method call can be used to perform said updates.

This class, in turn, without the need for the developer to worry about, take and make sure the correct ordering and sequence of the given data updates are carried out properly. This then, means that this new class helps to make sure, that the integrity of transactions are safe, while developing code that performs such actions on a set of possible data needs.

To help bring this concept home, I have created the following short, dive into the use of this class, and how it can be used with your own needs of working with row data inside Microsoft Dynamics AX 2012.

To start we will need to make sure and have a table to work with. For this, I will create a new custom table, in which to work on. The idea, again, is to prove out and show the theory behind the UnitOfWork class. Once it's clearly understood the purpose, then the usage can be applied as needed when working with data.



For this, I created the above UOWTest table, that has two fields as part of it's make up. Those are two string based fields, called 'Id' & 'Name'.

Now that I have the table to work with, next I need a block, or unit of code, in order to work with this table. In the past, the only way to perform insert's, updates or deletes, a developer would have to take and make use of ttsBegin,ttsCommit & ttsAbort to perform such actions.

These are still around, and you can still make use of them, however, with the UnitOfWork class, this is handled for you, through a single method call of UnitOfWork.SaveChanges();

So lets take a look then, and see some code, that makes use of the UnitOfWork, in say an insert fashion.



As you can see above, I choose to place my block of code in a job called 'TestUOWJob'. Looking at the make up of this job we can see that I have 3 variables. A UnitOwWork variable, a variable that represents my new test table as well as an int
variable.

Since I am performing an insert, I choose to do a for() loop, that should in turn create ten records in the new table. In order to achieve this, I am simply, taking and working with the table variable, by setting my two field values, and then calling upon the initialized uow variable, for '.insertonSaveChanges(tUOW);'.

This is passing in the given record, or row of data, into the UnitOfWork object, and slating that record, for later when code calls the saveChanges(). When this is done the UnitOfWork object will in turn iterate through the given types of deletes, updates or inserts that have been marked for *onSaveChanges() method calls.

So lets take now and try to execute this block of code. In clicking on the run button of the job, instead of getting my desired results, I get the following error message.: "Error - Cannot add a record in table UOWTest (UOWTest) with Unit of Work. The UnitofWork class should be instantiated on the server to perform any operation."

What gives? Well, the is actually by design, since the context of which a given UnitOfWork object is meant to operate only at the server level. This can not operate within a client side context at all. Since that is the case, then we can either wrap our code block in a class that is set to run at the Server, or within a server static method, that will execute then the given unit of code at the correct server side context.

In order to achieve this, I have now taken my block of code that was in a client side job, and moved it to live within a class, and a static method off of that class, with the server keyword as part of the method signature.



I then simply, take and make the following call: UOWTestClass::executeUOWTest(); Which in turn gives us are unitOfWork, proper context execution, so that we get the full amount of data, as shown in the following screen shot.:



With this, the same approach works for both update and delete operations, including the ability to mix these operations within a given instance of the UnitOfWork class.

The benefit from doing so, in turn reduces the need for the developer to keep up with transactions within the given code block, and reduces the effort therefore needed to achieve working with row based data, for insert, update & delete operations.

That's all for now, but check back soon as more deep dives into AX 2012 continue, including I have a review of the keynote speech from Microsoft COO Kevin Turner, while at WPC11. Till next time!



"Visit the Dynamics AX Community Page today!"