First, we need to apply a where clause to all queries to ensure that each tenant sees only their data. This is pretty painless with NHibernate and completely transparent to the existing application! We just have to define a parameterized filter:

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2">

  <filter-def name="tenant">

    <filter-param name="id" type="System.Int32" />

  </filter-def>

</hibernate-mapping>

And then apply it to each entity:

<class name="User" table="[user]">

  <id name="Id" column="user_id">

    <generator class="identity" />

  </id>

  <property name="Username" />

  <property name="Email" />

  <filter name="tenant" condition="tenant_id = :id" />

</class>

The last step is to set the value of the filter at runtime. This is done on the ISession like this:

Container

    .RegisterType<ISession>(

        new PerRequestLifetimeManager(),

        new InjectionFactory(c =>

        {

            var session = c.Resolve<ISessionFactory>().OpenSession();

            session.EnableFilter("tenant").SetParameter("id", c.Resolve<Tenant>().Id);

            return session;

        })

    );

The current tenant comes from c.Resolve<Tenant>(). In order for that to work, you have to tell Unity how to find the current tenant. In ASP.NET MVC, we can look at the host header on the request and find our tenant that way. We could just as easily use another strategy though. Maybe if this were a WCF service, we could use an authentication header to establish the current tenant context. You could build out some interfaces and strategies around establishing the current tenant context, however for this article I’ll just bang it out.

Container

    .RegisterType<Tenant>(new InjectionFactory(c =>

    {

        var repository = c.Resolve<ITenantRepository>();

        var context = c.Resolve<HttpContextBase>();

        var host = context.Request.Headers["Host"] ?? context.Request.Url.Host;

        return repository.FindByHost(host);

    }));

Second, we have to set the tenant_id when new entities are saved. This is a bit more complicated with NHibernate and requires a bit of a concession in that we have to add a field to the entity in order for NHibernate to know how to persist the value. I’m using a private nullable int for this.

public class User

{

    private int? tenantId;

    public virtual int Id { get; set; }

    public virtual string Username { get; set; }

    public virtual string Email { get; set; }

}

It’s private because I don’t want the business logic to deal with it and it’s nullable because my tenant table is in a separate database which means I can’t lean on the data model to enforce referential integrity. That’s a problem because the default value for an integer is zero which could be happily saved by the database. By making it nullable I can be sure the database will blow up if the tenant_id is not set.

So, back to the issue at hand. The tenant_id needs to be set when the entity is saved. For this, I’m using an interceptor and setting the value in the OnSave method:

public class MultiTenantInterceptor : EmptyInterceptor

{

    private readonly Func<Tenant> tenant;

    public MultiTenantInterceptor(Func<Tenant> tenant)

    {

        this.tenant = tenant;

    }

    public override bool OnSave(object entity... object[] state, string[] propertyNames...)

    {

        var index = Array.IndexOf(propertyNames, "tenantId");

        if (index == -1)

            return false;

        var tenantId = tenant().Id;

        state[index] = tenantId;

        entity

            .GetType()

            .GetField("tenantId", BindingFlags.Instance | BindingFlags.NonPublic)

            .SetValue(entity, tenantId);

        return false;

    }

}

This IInterceptor mechanism is a little wonky. If you change any data, you have to do it in both the entity instance and the state array that NHibernate uses to hydrate entities. It’s not a big deal, it’s just one of those things you have to accept like the fact that Apple and Google are tracking your every move via your smart phone. Oh, and the interceptor gets wired up like this:

Container

    .RegisterType<ISessionFactory>(

        new ContainerControlledLifetimeManager(),

        new InjectionFactory(c =>

        {

            return new NHibernate.Cfg.Configuration()

                .Configure()

                .SetInterceptor(new MultiTenantInterceptor(() => c.Resolve<Tenant>()))

                .BuildSessionFactory();

        })

    );

We’re almost done. There is one more case that needs to be handled. When NHibernate loads an entity by its primary key, it doesn’t run through the query engine which means the tenant filter isn’t applied. Fortunately, we can take care of this in the interceptor:

public class MultiTenantInterceptor : EmptyInterceptor

{

    ...

    public override bool OnLoad(object entity... object[] state, string[] propertyNames...)

    {

        var index = Array.IndexOf(propertyNames, "tenantId");

        if (index == -1)

            return false;

        var entityTenantId = Convert.ToInt32(state[index]);

        var currentTenantId = tenant().Id;

        if (entityTenantId != currentTenantId)

        {

            throw new AuthorizationException("Permission denied to {0}", entity);

        }

        return false;

    }

}

That’s it. Have fun and happy commingling.

Build a web application as though it’s for a single customer (tenant) and add multi-tenancy as a bolt-on feature by writing only new code. There are flavors of multi-tenancy, in this case I want each tenant to have its own database but I want all tenants to share the same web application and figure out who’s who by looking at the host header on the http request.

The Plan:

To pull this off, we’re going to have to rely on our SOLID design principles, especially Single Responsibility and Dependency Inversion. We’ll get some help from these frameworks:

• ASP.NET MVC
• Unity
• NHibernate

Game on:

Let’s take a look at a controller that uses NHibernate to talk to the database. I’m not going to get into whether you should talk directly to NHibernate from the controller or go through a service layer or repository because it doesn’t affect how we’re going to add multi-tenancy. The important thing here is that the ISession is injected into the controller, and we aren’t using the service locator pattern to request the ISession from a singleton.

public class UserController : Controller

{

    private readonly ISession session;

    public UserController(ISession session)

    {

        this.session = session;

    }

    public ActionResult Edit(int id)

    {

        var user = session.Load<User>(id);

        return View(user);

    }

}

Alright, now it’s time to write some new code and make our web application connect to the correct database based on the host header in the http request. First, we’ll need a database to store a list of tenants along with the connection string for that tenant’s database. Here’s my entity:

public class Tenant

{

    public virtual string Name { get; set; }

    public virtual string Host { get; set; }

    public virtual string ConnectionString { get; set; }

}

I’ll use the repository pattern here so there is a crisp consumer of the ISession that connects to the lookup database rather than one of the tenant shards. This will be important later when we go to configure Unity.

public class NHibernateTenantRepository : ITenantRepository

{

    private readonly ISession session;

    private readonly HttpContextBase context;

    public NHibernateTenantRepository(ISession session, HttpContextBase context)

    {

        this.session = session;

        this.context = context;

    }

    public Tenant Current

    {

        get

        {

            var host = context.Request.Headers["Host"];

            return FindByHost(host);

        }

    }

    public Tenant FindByHost(string host)

    {

        return session

            .Query<Tenant>()

            .SingleOrDefault(t => t.Host == host);

    }

}

So now we need a dedicated ISessionFactory for the lookup database and make sure that our NHibernateTenantRepository gets the right ISession . It’s not too bad, we just need to name them in the container so we can refer to them explicitly.

Container

    .RegisterType<ISessionFactory>(

        "tenant_session_factory",

        new ContainerControlledLifetimeManager(),

        new InjectionFactory(c =>

            new NHibernate.Cfg.Configuration().Configure().BuildSessionFactory())

    );

Container

    .RegisterType<ISession>(

        "tenant_session",

        new PerRequestLifetimeManager(),

        new InjectionFactory(c =>

            c.Resolve<ISessionFactory>("tenant_session_factory").OpenSession())

    );

Container

    .RegisterType<ITenantRepository, NHibernateTenantRepository>()

    .RegisterType<NHibernateTenantRepository>(

        new InjectionConstructor(

            new ResolvedParameter<ISession>("tenant_session"),

            new ResolvedParameter<HttpContextBase>()

        )

    );

Hopefully that’s about what you were expecting since it’s not really the interesting part. The more interesting part is configuring the ISession that gets injected into the UserController to connect to a different database based on the host header in the http request. The Unity feature we’re going to leverage for this is the LifetimeManager. This is an often overlooked feature of IoC containers.

Container

    .RegisterType<ISessionFactory>(

        new PerHostLifetimeManager(() => new HttpContextWrapper(HttpContext.Current)),

        new InjectionFactory(c =>

        {

            var connString = c

                .Resolve<ITenantRepository>()

                .Current

                .ConnectionString;

            return new NHibernate.Cfg.Configuration()

                .Configure()

                .SetProperty(NHibernate.Cfg.Environment.ConnectionString, connString)

                .BuildSessionFactory();

        }));

Container

    .RegisterType<ISession>(

        new PerRequestLifetimeManager(),

        new InjectionFactory(c => c.Resolve<ISessionFactory>().OpenSession())

    );

Here we’re using a custom PerHostLifetimeManager. This tells Unity to maintain a session factory per host. When Unity runs across a host it doesn’t have a session factory for, it will run the InjectionFactory block to create one using the connection string associated with that tenant.

Since multiple simultaneous requests will be trying to get and set values with the same key, we need to make sure our PerHostLifetimeManager is thread safe. That’s pretty easy since Unity comes with a SynchronizedLifetimeManager base class that takes care of the fact that Dictionary isn’t thread safe.

