Getting started with NHibernate on Azure table Storage services

In order to get NHibernate running on top of azure table storage, you first need an azure account obviously, or at least have installed the development fabric. I assume you’ve got that covered before attempting this tutorial.

Next up is to download and compile the NHibernate azure table storage driver from http://nhazuredriver.codeplex.com/. It already includes a test project that shows you how to get started. If you want to try it out, I suggest you continue from there.

Setting up the driver and it’s connection

First thing to do is to set up a SessionFactory that has been configured to use the driver and that has a connection to your azure storage account. The easiest way to do this is to use the Fluent NHibernate API, for which a configuration is included in the driver. This configuration is connecting to development storage by default, but you can pass it a connection string in any of the formats specified by MSDN:

var fluentConfiguration = Fluently.Configure().Database(
                AzureConfiguration.TableStorage
                .ProxyFactoryFactory(typeof(ProxyFactoryFactory).AssemblyQualifiedName)
                .ShowSql())
fluentConfiguration.Mappings(cfg => cfg.HbmMappings.AddFromAssemblyOf<NewsItem>());
sessionFactory = fluentConfiguration
                .ExposeConfiguration(cfg => nHibernateConfiguration = cfg)
                .BuildSessionFactory();

Note that I’ve exposed the internal nHibernate configuration, I will use it to tell NHibernate to create the schema in the table storage service. In reality, the underlying store doesn’t have a concept of schema, only the table name is registered.

using (var session = sessionFactory.OpenSession())
{
       var export = new SchemaExport(nHibernateConfiguration);
       export.Execute(true, true, false, session.Connection, null);
       session.Flush();
}

Mapping files

The azure storage environment does pose some restrictions to what you can specify in a mapping file as well:

  • The identifier must be a composite key which includes the fields RowKey and PartitionKey, both must be of type string (no exceptions)
  • All references, between entities in different tables, must be lazy loaded, join fetching (or any other relational setting for that matter) is not supported

A simple mapping file would look like:

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"
                   assembly="NHibernate.Drivers.Azure.TableStorage.Tests"
                   namespace="NHibernate.Drivers.Azure.TableStorage.Tests.Domain">

  <class name="NewsItem" table="NewsItems">
    <composite-id>
      <key-property name="Id" column="RowKey" />
      <key-property name="Category" column="PartitionKey"/>
    </composite-id>
    <property name="Title" type="String" />
  </class>

</hibernate-mapping>

Persisting instances

Now we’re ready to go: save, update, get, load, list, delete, etc are all operational. In order to test this quickly, you could run a PersistenceSpecification from the FluentNHibernate library.

using (var session = SessionFactory.OpenSession())
 {
        new PersistenceSpecification<NewsItem>(session)
            .CheckProperty(c => c.Id, "1")
            .CheckProperty(c => c.Title, "Test Title")
            .CheckProperty(c => c.Category, "Test Category")
            .VerifyTheMappings();
 }

Some remarks

Please note that azure table storage DOES NOT support transactions, so all data you put in the store during testing must be removed before executing the next test. PersistenceSpecifciation does this by default, but in other tests you might have to do it yourself.

Also most NHibernate settings that rely on relational storage features, such as joins, batches, complex queries, etc… don’t work (yet). There is a lot of room for improvement, so any contributions are welcome…

Happy coding.

Introducing the nhibernate azure table storage driver

For some time now, I’ve been working, together with Koen Callens, on a driver for NHibernate on top of the azure table storage services api. Today, Im proud to announce that the project has finally found a public home at: http://nhazuredriver.codeplex.com/

The primary goal of the NHibernate Azure Table Storage Driver is to ease the coding experience on top of the azure table storage services api and to benefit from the features offered by NHibernate such as identity mapping, caching, and the like. If you’ve ever dealt with handcrafting these requests or used the storage client, than you know what I mean…

But remember, azure table storage is not a relational database, so you cannot benefit from a lot of the features that you might have grown accustomed to. In the next few days, I’ll give you some more insight into how to use NHibernate on top of azure table storage.

If you’re interested in contributing to the project, just send me a mail…