As a follow-up to my earlier post about the new blob storage features, in this post, I’ll show you how to take advantage of the entity group transactions functionality that was recently rolled out to Windows Azure tables.

I’ve updated the project (modified storage client library and test program) I announced in the last post, so go ahead and download the code again.  To use the new features, you’ll need this code or your own code like it, because the SDK sample hasn’t yet been updated to include the new functionality.  You’ll also need to run against a storage account in the cloud, because the development storage in the SDK has also not yet been updated to match the latest bits in the cloud.

What are “Entity Group Transactions”?

Entity group transactions is a feature that allows you to make changes to multiple entities as part of the same operation, as long as all the entities are part of the same “entity group” (for now, that just means the same partition).  Here’s a more complete description from the “Programming Table Storage” whitepaper:

For the entities stored within the same table and same partition (i.e., they have the same partition key value), the application can atomically perform a transaction involving those entities. This allows the application to atomically perform multiple Create/Update/Delete operations across multiple entities in a single batch request to the storage system, as long as all the entities have the same partition key value and are in the same table. Either all the entity operations succeed in the single transaction or they all fail, and snapshot isolation is provided for the execution of the transaction. In addition, all other queries executing in parallel at the same time will not see the result of the transaction, since they will be working off a prior snapshot. Queries will only see the result of the transaction, once it has fully successfully committed.

Entity Group Transaction will require the use of the version header with the version set to "2009-04-14" or later.

I recommend the MSDN documentation for entity group transactions to see exactly what it looks like in the REST API.

How Do I Use Them?

Using this functionality is simple, because it’s already built into the ADO.NET Data Services protocol that we use in Windows Azure Tables.  I took two simple steps to take advantage of the new functionality:

1. I modified the storage client library to put the x-ms-version header (with value 2009-04-14) on all web requests to table storage.
2. I wrote some code using the SaveChangesOptions.Batch flag on my SaveChanges call.

That’s it!  The updated test program in the download should show the following output:

Creating container.
Creating big blob (5MB).
Done.
Committed blocks:
        AAAAAA==
        AQAAAA==
        AgAAAA==
        AwAAAA==
        BAAAAA==
Copying blob...
Done.
Committed blocks:
        AAAAAA==
        AQAAAA==
        AgAAAA==
        AwAAAA==
        BAAAAA==
Deleting test container.
Adding three entities (same table, same partition)...
Done.
Updating one entity and deleting another (same table, same partition)...
Done.
Deleting two entities (same table, same partition)...
Done.
Adding two entities (different table, different partition)...
        Got error: CommandsInBatchActOnDifferentPartitions: 1:All commands in a
batch must operate on same entity group.
Done.
Adding two entities (same table, different partition)...
        Got error: CommandsInBatchActOnDifferentPartitions: 1:All commands in a
batch must operate on same entity group.
Done.

Download

Download the code to see exactly what I did and to see both positive and negative tests showing that all the actions as part of the batch transaction need to operate on entities in the same partition of the same table.