public class PerHostLifetimeManager : SynchronizedLifetimeManager

{

    private readonly Func<HttpContextBase> context;

    private readonly IDictionary<string, object> store;

    public PerHostLifetimeManager(Func<HttpContextBase> context)

    {

        this.context = context;

        store = new Dictionary<string, object>();

    }

    protected override object SynchronizedGetValue()

    {

        var host = GetHost();

        if (!store.ContainsKey(host))

            return null;

        return store[host];

    }

    protected override void SynchronizedSetValue(object newValue)

    {

        store[GetHost()] = newValue;

    }

    private string GetHost()

    {

        return context().Request.Headers["Host"];

    }

}

So what did we accomplish? Well we didn’t touch any of our existing application code. We just wrote new code and through configuration we added multi-tenancy! That’s pretty cool, but was it worth it? Well, the goal in itself isn’t super important, but this exercise can certainly highlight areas of your codebase where you might be violating the single responsibility principle or leaking too many infrastructure concepts into your application logic.

public class Product {
    public int Id { get; set; }

    [Required]
    public string Description { get; set; }

    [Required]
    [RegularExpression(@"^\$?\d+(\.(\d{2}))?$")]
    public decimal UnitPrice { get; set; }
}

Just for the record, this is a cool bit of code that was released to the community for backseat drivers like me to use and complain about. I’m really only bitter because I can’t use it. Let’s take a peek at the source code to see why:

/// <summary>
/// An implementation of IModelBinder which is designed to be a replacement
/// default model binder, adding the functionality of validation via the validation
/// attributes in System.ComponentModel.DataAnnotations from .NET 4.0.
/// </summary>
public class DataAnnotationsModelBinder : DefaultModelBinder {
    ...
}

The problem with this class is that it’s not just about validation. It’s more about binding with validation sprinkled in. The author even states this as a design goal with the comment “designed to be a replacement default model binder.” This is a violation of the Single Responsibility Principle and it’s the reason I can’t use it. The DefaultModelBinder does some basic reflection mapping of form elements to model properties. That’s cool, but what about a controller action that takes json, xml, or anything slightly more complicated than what the default binder can handle?

I’ll tell you what happens. You write a custom model binder which is pretty easy and happens to be a pretty rad extension point in the MVC framework. Consider this model binder that deserializes json:

public class JsonModelBinder<T> : IModelBinder {
    private string key;

    public JsonModelBinder(string requestKey) {
        this.key = requestKey;
    }

    public object BindModel(ControllerContext controllerContext, ...) {
        var json = controllerContext.HttpContext.Request[key];
        return new JsonSerializer().Deserialize<T>(json);
    }
}

That’s pretty cool, but now I’ve lost my validation! This my friend is the evil of inheritance and the epic fail of the DataAnnotationsModelBinder. So what’s wrong with inheritance, isn’t that what OOP is all about? The short answer is no (the long answer is also no.)

Human sacrifice, dogs and cats living together… mass hysteria! — Dr. Peter Venkman

Inheritance is pretty enticing especially coming from procedural-land and it often looks deceptively elegant. I mean all I need to do is add this one bit of functionality to another other class, right? Well, one of the problems is that inheritance is probably the worst form of coupling you can have. Your base class breaks encapsulation by exposing implementation details to subclasses in the form of protected members. This makes your system rigid and fragile.

The more tragic flaw however is the new subclass brings with it all the baggage and opinion of the inheritance chain. Why does a model that enforces validation attributes care how the model is constructed? The answer is it shouldn’t, and to add insult to injury, the better design is actually easier to implement. Listen closely and you may hear the wise whispers of our forefathers…

Use the decorator pattern.

Is this really going to solve all my problems? The short answer is yes. Let’s take a look:

public class BetterDataAnnotationsModelBinder : IModelBinder {
    private IModelBinder binder;

    public BetterDataAnnotationsModelBinder(IModelBinder binder) {
        this.binder = binder;
    }

    public object BindModel(ControllerContext controllerContext, ...) {
        var model = binder.BindModel(controllerContext, bindingContext);
        AddValidationErrorsToModelState(model, controllerContext);
        return model;
    }

    ...
}

Now all this class does is enforce validation and we can use whatever model binder we want to construct our object. Let’s wire this up in the Global.asax real quick:

var productModelBinder = new JsonModelBinder<Product>("product");

ModelBinders.Binders.Add(
    typeof(Product),
    new BetterDataAnnotationsModelBinder(productModelBinder));

This is cool for the following reasons:

