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.

Advertisements

2 Responses to Getting started with NHibernate on Azure table Storage services

  1. aph5 says:

    Is it possibile to use nhibernate.search with this driver ?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: