C# dynamic object and JSON serialization with Json.Net


Heads up!

The blog has moved!
If you are interested in reading new posts, the new URL to bookmark is http://blog.valeriogheri.com/


I’m working on a project where I don’t need a solid domain model as all the logic is handled by the client-side code using  javascript and various frameworks as SignalR, Knockout.js and jQuery.
That’s why I found myself unwilling to add dumb C# POCO objects just to handle JSON serialization and deserialization in the SignalR hub(s), and I turned to dynamic objects and Json.Net (starting from version 4.0)  to handle this tasks easily and quickly.


Let’s say that for example I want to send data to the browser. All I have to do is to create an ExpandoObject (my new favourite .Net class!) and serialize it using Json.Net “JsonConvert.SerializeObject()”.

Let’s see an example:

dynamic foo = new ExpandoObject();
foo.Bar = "something";
string json = Newtonsoft.Json.JsonConvert.SerializeObject(foo);

And here is the output:


Json.Net offers a great way to deserialize a JSON string into a dynamic using the JObject (you can find it under the Newtonsoft.Json.Linq namespace and here the details).

Let’s see an example re-using the previous foo object:

dynamic foo = JObject.Parse(jsonText);
string bar = foo.Bar; // bar = "something"

And that’s it, really easy and yet really powerful.
In a more structured application, I would probably not use this trick as I would probably have all of my ViewModels and Domain Models objects ready to use in type safe serialization/deserialization operations, but that’s not always the case.

I hope this helps.


ChatR: just another chat application using SignalR


Heads up!

The blog has moved!
If you are interested in reading new posts, the new URL to bookmark is http://blog.valeriogheri.com/


Update (30 November, 2012): David Fowler (SignalR co-creator) has made ChatR into an example application downloadable via Nuget to show SignalR beginners how to quickly build a chat web app.
He forked the project on GitHub and updated the code base to the latest version of the library, 1.0Alpha2, and then sent me a pull request that I accepted and merged into the master branch.
Therefore the code that you see now in the latest commit on the master branch is slightly different than the one shown in this post, but this is not a problem, you just need to go back in time in the history of the commits to find exactly what is shown here if you really want to, otherwise just dive into the new code!

Update (17 November, 2012): this blog article is related to version 0.5.2. In these days the SignalR team is working on version 1.0 and has released an Alpha. There are quite a lot of significant changes in the API, but the concepts at the basis still apply.
I hope to be able to post an update article when 1.0 is released.