1. We are not coupled to the DefaultModelBinder. This means we don’t know or care about the structure and implementation details of it so it’s free to change in the next version of ASP.NET MVC.
2. The code is simpler because it is only about validation.
3. The behavior is composable. This means we can add validation to any model binder (like our json model binder) and bolt on more responsibilities with a chain of decorators. How about converting DateTime fields to UTC or striping formatting characters from phone numbers?
4. It’s easy to test.

You can substitute a decorator for a subclass in most cases and in most cases it’s the right choice. You’re better off making the decorator your default choice and only settle for inheritance when you really need it.

…don’t be jealous that I’ve been chatting online with babes all day. Besides, we both know that I’m training to be a cage fighter. — Kip

The built-in model binder can handle the easy fields like FirstName, LastName, and Email, but it doesn’t know how to deal with the roles. This is where the custom model binder comes in:

public class UserModelBinder : IModelBinder {
    private readonly IModelBinder binder;

    public UserModelBinder(IModelBinder binder) {
        this.binder = binder;
    }

    public object BindModel(ControllerContext controllerContext, ...) {
        var user = (User)binder.BindModel(controllerContext, bindingContext);
        AddRoles(user, controllerContext);
        return user;
    }

    private static void AddRoles(User user, ControllerContext controllerContext) {
        foreach (var role in GetRoles(controllerContext)) {
            user.Add(role);
        }
    }

    private static IEnumerable<Role> GetRoles(ControllerContext controllerContext) {
        var roles = controllerContext.HttpContext.Request["roles"];
        if (roles == null) yield break;
        foreach (var roleId in roles.Split(',')) {
            yield return (Role)Convert.ToInt32(roleId);
        }
    }
}

And it gets wired-up in the Global.asax like this:

var defaultBinder = new DataAnnotationsModelBinder();
ModelBinders.Binders.DefaultBinder = defaultBinder;
ModelBinders.Binders.Add(typeof(User), new UserModelBinder(defaultBinder));

Because UserModelBinder is a decorator, it preserves the base functionality (like validation) of the default binder and only adds the part about mapping the roles. This is good stuff because it keeps construction of the model out of the controller. That’s the Single-Responsibility Principle in action.

Command Query Separation

The two functions AddRoles, and GetRoles are an example of command query separation (CQS). It would be easy to combine those two functions together and in fact that’s how it looked at first. So why bother separating them? Well it doesn’t really matter in this simple case, but it’s like how I tell my 3 year-old son to move his milk cup away from the edge of the table. I figure it’s a good habit that will prevent a few spills in the long run. The idea with CQS is there is a natural seam between finding objects and doing stuff with them. I buy that. I expect GetRoles to be more volatile than AddRoles or at least change for different reasons.

Before I get into the guts, I would like to provide a little context. My application has 20+ databases scattered across 4 machines.

IRepository<Customer> customerRepository; // customer database on server 1
IRepository<Package>  packageRepository; // customer database on server 1
IRepository<Contact>  contactRepository; // contact database on server 2

The “magic” if you will, happens in the global.asax. I was nosing around in Rhino.Commons for inspiration and adapted a technique I saw there. This is how it looks:

public class GlobalApplication : HttpApplication
{
    private static IUnityContainer container;

    public GlobalApplication()
    {
        BeginRequest += new EventHandler(GlobalApplication_BeginRequest);
        EndRequest += new EventHandler(GlobalApplication_EndRequest);
    }

    protected void Application_Start(object sender, EventArgs e)
    {
        RegisterRoutes(RouteTable.Routes);

        container = new UnityContainer();
        container.AddNewExtension<PolicyInjectorContainerExtension>();
        container.AddNewExtension<HttpRequestLifetimeCoreContainerExtension>();
        container.AddNewExtension<WebMvcContainerExtension>();

        ControllerBuilder.Current.SetControllerFactory(new UnityControllerFactory(container));
    }

    void GlobalApplication_BeginRequest(object sender, EventArgs e)
    {
        var unitOfWork = container.Resolve<IUnitOfWork>();
        unitOfWork.Start();
    }

    void GlobalApplication_EndRequest(object sender, EventArgs e)
    {
        var unitOfWork = container.Resolve<IUnitOfWork>();
        unitOfWork.Commit();
    }
}

I register the UoW with an HttpRequestLifetimeManager so I get a new instance for each request.

Container.RegisterType<IUnitOfWork<ISession>,
	NHibernateUnitOfWork>(new HttpRequestLifetimeManager());

public class NHibernateRepository<T> : IRepository<T>
{
    protected ISession session;

    public NHibernateRepository(IUnitOfWork<ISession> unitOfWork)
    {
        session = unitOfWork.GetContextFor<T>();
    }

    ...

    public virtual void Save(T obj)
    {
        session.Save(obj);
    }
}

Now, this is all the context of an ASP.NET MVC Controller, but I have a similar issue for other (non-web) services. In that context I am using AOP and decorating a particular method with [UnitOfWork], which looks like:

public class UnitOfWorkCallHander : ICallHandler
{
    private IUnitOfWork<ISession> unitOfWork;

    public UnitOfWorkCallHander(IUnitOfWork<ISession> unitOfWork)
    {
        this.unitOfWork = unitOfWork;
    }

    public int Order { get; set; }

    public IMethodReturn Invoke(IMethodInvocation input, GetNextHandlerDelegate getNext)
    {
        unitOfWork.Start();

        try
        {
            return getNext()(input, getNext);
        }
        finally
        {
            unitOfWork.Commit();
        }
    }
}

In that context I use a PerThreadLifetimeManager for the NHibernateUnitOfWork, and code ends up looking like:

[UnitOfWork]
public void Process(Job job)
{
    ...
}

You know, there is really no reason why you couldn’t do the same thing in the MVC context. You could basically ditch the global.asax event hooha and just annotate the Controller task:

[UnitOfWork]
public ActionResult ControllerTaskThatRequiresUoW()
{
    ...
}

It’s more explicit than using the global.asax technique and it would allow you to specify different UoW behavior on each controller task:

[UnitOfWork(IsolationLevel.ReadCommitted]
public ActionResult SomeTaskThatShouldNotReadUncommitedData()
{
}

[UnitOfWork(IsolationLevel.ReadUncommitted)]
public ActionResult AnotherTaskWithDifferentRequirements()
{
}

I’d like to try this out next time I get back into ASP.NET MVC, the global.asax event technique felt a little too magical and I don’t think Uncle Bob would approve.

So, here it is in action. Below is a controller from an ASP.NET MVC application. The method accepts an order in the form of xml for provisioning products in our system.

public ActionResult EnqueueOrders(string orderXml)
{
    var context = new OrderContext(orderXml);

    var pipeline = new FilterPipeline<OrderContext>()
        .Add(new RewriteLegacyUsernameFeature(productFinder))
        .Add(new ValidateOrderXml())
        .Add(new ValidateReferenceCode(customerFinder))
        .Add(new IgnoreOnException(new ValidateRemoteAccountUsernames(packageRepository)))
        .Add(new IgnoreOnException(new ValidateRemoteAccountUniqueEmail(packageRepository)))
        .Add(new EnqueueOrders(customerFacade)).When(new OrderHasNoErrors())
        .Execute(context);

    var xml = BuildResponseFromOrderContext(context);

    return new XmlResult(xml);
}

Most of it is just validation logic, but there are a few meatier pieces. Take a look a the first filter – RewriteLegacyUsernameFeature. If you’ve ever published an API that accepts xml, then you’ve probably wanted to change your schema 5 minutes later. The pipeline is great way to deal with transforming legacy xml on the way in.

Next is the implementation of the FilterPipeline which is essentially a chain of responsibility with a few convenience features.

public class FilterPipeline<T> : IFilter<T>
{
    private IFilterLink<T> head;

    public void Execute(T input)
    {
        head.Execute(input);
    }

    public IFilterConfiguration<T> Add(IFilterLink<T> link)
    {
        var specificationLink = new SpecificationFilterLink<T>(link);

        AppendToChain(specificationLink);

        return specificationLink;
    }

    public IFilterConfiguration<T> Add(IFilter<T> filter)
    {
        return Add(new FilterLinkAdapter<T>(filter));
    }

    public void AppendToChain(IFilterLink<T> link)
    {
        if (head == null)
        {
            head = link;
            return;
        }

        var successor = head;

        while (successor.Successor != null)
        {
            successor = successor.Successor;
        }

        successor.Successor = link;
    }
}

You might be scratching your head and wondering what this business is with both IFilter<T> and IFilterLink<T>. IFilter<T> is just a simpler version of IFilterLink<T> that doesn’t require the implementer to deal with calling the next link in the chain. The subject will always pass through, no short-circuiting, hence the pipeline.

My favorite part  is the SpecificationFilterLink<T> which is a decorator that uses a Specification to decide if the filter should be invoked. So you can do little readable snippets like:

pipeline.Add(new EnqueueOrders(customerFacade)).When(new OrderHasNoErrors());

Maybe this post will get it out of my system and I can move on to other solutions. It’s just so handy…