There’s a lot of buzz these days around SignalR (http://signalr.net/) and more in general around real time communication techniques for the web (http://www.webrtc.org/).
There are many scenarios where real time can be embedded in web applications in a way that is actually useful for the user, but the most easy to understand scenario is the good old chat 🙂
That’s why today I’m going to write about…


A chat web application! Yes, I know it’s not the most original example, but it’s still a good starting point to excercise the fundamentals of the framework.
The user will be able to choose a username and then join the (single room) chat, where he/she will be able to chat with the others and see a list of currently connected users.
This list will obviously update itself everytime someone joins or disconnect the chat.

Source code and demo

As always the code for this tutorial is published on GitHub at https://github.com/vgheri/ChatR
A working demo is deployed on the fantastic AppHarbor at http://chatr-1.apphb.com  (if you want to run a test, simply load up new tabs… SignalR is not relying on Sessions so it will be safe). 


This project relies on Asp.Net MVC 3 for the general architecture and the basic client-server communication.
As anticipated, I’ll be using SignalR for real time client-server communication, Twitter’s Bootstrap for basic UI layout and CSS and Knockout Js (knockoutjs.com) to automatize the view.

Before starting, I’d like to spend a few words about SignalR: it’s growing up as a solid library to use in order to build production code and it’s dead easy to use (https://github.com/SignalR/SignalR/wiki) once you grasp the fundamentals (which I’ll cover later on). It not only gets the job done, but also sports an awesome client-server async communication pattern, that makes really easy to invoke methods from Js to C# and viceversa (there is even someone who proposed to use it for general purpose communication http://www.novanet.no/blog/yngve-bakken-nilsen/dates/2012/7/clean-up-your-mvc-app-with-signalr/)
If you are interested in understanding more about the internals, I suggest you clone the repository on GitHub (https://github.com/SignalR/) and read something like http://ayende.com/blog/93185/reviewing-signalrndash-part-ii.


This application will feature a 1-click process to join the chat:

Step 1: landing page with a form to enter username
Step 2: chat page

The landing page is really simple, just a few text elements and an HTML form with an input text and a submit button that will trigger a HTML POST handled by the server via a MVC action.


I’m going to use 2 objects as Domain models and 1 repository object to store users currently connected to the system.
Let’s see them briefly:
ChatUser has two properties, Id and Username. The former uniquely identifies a client during a session and is assigned by SignalR.
ChatMessage is super easy and has a minimal set of properties: username (I could have used the ChatUser object, but because I’m displaying just a username and not the user id, I chose to transfer the minimum set of information), content and timestamp.
InMemoryRepository implements the Singleton pattern and helps clients retrieve the list of users.

Basic UI structure

Super simple and clean: a title bar on the top of the page that holds the name of the app, a container on the left that holds the usernames of currently connected users, a container, side by side with the previous one, that holds the chat messages and below an input box to enter a message with a submit button.
All the client-server communication round-trips here are handled by SignalR.
To dynamically update the UI, I’ve used Knockout Js and its data-binding declarations.

Javascript namespace and Knockout view models

I chose to create a separate Js file to declare a namespace and the Knockout viewmodels.
Therefore I created a separate folder called “Js” and a javascript file called chatR.js.
The code is pretty straightforward, as you can see:

The rest of the javascript code is inside chat.cshtml as I needed to access the Model binding engine to retrieve the username chosen by the user.


Server side code

Let’s start with the server side part of SignalR.
Do  you remember what I mentioned earlier in the post, that this library sports a great communication pattern that makes really easy to call C# methods from Javascript and viceversa? Well, the C# methods that we can call from the client side are those declared (as public) in the so called Hub.
What is a Hub? Well, a Hub is an abstraction that, to cite the Wiki,  “provides a higher level RPC framework over a PersistentConnection. If you have different types of messages that you want to send between server and client then hubs is recommended so you don’t have to do your own dispatching”.
SignalR offers two options to build a RTC app, leaving to the developer the choice between two built-in objects: Persistent Connections and Hubs.
It took me a while to fully understand what are the differences between these two, and why choose one over another.
Basically Hubs allow you to dispatch whatever object you want to the server, taking care of JSON serialization and deserialization, integrate model binding and are easier to setup, as you won’t have to write additional code to manually register additional routes (the SignalR specific routes). (You may want to read this question on SO, with words from David Fowler, creator of SignalR:  http://stackoverflow.com/questions/9280484/signalr-why-choose-hub-vs-persistent-connection).
I think it’s pretty safe to say that if you are writing a common web application or .Net application, you’ll be fine with Hubs.

N.B It’s imporant to note that Hubs are created on a “per request” basis, so no static stuff in it should be declared.

To start with, create a Hubs folder and create a new class that derives from Hub.
Here I called mine “ChatHub” and I defined the methods that will be used by the clients:
GetConnectedUsers: retrieves the list of currently connected users
Joined: fired when a new client joins the chat. We add the user to the repository and notify all the clients (even the newly joined) that this new client connected.
Send: broadcasts the message to all the clients (plus some extra work, like formatting links and youtube urls embedded in the messages, showing them as active links and embedded video player respectively. This part is mostly taken by the Jabbr codebase, thanks again David Fowler 🙂 )

Here’s the code:

As you can see, there’s something more: this class implements an interface called IDisconnect, part of SignalR, which allows us to handle the Disconnect() event fired when a user leaves the application. Again what we do here is remove the user from the repository and notify the other clients of the event.
There is another interface, called IConnected, that allows us to catch connection events like Connect and Reconnect, but I chose not to use them because unfortunately (at least in Connect) the round-trip state (see https://github.com/SignalR/SignalR/wiki/SignalR-JS-Client-Hubs) is not available, therefore I cannot access the state set on the Hub with information like the username set on the client that caused the event to fire.
Later on I’ll explain in more detail with code.
This is also the reason why I have a Joined event handler, because I need an event handler, fired after the Connect event, where I can access the round-trip state. Just for the record, Jabbr uses the same philosohpy, not implementing IConnected.
Finally, as you can see almost all of the methods have a void return type, but one: GetConnectedUsers has a ICollection<ChatUsers> return type and this means that only the client invoking the method will get the data back and furthermore the library will handle the JSON serialization and deserialization of the collection.
Alternatively I could have used Caller.callback and set a void return type to the method.

Client side code

On the client side, the first important thing to note is the order of the script references:
1) jQuery 2) jQuery.signalR 3) <script src=”signalr/hubs” type=”text/javascript”></script>

The last one is important because navigating to /signalr/hubs will dynamically generate the script based on the hubs declared on the server. Each hub on the server will become a property on the client side $.connection, e.g. $.connection.myHub.

Let’s see now how to hook up the client and the server:

It’s important to note that all Hub names (methods and class name) are in  camelCase, so for example
var chatHub = $.connection.chatHub;   is creating the proxy to invoke server code.

The next statement,
chatHub.username = currentUser.username;
is setting the round-trip state on the Hub, in this case I’m setting the username so that it will be accessible from the server and I’ll be able to add this user to the list of currently connected clients.

Following we have client-side event handlers, as invoked by the server (remember? Clients.onMessageReceived(message); )

We also apply knockout bindings so that the UI will start updating itself as the ViewModels change.
Finally we have the code block to start the SignalR connection and invoke two Hubs method:

// Step 1: Start the connection
// Step 2: Get all currenlty connected users
// Step 3: Join to the chat and nmotify all the clients (me included) that there is a new user connected
            .done(function () {
                              .done(function (connectedUsers) {
                                   ko.utils.arrayForEach(connectedUsers, function (item) {
                                      users.contacts.push(new chatR.user(item.Username, item.Id));
                               }).done(function () {

method $.connection.hub.start provides two callbacks, done and fail.
So in the code above I’m saying that if the connections is successfully estabilished, we can now try to retrieve the list of connected users and if this worked too, we can notify all the clients that this new client connected via chatHub.joined().
At this point the round-trip state will be available and therefore we will be able to register a new User, along with its connection ID and username.

One final note: by default DateTime is serialized by SignalR using ISO8601 format (http://en.wikipedia.org/wiki/ISO_8601), which is ok to parse for Chrome and latest browsers, but, guess what?, not for IE 9 and older versions. That’s why I had to search the web for a nice and quick solution, that you can find in the source code on GitHub.

Useful links

ChatR on GitHub: https://github.com/vgheri/ChatR
ChatR on AppHarbor: http://chatr-1.apphb.com
SignalR Wiki: https://github.com/SignalR/SignalR/wiki/Hubs
Hubs vs Persistent Connections: http://stackoverflow.com/questions/9280484/signalr-why-choose-hub-vs-persistent-connection
Useful tutorial: http://www.amazedsaint.com/2011/11/introduction-ksigdo-knockout-signalr-to.html
Jabbr on GitHub: https://github.com/davidfowl/JabbR

Excel 2010 automation with Asp.Net, on top of a Windows Server 2008 R2 64 with IIS 7.5


Heads up!

The blog has moved!
If you are interested in reading new posts, the new URL to bookmark is http://blog.valeriogheri.com/


Anyone who ever tried working with Office automation on Windows Server 2008 64bit knows that it is a nightmare to make it work as expected.
For a web application I’m currently working on, I need to access an Excel 2010 file, write some data in it, run a VBA macro and read the results out of it.
To make this workflow successfull, there are 3 problems to cope with:
1) create an Excel application

var excelApp = new Microsoft.Office.Interop.Excel.Application();

2) open and save files


3) run a VBA macro stored into the Excel file


Now, problems 1 and 2 have been successfully addressed in the past, see for example http://www.bloing.net/2011/01/how-to-make-iis7-play-nice-with-office-interop/

for a complete overview.

But I couldn’t find anything about problem number 3! My application was simply stuck when trying to run the macro and the only solution was to kill the Excel application to take back control of it. After two days spent troubleshooting, changing every possible configuration options, I’ve finally found the solution. Open IIS Manager, select the Application Pool used for the application you want to deploy and then click on “Advanced Settings”. Once the window opens, set the option “Load User Profile” to true, like shown in the image below.

Interop fix

Set Load User profile to true

That’s it, this was enough to make my application work as expected, being able to run the Excel VBA macro!
I hope this helps.

Custom Unobtrusive jQuery Validation with Data Annotations in MVC 3


Heads up!

The blog has moved!
The new URL to bookmark is http://blog.valeriogheri.com/


MVC 3 introduced what is called Unobtrusive Client Validation. This feature relies on jQuery and HTML5 custom data attributes. It is very powerful and not so hard to use… with the right tutorial to follow 🙂
It’s also very useful because it leverages the power of Data Annotations,  a clean way to express View Model rules in my opinion.
Let’s start the tutorial with a bit of theory (if you’re not interested, you can skip it and go straight to the paragraph “The tutorial”  and download the source code from https://github.com/vgheri/DateCustomValidationExample)

What is a custom data attribute

“As per HTML 5 draft specification a custom data attribute is an attribute in no namespace whose name starts with the string “data-“, has at least one character after the hyphen, is XML-compatible, and contains no characters in the range U+0041 to U+005A (LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z). Custom data attributes are intended to store custom data private to the page or application, for which there are no more appropriate attributes or elements. These attributes are not intended for use by software that is independent of the site that uses the attributes. It would be inappropriate, however, for the user to use generic software not associated with that music site to search for tracks of a certain length by looking at this data. This is because these attributes are intended for use by the site’s own scripts, and are not a generic extension mechanism for publicly-usable metadata. Every HTML element may have any number of custom data attributes specified, with any value. JavaScript libraries may use the custom data attributes, as they are considered to be part of the page on which they are used.”

This means that any attribute whose name starts with “data-” will be treated as a storage area for private data.
This allows you to write valid HTML markup (passing an HTML 5 validator) while, simultaneously, embedding data within your page.

MVC 3 + jQuery

MVC3’s new jQuery Validation mechanism links jQuery Validation and Validation Attributes Metadata. The magic happens in the jquery.validate.unobtrusive file that takes all data- attributes and works with them.
To exploit this mechanism, we need to create our own Custom Validation Attributes as we’ll see in this article.

How MVC generates the data- attributes:

The custom data attributes are generated by helpers methods like Html.TextBoxFor(), as it knows already all the Data Anotations that the field needs, and if Unobstrutive setting is true (by default in MVC 3) it will generate all data- that he needs.
For each client validation rule(we’ll get there), an attribute is added with data-val-rulename=”message”. Then, for each parameter in the client validation rule, an attribute is added with data-val-rulename-paramname=”paramvalue”.

The tutorial

In this tutorial we will create a custom validation that checks if a certain date is greater than another date entered by the user in a form. For the purpose of this tutorial we will create a model consisting of one class, Project, that obviously has a start date and an end date. Our goal is to force the user to enter an end date greater than the start date of the project.
To better clarify how to create a custom validator, this tutorial is divided in two steps: first we will provide server side validation, and on top of that we will add client side validation.

Step 1: Server side validation

First we create the model

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations;
using System.Web.Mvc;

namespace DateCustomValidationExample.Models
    public class Project
        public string Name { get; set; }

        public string ProjectManager { get; set; }

        [DisplayName("Start date")]
        [DisplayFormat(DataFormatString = "{0:MM/dd/yyyy}", ApplyFormatInEditMode = true)]
        public DateTime StartDate { get; set; }

        [DisplayName("Estimated end date")]
        [DisplayFormat(DataFormatString = "{0:MM/dd/yyyy}", ApplyFormatInEditMode = true)]
        [DateGreaterThan("StartDate", "Estimated end date must be greater than the start date of the project")]
        public DateTime EndDate { get; set; }
Note that we already added our custom data attribute data annotation even if it’s not yet created. In my opinion this helps us to think more about how we want to use it rather than how it should be built.
Ok, we defined how we want to use the attribute, now we must create it:
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.ComponentModel.DataAnnotations;
using System.Web.Mvc;

namespace DateCustomValidationExample.Models
    [AttributeUsage(AttributeTargets.Property, AllowMultiple=true)]
    public class DateGreaterThanAttribute : ValidationAttribute
        string otherPropertyName;

        public DateGreaterThanAttribute(string otherPropertyName, string errorMessage)
            : base(errorMessage)
            this.otherPropertyName = otherPropertyName;

        protected override ValidationResult IsValid(object value, ValidationContext validationContext)
            ValidationResult validationResult = ValidationResult.Success;
                // Using reflection we can get a reference to the other date property, in this example the project start date
                var otherPropertyInfo = validationContext.ObjectType.GetProperty(this.otherPropertyName);
                // Let's check that otherProperty is of type DateTime as we expect it to be
                if (otherPropertyInfo.PropertyType.Equals(new DateTime().GetType()))
                    DateTime toValidate = (DateTime)value;
                    DateTime referenceProperty = (DateTime)otherPropertyInfo.GetValue(validationContext.ObjectInstance, null);
                    // if the end date is lower than the start date, than the validationResult will be set to false and return
                    // a properly formatted error message
                    if (toValidate.CompareTo(referenceProperty) < 1)
                        validationResult = new ValidationResult(ErrorMessageString);
                    validationResult = new ValidationResult("An error occurred while validating the property. OtherProperty is not of type DateTime");
            catch (Exception ex)
                // Do stuff, i.e. log the exception
                // Let it go through the upper levels, something bad happened
                throw ex;

            return validationResult;

Notice how the attribute extends ValidationAttribute and overrides IsValid method, in which we perform the custom validation.

Now we need aController and aView to test the validation.

Create a HomeController with a simple Index action method, build the project and then add a strongly typed View bound to our model, choosing the “Create” item into the scaffolding  menu.
To simplify user interaction, we will use the standard  jQuery datepicker component to let the user choose the dates.
In order to use it, we must add the following references to our page (or into the master layout page)
<script src="../../Scripts/jquery-1.x.x.js" type="text/javascript"></script>
<script src="../../Scripts/jquery-ui-1.x.x.js" type="text/javascript"></script>
<link href="../../Content/themes/base/jquery.ui.all.css" rel="stylesheet" type="text/css" />
Where x.x is the version you currently have installed.
To bind the datepicker method to our input fields, we use the following jquery code
    $().ready(function () {
        return false;

Then, in order to use server side validation, we need to add the following code to our HomeController to handle form submit

// POST: /Home/
public ActionResult Index(Project model)
   return View(model);
If we run the project and inspect the HTML emitted, this is what we see:
HTML5 emitted  with the server side validation

HTML5 emitted with the server side validation

As expected there is no custom data attribute related to our custom rule.

Then we can insert two dates that will trigger the error message and we get the error message as we expected
Validation error message

Validation error message

That’s it for server-side validation.

Client side validation

Now on to the second part of this tutorial, where we will achieve client side validation.
Before we start, a few important notes (taken directly from the blog  of one of the developers of Asp.Net MVC 3)

jQuery Validate requires your input elements to be inside of a <form> element in order to be validated. In addition, MVC 3 requires that you have called Html.BeginForm() to render this form, so that it can find its book-keeping object to help render the HTML attributes.

Writing a client-side validator involves two steps:

  1. adding one more method to our DateGreaterThanAttribute
  2. writing some jQuery code to create a validation rule and what is called an adapter, which takes the parameter values from the HTML attributes and turns it into jQuery Validate metadata.
Note that we need to write a custom adapter since the default collection doesn’t come with what we need! Otherwise, there is an adapter collection available at jQuery.validator.unobtrusive.adapters.
Let’s go back to our DateGreaterThanAttribute class and modify it so that it implements the IClientValidatable, which, as MSDN says, provides a way for the ASP.NET MVC validation framework to discover at run time whether a validator has support for client validation.
Since we are implementing it, we need to write the method GetClientValidationRules like the following:
public IEnumerable<ModelClientValidationRule> GetClientValidationRules(ModelMetadata metadata, ControllerContext context)
            //string errorMessage = this.FormatErrorMessage(metadata.DisplayName);
            string errorMessage = ErrorMessageString;

            // The value we set here are needed by the jQuery adapter
            ModelClientValidationRule dateGreaterThanRule = new ModelClientValidationRule();
            dateGreaterThanRule.ErrorMessage = errorMessage;
            dateGreaterThanRule.ValidationType = "dategreaterthan"; // This is the name the jQuery adapter will use
            //"otherpropertyname" is the name of the jQuery parameter for the adapter, must be LOWERCASE!
            dateGreaterThanRule.ValidationParameters.Add("otherpropertyname", otherPropertyName);

            yield return dateGreaterThanRule;

Important: The metadata expressed for this rule will be used by the runtime to emit the HTML5 data-val custom attributes!

Now we need to create the jQuery validation function and the jQuery adapter.
We can create a separate .js file, thus we can reuse the code.
Let’s create a new Folder into /Scripts and call it “Custom”, then let’s create a new script called CustomValidation.js.
Let’s see the code:
/* File Created: January 16, 2012 */

// Value is the element to be validated, params is the array of name/value pairs of the parameters extracted from the HTML, element is the HTML element that the validator is attached to
$.validator.addMethod("dategreaterthan", function (value, element, params) {
    return Date.parse(value) > Date.parse($(params).val());

/* The adapter signature:
adapterName is the name of the adapter, and matches the name of the rule in the HTML element.

params is an array of parameter names that you're expecting in the HTML attributes, and is optional. If it is not provided,
then it is presumed that the validator has no parameters.

fn is a function which is called to adapt the HTML attribute values into jQuery Validate rules and messages.

The function will receive a single parameter which is an options object with the following values in it:
The HTML element that the validator is attached to

The HTML form element

The message string extract from the HTML attribute

The array of name/value pairs of the parameters extracted from the HTML attributes

The jQuery rules array for this HTML element. The adapter is expected to add item(s) to this rules array for the specific jQuery Validate validators
that it wants to attach. The name is the name of the jQuery Validate rule, and the value is the parameter values for the jQuery Validate rule.

The jQuery messages array for this HTML element. The adapter is expected to add item(s) to this messages array for the specific jQuery Validate validators that it wants to attach, if it wants a custom error message for this rule. The name is the name of the jQuery Validate rule, and the value is the custom message to be displayed when the rule is violated.
$.validator.unobtrusive.adapters.add("dategreaterthan", ["otherpropertyname"], function (options) {
    options.rules["dategreaterthan"] = "#" + options.params.otherpropertyname;
    options.messages["dategreaterthan"] = options.message;

Let’s look at it in more details:
$.validator.addMethod("dategreaterthan", function (value, element, params) {
    return Date.parse(value) > Date.parse($(params).val());
The first parameter for addMethod is the name that identifies the rule and can be different from what we used inside GetClientValidationRules => dateGreaterThanRule.ValidationType = “dategreaterthan”;
In this example is the same, but you can change it.
The second parameter is the actual validator, in this case simply a comparison between two dates.

The adapter instead is tightly coupled with GetClientValidationRules implementation, therefore the first parameter must match the name we used in the code of our custom attribute for the validationType.

The second parameter is an array of parameters name.

In our case we only added one parameter

dateGreaterThanRule.ValidationParameters.Add("otherpropertyname", otherPropertyName);
so our array will have only one parameter. Should we have more, it would look like [“param1”, “param2”, ….]
The third parameter is a function which is called to adapt the HTML attribute values into jQuery Validate rules and messages.
options.rules["dategreaterthan"] //"dategreaterthan", the key to identify the rule, must match what we used in the addMethod as first parameter.
options.rules["dategreaterthan"] = "#" + options.params.otherpropertyname;

we use the # so that the value stored will be something like “#StartDate”, that is ready to be consumed by the validation rule previously wrote to get the value out of the StartDate field.

The javascript is done! Now let’s go back to our View because we need to add all the references we need to run the unobtrusive validation:
<script src="../../Scripts/jquery.validate.js" type="text/javascript"></script>
<script src="../../Scripts/jquery.validate.unobtrusive.js" type="text/javascript"></script>
<script src="../../Scripts/MicrosoftMvcAjax.js" type="text/javascript"></script>
<script src="../../Scripts/Custom/CustomValidation.js" type="text/javascript"></script>

Everything’s done and now we can run the app. If we inspect the HTML that has been emitted this is what we see

HTML emitted with client side validation

HTML emitted with client side validation

and if we run the application we will see the same error message as before, with no form submit!

The source code is available on my github at the following URL: https://github.com/vgheri/DateCustomValidationExample

That’s all for the unobtrusive custom validation with MVC 3.

I hope this helps,


Handling transactions in .Net using TransactionScope


Heads up!

The blog has moved!
The new URL to bookmark is http://blog.valeriogheri.com/


For one of the projects I’m currently working on, I had to refactor a (sort of) data access layer and move it from nHibernate technology to stored procedures.
During the code review process, I noticed there were some macro logical operations made of several short-lived and concise activities that were perfect to group together inside transactions.
I didn’t want to group them inside some bloated stored procedure, taking some of the logic away from the code into the DB, so I decided to look at what the framework had to offer, and this is how I was carried into TransactionScope world.

When using transaction is a good idea and when it isn’t 

Transactions are great when you can group a set of short and quick activities together under a transaction. If any of those activities fail, the whole transaction would fail and rollback all the already done work. Everything is taken care of automatically by the framework, ensuring data consistency.
While the transaction is being executed, the database engine keeps required resources in a locked state, and this means that no one else can use locked data (the degree of freedom depends on the isolation level which the transaction is currently running on. More on this later).
Now imagine your transaction is taking many minutes or hours (or more) to complete… this could potentially create deadlocks or starving situations or timeouts of other operations! Definetely not a good scenario, isn’t it?

TransactionScope Class: the framework to the rescue 

Before you start, I strongly suggest you start reading the fundamentals here if you didn’t do it yet.
Let’s start with some examples to see it in action:
private static void BaseCaseSuccessTest()
    //Let's get the connection to SQL Server
    var connection = GetConnection();
        using (TransactionScope rootScope = new TransactionScope())
            using (connection)
                // All code placed here will take part in the transaction
    catch (TransactionAbortedException tae)
        Console.WriteLine("Test aborted: " + tae.Message);
All the code placed inside the TransactionScope using statement will be executed inside the same ambient transaction, even if it’s code belonging to an external dll!
Furthermore, whenever using the default constructor we are implicitly asking the transaction manager to check if an existing ambient transaction is present, creating it if it isn’t, and then joining it.
We are also asking the framework to create a transaction with the default timeout (set to 1 minute) and with isolation level set to Serializable (more on this later).
Now, what if we want to do some non transactional work in the middle of a transaction, without leaving it?
One of  TransactionScope’s constructor accepts the TransactionScopeOption enumeration as a parameter, and we can set it to Suppress like I do in the following example:
private static void SuppressTest()
    var connection = GetConnection();
        using (TransactionScope scope1 = new TransactionScope())
            using (connection)
                // Do some work
                using (TransactionScope scope2 = new TransactionScope(TransactionScopeOption.Suppress))
                    // Non transactional work here

                    var current = Transaction.Current; // current is equal to null

                    // This will create a new ambient transaction, as the upper level (scope3) is currently running with no ambient transaction
                    using (TransactionScope scope3 = new TransactionScope(TransactionScopeOption.Required))
                        current = Transaction.Current;  // current is now not null

                    // Calling scope2.Complete() is not mandatory, given that the operations here are non transactional, but it is nevertheless
                    // recommended to do so for consistency sake among the code
    catch (TransactionAbortedException tae)
        Console.WriteLine("Test aborted: " + tae.Message);
We can even create a new transaction inside the Suppress block of code!
It is important to note that if for any reason the code executed inside the Suppress block of code fails, the ambient transaction created with scope1 will not be aborted!
It’s also worth noting that calling scope3.Complete() in this case is not mandatory, given that we are not inside a transaction, but it’s nevertheless recommended for the sake of code consistency.

Transaction isolation level

I will start citing MSDN here:
“By default, the transaction executes with isolation level set to Serializable. Selecting an isolation level other than Serializable is commonly used for read-intensive systems. […]
Every isolation level besides Serializable is susceptible to inconsistency resulting from other transactions accessing the same information.”

Now, what does it mean in terms of performance that the default isolation level is set to Serializable? Let’s see what wikipedia has to say about it:
“This is the highest isolation level. It specifies that all transactions occur in a completely isolated fashion, or, in other words, as if all transactions in the system had executed serially, one after the other. The DBMS may execute two or more transactions at the same time only if the illusion of serial execution can be maintained.
With a lock-based concurrency control DBMS implementation, serializability requires read and write locks (acquired on selected data) to be released at the end of the transaction.“

As pointed out in this MSDN blog, the default behaviour can be harmful if you don’t know exactly what you’re doing and what usage patterns your system will have, because you might end up having deadlock and timeout problems, without a clue about why this is happening!

Let’s now see an example that shows how to create a non default TransactionScope object, manually setting the isolation level to ReadCommitted and the timeout for our transaction:

private static void TransactionWithIsolationAndTimeout()
    var transactionScopeOptions = new TransactionOptions();
    // The default isolation level value is Serializable
    // Here we explicitely ask the framework to create a transaction with isolation level ReadCommitted:
    // Volatile data cannot be read during the transaction, but can be modified.
    transactionScopeOptions.IsolationLevel = System.Transactions.IsolationLevel.ReadCommitted;
    transactionScopeOptions.Timeout = TimeSpan.MaxValue;
    var connection = GetConnection();
        using (TransactionScope scope1 = new TransactionScope(TransactionScopeOption.Required, transactionScopeOptions))
            using (connection)
                // Do transactional work using DB connection
    catch (TransactionAbortedException tae)
        Console.WriteLine("Test aborted: " + tae.Message);

To end this topic, it’s important to note that when using nested TransactionScope objects, all nested scopes must be configured to use exactly the same isolation level if they want to join the ambient transaction. If a nested TransactionScope object tries to join the ambient transaction yet it specifies a different isolation level, an ArgumentException is thrown.

Local transaction vs. Distributed one

Up until now we’ve seen examples of just one SQL connection shared amongst several TransactionScope objects (and sometimes transactions), opened and closed only once.
This means that only one SQL server and one database is concerned.
This is what is called a local transaction, also known as lightweight.
A distributed transaction is a local transaction that has been escalated to MSDTC (Microsoft Distributed Transaction Coordinator).
Lightweight transactions should be the preferred solution, when possible, due to better performance because escalating to MSDTC adds overhead to the whole process (and saves some headache configuring it!).
So, how to avoid escalating? There is a lot about this topic on the internet because it’s not easy to understand exactly when a transaction is escalated and how to configure MSDTC to correctly handle your requests.
Browsing Stack Overflow I found a very interesting post  that casts some bright light on the problem and that  you can read for yourself.
Anyway to summarize and to remain practical, SQL Server 2005 and 2008 have different behaviour handling and escalating transactions:


  • Allows multiple connections, not simultaneously open, within a single TransactionScope without escalating to MSDTC.
  • If those multiple SqlConnections are nested, that is, two or more SqlConnections are opened at the same time, TransactionScope will immediately escalate to DTC.
  • If an additional SqlConnection is opened to a different ‘durable resource’ (ie: a different SQL Server or a different database inside the same SQL Server) it will immediately escalate to DTC


  • Does not allow multiple connections within a single TransactionScope. It will escalate when a second SqlConnection is opened, even if the previous one has been already closed.

The following code will escalate

using (TransactionScope transactionScope = new TransactionScope()) {
   using (SqlConnection connection = new   SqlConnection(connectionString)) {
      connection.Open(); // escalates to DTC

This ends my article on how to handle transactions with TransactionScope object using the .Net framework, and I hope it will save you some time and headache while dealing with it!