Query

Linq to NHibernate

NHibernate's Answers — Wed, 26 Nov 2008 17:13:20 GMT

The popularity of NHibernate is steadily increasing. At the same time people get used to LINQ. Now there exists a LINQ to NHibernate provider since quite some time. It's not a complete implementation of a LINQ provider but it is still quite useful. Most of the day to day problems we face when developing typical business application can be solved by using this provider. And if there is a query that cannot be executed against the provider we still have the option to falling back to the hibernate query language (HQL).

In this post I'll give you an introduction on how you can use NHibernate in conjunction with LINQ. Let's start with the definition of a domain model we are going to use when querying the database by using LINQ expressions or LINQ query operators.

The domain model

I have the following simple domain model. A person can have a set of assigned tasks.

The entities

I want to keep the entities as simple as possible for this example. So their implementation is as follows

public class Person

    public Person()

        Tasks = new List<Task>();

    public virtual long Id { get; set; }

    public virtual string Lastname { get; set; }

    public virtual string Firstname { get; set; }

    public virtual IList<Task> Tasks { get; set; }

public class Task

    public virtual long Id { get; set; }

    public virtual string TaskName { get; set; }

    public virtual DateTime DueDate { get; set; }

one thing worth noting is the fact that I instantiate a new empty Tasks collection in the constructor of the Person class.

The mapping

For the mapping of my domain model I am going to use the Fluent NHibernate framework (please refer to my previous posts for a detailed introduction to this framework: part 1, part 2, part 3, part 4) .

The Task is very easy to map

public class TaskMap : ClassMap<Task>

    public TaskMap()

        Id(x => x.Id);

        Map(x => x.TaskName);

        Map(x => x.DueDate);

And the person is nothing more complicated

public class PersonMap : ClassMap<Person>

    public PersonMap()

        Id(x => x.Id);

        Map(x => x.Firstname);

        Map(x => x.Lastname);

        HasMany<Task>(x => x.Tasks)

            .LazyLoad()

            .Cascade.All();

Just let's have a look at the mapping of the Tasks collection. I want the tasks to only be lazy loaded when loading a person entity (LazyLoad). And I want NHibernate to automatically save or update any tasks associated with a given person if ever the person is updated (Cascade.All).

Test the mapping

One quick test I want to always do is to check whether my mappings work as expected. Since I use Fluent NHibernate this is very easy and straight forward. A lot of infrastructure code is available to me to leverage and thus simplify my unit test regarding mapping of the domain entities.

The base test fixture

First I want to present my base class I use for all of my tests. Every test fixture used in this post will inherit from this base class.

public class FixtureBase<TModel> where TModel : PersistenceModel, new()

    protected SessionSource SessionSource { get; set; }

    protected ISession Session { get; private set; }

    [SetUp]

    public void SetupContext()

        var cfg = new SQLiteConfiguration()

                        .InMemory()

                        .ShowSql();

        SessionSource = new SessionSource(cfg.ToProperties(), new TModel());

        Session = SessionSource.CreateSession();

        SessionSource.BuildSchema(Session);

        Context();

        Because();

        Session.Flush();

        Session.Clear();

    [TearDown]

    public void TearDown()

        TearDownContext();

        Session.Close();

        Session.Dispose();

    protected virtual void Context()

    protected virtual void Because()

    protected virtual void TearDownContext()

First of all my base fixture has a generic parameter TModel. TModel represents the persistence model used during the tests. The persistence model must inherit from the PersistenceModel (provided by Fluent NHibernate) and it must have a default constructor.

In the SetupContext method (which is executed before each test)

I define my configuration I want to use. Most of the time I use the SQLite database in in-memory mode for my database related tests. Fluent NHibernate provides me such a configuration object. For debugging purposes I declare that I want to see the SQL statements generated by NHibernate (ShowSql).
Second I create a session source and pass the above configuration as well as an instance of the model used to the constructor of the session source.
Then I create a new session object. Note that since I am using SQLite in in-memory mode I have to use the same session object during the whole test (including setup and tear down) since the database schema (and the data) is destroyed when the session is closed.
I now use the Session object created above to generate the database schema. The schema is generated from the information provided by the model (which consists of all mappings)
Now I call the virtual Context and Because methods. The reason is that I want my unit test to be more BDD like
Finally I flush all pending operations from the session to the database and then clear the session.

The persistence model

The persistence model I am using is very straight forward. I just include all class mappings that are in the same assembly as the PersonMap.

public class TestModel : PersistenceModel

    public TestModel()

        addMappingsFromAssembly(typeof(PersonMap).Assembly);

I could also explicitly add mappings if I want so

public class TestModel : PersistenceModel

    public TestModel()

        addMapping(new PersonMap());

        addMapping(new TaskMap());

The test

Writing a test for the mapping is really straight forward with the aid of the PersistenceSpecification class provided by Fluent NH.

[Test]

public void can_add_person_without_tasks()

    new PersistenceSpecification<Person>(Session)

        .CheckProperty(x => x.Firstname, "Gabriel")

        .CheckProperty(x => x.Lastname, "Schenker")

        .VerifyTheMappings();

or a test which also tries to add tasks

[Test]

public void can_add_person_with_tasks()

    var tasks = new[]

                        new Task {TaskName = "Task 1", DueDate = DateTime.Today.AddDays(5)},

                        new Task {TaskName = "Task 2", DueDate = DateTime.Today.AddDays(6)},

                        new Task {TaskName = "Task 3", DueDate = DateTime.Today.AddDays(3)},

};

    new PersistenceSpecification<Person>(Session)

        .CheckProperty(x => x.Firstname, "Gabriel")

        .CheckProperty(x => x.Lastname, "Schenker")

        .CheckList(x=>x.Tasks, tasks)

        .VerifyTheMappings();

Do I need to tell that the tests pass successfully? It's really that easy... I have not needed a single line of XML so far. And no "magic strings" are involved. For me it's really a joy to work like this.

And now finally we get LINQ into the play

The context

In LINQ the notion of a context is very important. It represent kind of a facade to the database. LINQ to NHibernate provides us a base class from which we can derive when we define our own context. In our simplified model we have only 2 entities and thus our context needs just two members to have access via LINQ to either the persons or tasks.

public class SampleContext : NHibernateContext

    public SampleContext(ISession session)

        : base(session)

{ }

    public IOrderedQueryable<Person> Persons

        get { return Session.Linq<Person>(); }

    public IOrderedQueryable<Task> Tasks

        get { return Session.Linq<Task>(); }

Testing

Now I want to implement a first test to check whether LINQ to NHibernate does indeed work as expected. First I have to setup a context where I have some person object with tasks in the database

public class a_repository_with_persons_having_tasks : Person_Fixture

    protected Person[] persons;

    private IList<Task> tasks1, tasks2, tasks3;

    protected override void Context()

        base.Context();

        tasks1 = new[]

                         new Task {TaskName = "Task 1.1", DueDate = DateTime.Today.AddDays(5)},

                         new Task {TaskName = "Task 1.2", DueDate = DateTime.Today.AddDays(6)},

                         new Task {TaskName = "Task 1.3", DueDate = DateTime.Today.AddDays(3)},

};

        tasks2 = new[]

                         new Task {TaskName = "Task 2.1", DueDate = DateTime.Today.AddDays(5)},

                         new Task {TaskName = "Task 2.2", DueDate = DateTime.Today.AddDays(6)},

                         new Task {TaskName = "Task 2.3", DueDate = DateTime.Today.AddDays(3)},

};

        tasks3 = new[]

                         new Task {TaskName = "Task 3.1", DueDate = DateTime.Today.AddDays(5)},

                         new Task {TaskName = "Task 3.2", DueDate = DateTime.Today.AddDays(6)},

                         new Task {TaskName = "Task 3.3", DueDate = DateTime.Today.AddDays(2)},

};

        persons = new[]

                          new Person {Firstname = "Gabriel", Lastname = "Schenker", Tasks = tasks1},

                          new Person {Firstname = "John", Lastname = "Doe", Tasks = tasks2},

                          new Person {Firstname = "Ann", Lastname = "Moe", Tasks = tasks3},

};

        foreach (var person in persons)

            Session.Save(person);

Now I can write a test for the case where I want to retrieve all persons from the database

[TestFixture]

public class when_querying_all_persons : a_repository_with_persons_having_tasks

    private IEnumerable<Person> list;

    protected override void Because()

        list = from p in db.Persons

               select p;

    [Test]

    public void should_return_all_persons()

        list.Count().ShouldEqual(persons.Length);

The query generated by the above test is

SELECT  this_.Id as Id0_0_,

        this_.Lastname as Lastname0_0_,

        this_.Firstname as Firstname0_0_

FROM [Person] this_

That's exactly what we were expecting!

Using Where to get a filtered list

Now let's do some more interesting stuff. I want to have a filtered list of persons

[TestFixture]

public class when_retrieving_filtered_list_of_persons : a_repository_with_persons_having_tasks

    [Test]

    public void can_filter_by_LastName()

        var list = db.Persons.Where(x=>x.Lastname=="Doe");

        list.Count().ShouldEqual(1);

    [Test]

    public void can_filter_by_task()

        var list = from p in db.Persons

                   from t in p.Tasks

                   where t.DueDate == DateTime.Today.AddDays(3)

                   select p;

        list.Count().ShouldEqual(2);

In the first test I use the Where extension method defined by LINQ to filter my collection of persons. The extension methods defined by LINQ are also called query operators. The select statement generated by Linq2NH is

SELECT count(*) as y0_

FROM [Person] this_

WHERE this_.Lastname = @p0;

@p0 = 'Doe'

In the second test I use the new language extension introduced for C# (also called a query expression) to get a filtered set of persons. This time we get the following select statement sent to the database

SELECT          count(*) as y0_

FROM            [Person] this_

left outer join [Task] t1_ on this_.Id=t1_.Person_id

WHERE t1_.DueDate = @p0;

@p0 = '29.11.2008 00:00:00'

Obviously also joins between tables work as expected.

Getting ordered lists

Often we need an ordered list of items, in this case persons ordered by their last name.

[Test]

public void can_order_by_LastName()

    var list = db.Persons.OrderBy(x => x.Lastname);

    list.First().Lastname.ShouldEqual("Doe");

The query generated is

SELECT  this_.Id as Id0_0_,

        this_.Lastname as Lastname0_0_,

        this_.Firstname as Firstname0_0_

FROM [Person] this_

ORDER BY this_.Lastname asc

Code

The code accompanying this post can be found here.

Summary

It is straight forward to use LINQ to NHibernate. Although the Linq2NH provider is not fully implemented it is more than sufficient for most scenarios we encounter in typical projects. And if ever we encounter a query that cannot be executed through the Linq2NH provider we can still implement the query by using HQL instead.

Enjoy

Lazy loading BLOBS and the like in NHibernate

NHibernate's Answers — Mon, 17 Nov 2008 12:23:16 GMT

[Updated, 2008-11-20 --> see end of post]

One of the questions that is asked again and again in the NHibernate user mailing list is the question about whether NHibernate supports lazy-loading of properties. The answer is NO - at least for the time being. Why is this question reasonable? Well, often we have entities in our domain that contain fields with large amount of data. Some samples are

a large binary object (BLOB, e.g. an image, a Word document, a PDF, etc.),
a large text object (CLOB, or nvarchar(max) )
a cluster of rarely used extra fields

The problem is that we do not always need all this information when loading an entity. Thus we can massively improve the performance of our queries if those fields would only be loaded on demand.

The Model

Let's have a look at the following simplified domain model.

Here the person entity has an associated photo. The photo has been extracted from the person entity since NHibernate does not support lazy load of specific properties of an entity (as mentioned above) and thus each time we load a person entity we would also load its photo which might be huge (e.g. several MB).

The code for the person entity is simple

public class Person

    public virtual Guid Id { get; private set; }

    public virtual string LastName { get; private set; }

    public virtual string FirstName { get; private set; }

    public virtual PersonPhoto Photo { get; private set; }

    // to satisfy NHibernate only!

    protected Person() { }

    public Person(string lastName, string firstName, PersonPhoto personPhoto)

        LastName = lastName;

        FirstName = firstName;

        AssignPhoto(personPhoto);

    public virtual void AssignPhoto(PersonPhoto photo)

        Photo = photo;

        photo.Owner = this;

please note that I have defined a method to assign a photo to the person. This method takes care of the fact that the relation between the person and the photo entity is bi-directional (via the assignment photo.Owner = this). I have omitted any validation code for brevity.

Let's also have a look at the implementation of the PersonPhoto class which I kept even simpler

public class PersonPhoto

    public virtual Guid Id { get; set; }

    public virtual Person Owner { get; set; }

    public virtual byte[] Image { get; set; }

Let's now define the mapping for my simple model.

Mapping with XML

The question is now: how can I map this model to achieve the desired result that is

whenever I load a person its photo is not automatically loaded but only on request (lazy load)
treating the person photo like an associated entity of the person entity, that is the photo is created, updated and deleted together with its parent - the person.

It is not possible in NHibernate to define a (bi-directional) one-to-one relation between Person and PersonPhoto and requesting at the same time that the PersonPhoto is lazy loaded.

But a possible solution to declare the relation between Person and PersonPhoto as many-to-one and between PersonPhoto and Photo as one-to-one.

<?xml version="1.0" encoding="utf-8" ?>

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

                   assembly="Blobs"

                   namespace="Blobs">

  <class name="Person">

    <id name="Id">

      <generator class="guid"/>

    </id>

    <property name="LastName"/>

    <property name="FirstName"/>

    <many-to-one name="Photo" class="PersonPhoto" unique="true"

                 column="PersonPhotoId" cascade="all-delete-orphan"/>

  </class>

  <class name="PersonPhoto">

    <id name="Id">

      <generator class="guid"/>

    </id>

    <property name="Image" type="BinaryBlob"/>

    <one-to-one name="Owner" property-ref="Photo" constrained="true"/>

  </class>

</hibernate-mapping>

It is important to note that the many-to-one relation defined in the Person mapping is declared as unique to avoid that a single photo is assigned to more than one person. Also I define that each insert, update and delete action applied to a person entity should be cascaded to the associated PersonPhoto entity.

Unit testing the XML mapping

Let's now write some unit tests that verify that my requirements are indeed satisfied.

[Updated]

First I want to analyze what database schema is created. Remember: whenever I have the possibility to start a so called green field project I always start by defining the domain and then let the database auto-generated from the domain (that is: the database is only an implementation detail). Things might be different if you have to use a pre-existing database though...

So my unit test to verify that the schema can indeed be created is

[TestFixture]

public class when_creating_the_schema : Person_Fixture

    protected override void Context()

        base.Context();

        new SchemaExport(Configuration).Execute(true, false, false, false, Session.Connection, null);

    [Test]

    public void smoke_test()

        true.ShouldBeTrue();

In the last line of the Context method I use the SchemaExport class of NHibernate to generate the database schema from the model and the mapping information. The first (and only) test I write is a so called smoke test, that is it's a dummy test which should run just to test that setting up the context doesn't throw an exception. And indeed the test succeeds and the following output is produced

The script is generated for the SQLite database I use. For a different type of database server the script would look slightly different. The two tables created are

create table Person (

  Id UNIQUEIDENTIFIER not null,

  LastName TEXT,

  FirstName TEXT,

  PersonPhotoId UNIQUEIDENTIFIER unique,

  primary key (Id)

create table PersonPhoto (

  Id UNIQUEIDENTIFIER not null,

  Image BLOB,

  primary key (Id)

Second I want to test whether I can create a new person object having a photo and save this aggregate to the database.

[TestFixture]

public class when_adding_a_new_person_with_a_photo : Person_Fixture

    private PersonPhoto photo;

    private Person person;

    protected override void Context()

        base.Context();

        photo = new PersonPhoto {Image = Encoding.Default.GetBytes("This is a placeholder for a photo...")};

        person = new Person("Schenker", "Gabriel", photo);

        Session.Save(person);

        // clean up

        Session.Flush();

        Session.Clear();

In the above code I have setup the context, that is - I want to add a new person with photo to the database - (please have a look at the source code regarding the base class Person_Fixture which I use)

The first test I write is again smoke test, which should run just to test that setting up the context doesn't throw an exception.

// Smoke test

[Test]

public void should_execute_without_an_error()

    true.ShouldBeTrue();

And indeed, if you run this test it is green. This tells me that the method Context is running without causing an exception.

Remarks: All the ShouldXXX methods you'll see in the presented code fragments are extension methods I defined and use for better readability of the code. You can find them here.

The second test method checks whether there exists indeed a person record in the database

[Test]

public void person_should_exist_in_the_database()

    var fromDb = Session.Get<Person>(person.Id);

    fromDb.ShouldNotBeNull();

    fromDb.ShouldNotBeTheSameAs(person);

    fromDb.LastName.ShouldEqual(person.LastName);

    fromDb.FirstName.ShouldEqual(person.FirstName);

In the above code I first check whether a non null object is loaded from db and then whether it is a different instance (that is it has not been just loaded from the first level cache of NHibernate --> please see also this post) which means it has really been loaded from the database. Finally I check some of the properties for equality. As you might have expected: this test is green when run.

Now I want to also check whether the photo has really been stored in the database or not. The following test should confirm that

[Test]

public void person_photo_should_exist_in_the_database()

    var fromDb = Session.Get<Person>(person.Id);

    fromDb.Photo.ShouldNotBeNull();

    fromDb.Photo.ShouldNotBeTheSameAs(person.Photo);

    fromDb.Photo.Image.ShouldEqual(person.Photo.Image);

Well, green again when run - so no problem!

One important thing to check is that the very same photo cannot assigned to two different person instances. Each photo is uniquely assigned to a certain person. The following test verifies that behavior.

[Test]

public void adding_another_person_with_same_photo_should_not_be_possible()

    var otherPerson = new Person("Doe", "John", photo);

    Session.Save(otherPerson);

try

        Session.Flush();

        Assert.Fail("Expected exception!");

    catch(HibernateException)

        Session.Clear();

this code needs some further explanation. As you probably can see I expect that NHibernate throws an exception when trying to add a new person having the same photo as an already existing person. The exception is not thrown when calling the save method of the session but only when the session is flushed (that is: the insert command is executed on the database). I clear the session in the catch block since otherwise the exception would be raised again by my test tear-down method (in the base fixture class) which also flushes and disposes the session object.

The above test also passes and thus we are left with only one additional test. Does the person photo indeed lazy load? Let's write a test which verifies this

[TestFixture]

public class when_loading_an_existing_person_from_database : Person_Fixture

    private PersonPhoto photo;

    private Person person;

    protected override void Context()

        base.Context();

        photo = new PersonPhoto { Image = Encoding.Default.GetBytes("This is a placeholder for a photo...") };

        person = new Person("Schenker", "Gabriel", photo);

        Session.Save(person);

        // clean up

        Session.Flush();

        Session.Clear();

    [Test]

    public void Person_photo_should_be_lazy_loaded()

        var fromDb = Session.Load<Person>(person.Id);

        NHibernateUtil.IsInitialized(fromDb.Photo).ShouldBeFalse();

        var image = fromDb.Photo.Image;

        NHibernateUtil.IsInitialized(fromDb.Photo.Image).ShouldBeTrue();

Again I first setup the context for the test, that is I add a person with a photo to the database. Then in the test method I load the previously save person from database and with the aid of a utility class of NHibernate I check whether the property Photo of the person entity is un-initialized (i.e. the entity behind the property is not loaded). Then I access the property and finally I use the utility class again to test whether now the photo has been (lazy) loaded.

Wow - the test passes! We have found a mapping which satisfies all our needs!

Mapping with Fluent NHibernate

As described in earlier posts (part 1, part 2, part 3 and part 4) we have the possibility to use Fluent NHibernate to map our entities. Mapping this way has many advantages (I already discussed in the posts just mentioned). Let's have a look at the mapping needed for the Person entity

public class PersonMapper : ClassMap<Person>

    public PersonMapper()

        LazyLoad();

        Id(x => x.Id);

        Map(x => x.FirstName);

        Map(x => x.LastName);

        References(x => x.Photo)

            .FetchType.Select()

            .Cascade.All()

            .TheColumnNameIs("PersonPhotoId")

            .WithUniqueConstraint();

I define a mapper class which inherits form the generic ClassMap<T> base class provided by the Fluent NHibernate framework. In the constructor of this class I define the mapping. The first line defines that I want my person entity to be lazy loaded (by default in Fluent NHibernate all entities are NOT lazy loaded).

The many-to-one relation between person and person photo is mapped with the aid of the References method.

The PersonPhoto entity is mapped as follows

public class PersonPhotoMapper : ClassMap<PersonPhoto>

    public PersonPhotoMapper()

        LazyLoad();

        Id(x => x.Id);

        Map(x => x.Image);

        HasOne(x => x.Owner)

            .PropertyRef(x=>x.Photo)

            .Constrained();

Here the part that interests us most (the reverse relation from photo to person) is mapped with the aid of the HasOne method.

Unit testing the Fluent NHibernate mapping

There is not much to say about this. The unit test are nearly the same with only one difference. I use a different base class from which I derive all my test classes. The definition of the base class used can be found here.

Code

You can find the accompanying this post here.

Summary

I have shown you a way how you can structure your domain model and map your entities to be able to lazy load "extra" information of a given entity. I have explained how to map the domain by using standard XML mapping files as well as by using the Fluent NHibernate framework. By applying this technique you can massively improve the performance of queries and reduce the bandwidth needed to transfer data from the database to the consuming client.

[Update] Uni-directional link between Person and PersonPhoto

In a comment I was asked why I implemented the relation between the person and the person photo entity as bi-directional and whether it would not be possible to only implement and uni-directional realtion between person and person photo.

The answer is: there is NO special reason for having a bi-directional relation (Eric Evans in his DDD book even suggests to keep the relations uni-directional whenever possible). And yes, it is possible to implement the sample with an uni-directional relation. I'll show the details below (this time I only show the mapping in Fluent NHibernate but the XML mapping is straight forward.

Here is the model with only an uni-directional relation

and the code

public class Person

    public virtual Guid Id { get; private set; }

    public virtual string LastName { get; private set; }

    public virtual string FirstName { get; private set; }

    public virtual PersonPhoto Photo { get; private set; }

    // to satisfy NHibernate only!

    public Person() { }

    public Person(string lastName, string firstName, PersonPhoto personPhoto)

        LastName = lastName;

        FirstName = firstName;

        AssignPhoto(personPhoto);

    public virtual void AssignPhoto(PersonPhoto photo)

        Photo = photo;

public class PersonPhoto

    public virtual Guid Id { get; set; }

    public virtual byte[] Image { get; set; }

Now let me show the mapping for this model (Fluent NHibernate)

public class PersonMapper : ClassMap<Person>

    public PersonMapper()

        LazyLoad();

        Id(x => x.Id);

        Map(x => x.FirstName);

        Map(x => x.LastName);

        References(x => x.Photo)

            .FetchType.Select()

            .Cascade.All()

            .TheColumnNameIs("PersonPhotoId")

            .WithUniqueConstraint();

public class PersonPhotoMapper : ClassMap<PersonPhoto>

    public PersonPhotoMapper()

        LazyLoad();

        Id(x => x.Id);

        Map(x => x.Image);

If I generate the schema from this model I get the very same create table scripts as in the bi-directional sample. And all the other unit tests I have shown above run successfully.

The code has been updated to contain both samples the uni- and the bi-directional relation.

Enjoy

First and Second Level caching in NHibernate

NHibernate's Answers — Sun, 09 Nov 2008 17:57:58 GMT

I'll try to dive deep into the caching of NHibernate in this article. This post has been inspired by the talk given by Oren Eini (aka Ayende) at the Kaizen Conference in Austin TX.

Caching is a topic that is IMHO only superficially described so far especially regarding the second level cache. Most of the time one finds a lot of information about how to configure a specific cache provider for usage but the real usage (who and when) is not really described. I hope to be able to provide some of the missing pieces with this post.

The full source code used for this post can be found here.

First Level Cache

When using NHibernate the first level cache is automatically enabled as long as one uses the standard session object. We can avoid to use a cache at all when using the stateless session provided by NHibernate though. The stateless session is especially useful for reporting situations or for batch processing. When NHibernate is loading an entity by its unique id from the database then it is automatically put into the so called identity map. This identity map represents the first level cache.
The life-time of the first level cache is coupled to the current session. As soon as the current session is closed the content of the respective first level cache is cleared. Once an entity is in the first level cache a subsequent operation that wants to load the very same entity inside the current session retrieves this entity from the cache and no roundtrip to the database is needed.
One of the main reasons behind this entity map is to avoid the situation that two different instances in memory can represent the same database record (or entity). The NHibernate session object provides us two ways to retrieve an entity by its unique id from the database. There are subtle but important differences between them.

Let's implement an Account class for our samples

public class Account

    public virtual int Id { get; private set; }

    public virtual string Name { get; private set; }

    public virtual decimal Balance { get; private set; }

    protected Account()

    public Account(string name, decimal balance)

        Name = name;

        Balance = balance;

    public virtual void Credit(decimal amount)

        Balance += amount;

the corresponding XML mapping file is

<?xml version="1.0" encoding="utf-8" ?>

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

                   namespace="Caching"

                   assembly="Caching">

  <class name="Account">

    <id name="Id">

      <generator class="hilo"/>

    </id>

    <property name="Name"/>

    <property name="Balance"/>

  </class>

</hibernate-mapping>

Get an entity from database

With the session.Get(id) method we can retrieve an entity from database. If there is no record found in the database with the given id then null is returned.
On the other hand if a record with the given unique id exists in the database then NHibernate loads this record and instantiates a fully populated entity in memory and immediately puts this entity into the entity map (or first level cache)
Assuming that a specific record has already been loaded from database inside the current session then a subsequent Get(id) operation will return the cached entity to the caller. We can see this in the following output produced by the unit test. There is only ONE select statement produced by NHibernate

The above output was produced by this unit test

[Test]

public void trying_to_get_the_same_account_a_second_time_should_get_the_account_from_1st_level_cache()

    Console.WriteLine("------ now getting entity for the first time");

    var acc1 = Session.Get<Account>(account.Id);

    Console.WriteLine("------ now getting entity for the second time");

    var acc2 = Session.Get<Account>(account.Id);

    acc1.ShouldBeTheSameAs(acc2);

Load an entity from database

When using the session.Load(id) method NHibernate only instantiates a proxy for the given entity. As long as we only access the id of the entity the entity itself is not loaded from the database. Only when we try to access one of the other properties of the entity NHibernate loads the entity from the database. We can see this clearly in the following output produced by the unit test. I have added some comment to the output to make it easier to verify the result.

Here is a unit test

[Test]

public void trying_to_load_a_non_existing_entity()

    var acc1 = Session.Load<Account>(account.Id);

    acc1.ShouldNotBeNull();

    Console.WriteLine("------ now accessing the id of the entity");

    Console.WriteLine("The id is equal to {0}", acc1.Id);

    acc1.Id.ShouldEqual(account.Id);

    Console.WriteLine("------ now accessing a property (other than the ID) of the entity");

    Console.WriteLine("The name of the account is: {0}", acc1.Name);

    acc1.Name.ShouldEqual(account.Name);

and the output produced by the above code

Using Load to optimize data access

The behavior mentioned above is especially useful when creating or updating complex entities which have relations to other entities. Assume that the account entity references a customer entity and I want to create a new account for a customer from which I only know its unique id. Then my code might look as follows

var newAccount = new Account("EUR Account 1", 1250m);

newAccount.Customer = Session.Load<Customer>(customerId);

Session.Save(newAccount);

Note that I use the Load method to get the (existing) customer entity. NHibernate will not physically load the customer since in the account table on the database there is only the id of the customer needed (as a foreign key). And as I mentioned above, as long as you only use the id of an entity retrieved with the Load method the corresponding entity is not physically loaded from the database.

Second level cache

The life time of the second level cache is tied to the session factory and not to an individual session. Once an entity is loaded by its unique id and the second level cache is active the entity is available for all other sessions (of the same session factory). Thus once the entity is in the second level cache NHibernate won't load the entity from the database until it is removed from the cache.
To enable the second level cache we have to adjust our configuration file. We have to define which cache provider we want to use. There exist various implementations of a second level cache. For our sample we use a Hashtable based cache which is included in the core NHibernate assembly. Please note that you should never use this cache provider for production code but only for testing. Please refer to the chapter "Second Level Cache implementations" below to decide which implementation fits best for your needs. You won't have to change your code if you change the cache provider though.

We have to add the the following line to the configuration file

<property name="cache.provider_class">NHibernate.Cache.HashtableCacheProvider</property>

this will instruct NHibernate to use the previously mentioned Hashtable based cache provider as a provider for the second level cache.
Now let's have a look at the following unit test.

[Test]

public void trying_to_load_an_existing_item_twice_in_different_sessions_should_use_2nd_level_cache()

    using(var session = SessionFactory.OpenSession())

        var acc = session.Get<Account>(account.Id);

        acc.ShouldNotBeNull();

    using(var session = SessionFactory.OpenSession())

        var acc = session.Get<Account>(account.Id);

        acc.ShouldNotBeNull();

In the above test we open a first session and load an existing entity from the database. Then we open a second session and try to load the very same entity from the database again. Without a second level cache we would expect that NHibernate loads the entity two times from the database since we are using 2 different sessions and thus the first level cache can not be used to avoid a roundtrip to the database. So let's have a look at the result produced.

Wait a moment - we clearly see two select statements instead of only one. What did we do wrong? This is not an error, no but it's a feature. NHibernate does not enable the second level cache by default, since it would have too many undesired implications. One has to explicitly enable the second level cache. If we add the following statement to the configuration file

we activate the second level cache. But that is still not enough. We have to also enable our entity to be cached in the second level cache.
This can be done by adding the following statement to the entity's mapping file

If we now run the unit test again we obtain the expected result. The entity is loaded only once from the database. The second time it is loaded from the second level cache.
Now if we try to update an entity which is already in the second level cache then this entity should also be automatically updated in the second level cache. The following unit test should prove this behavior.

[Test]

public void when_updating_the_entity_then_2nd_level_cache_should_also_be_updated()

    using(var session = SessionFactory.OpenSession())

    using (var tx = session.BeginTransaction())

        var acc = session.Get<Account>(account.Id);

        acc.Credit(200m);

        tx.Commit();

    using(var session = SessionFactory.OpenSession())

        var acc = session.Get<Account>(account.Id);

        acc.Balance.ShouldEqual(1200m);

and indeed it does as we can see in the test output. Again the entity is loaded from the cache the second time it is requested although it was updated (no select statement after the update statement). The last line in the test code verifies that the entity was indeed updated.

Second Level Cache Providers

All second level cache providers are part of the NHibernate contribution. The following list gives as short description of each provider.

Velocity: uses Microsoft Velocity which is a highly scalable in-memory application cache for all kinds of data.
Prevalence: uses Bamboo.Prevalence as the cache provider. Bamboo.Prevalence is a .NET implementation of the object prevalence concept brought to life by Klaus Wuestefeld in Prevayler. Bamboo.Prevalence provides transparent object persistence to deterministic systems targeting the CLR. It offers persistent caching for smart client applications.
SysCache: Uses System.Web.Caching.Cache as the cache provider. This means that you can rely on ASP.NET caching feature to understand how it works.
SysCache2: Similar to NHibernate.Caches.SysCache, uses ASP.NET cache. This provider also supports SQL dependency-based expiration, meaning that it is possible to configure certain cache regions to automatically expire when the relevant data in the database changes.
MemCache: uses memcached; memcached is a high-performance, distributed memory object caching system, generic in nature, but intended for use in speeding up dynamic web applications by alleviating database load. Basically a distributed hash table.
SharedCache: high-performance, distributed and replicated memory object caching system. See here and here for more info

Saving a transient entity

Lately the following question came up in the NHibernate user list. "When I create a transient object and then save it to my session and
commit to my database, should it be added to my second level cache as well?" The answer is of course YES. Let's write a unit test

[TestFixture]

public class when_saving_a_transient_account : FixtureBase

    private Account newAccount;

    protected override void Context()

        base.Context();

        using (var session = SessionFactory.OpenSession())

        using (var tx = session.BeginTransaction())

            newAccount = new Account("CHF Account", 5500m);

            session.Save(newAccount);

            tx.Commit();

    [Test]

    public void account_should_be_in_second_level_cache()

        using (var session = SessionFactory.OpenSession())

            Console.WriteLine("--> Now loading account");

            var acc = session.Get<Account>(newAccount.Id);

            acc.ShouldNotBeNull();

            acc.Name.ShouldEqual(newAccount.Name);

In the method Context I create and save a new account entity. In the test method I open a new session and try to load the previously created entity from database. I now expect that NHibernate should take the entity out of the second level cache. And indeed it does. This is the resulting output

as we can see, no select statement is sent to the database when the entity is loaded from a new session after it has been created and saved beforehand.

Inside the second level cache

An important point is that the second-level cache does not cache instances of the object type being cached; instead it caches the individual values of the properties of that object. This provides two benefits. One, NHibernate doesn't have to worry that your client code will manipulate the objects in a way that will disrupt the cache. Two, the relationships and associations do not become stale, and are easy to keep up-to-date because they are simply identifiers. The cache is not a tree of objects but rather a map of arrays.

If you are interested in some more details about the inner workings of the second level cache then the following text (taken from Ayende and only slightly edited by me) will be of interest to you:

NHibernate is design as an enterprise OR/M product, and as such, it has very good support for running in web farms scenarios. This support include running along side with distributed caches, including immediate farm wide updates. NHibernate goes to great lengths to ensure cache consistency in these scenarios...

The way it works, NHibernate keeps three caches.

The entities cache - the entity data is disassembled and then put in the cache, ready to be assembled to entities again.

The queries cache - the identifiers of entities returned from queries, but no the data itself (since this is in the entities cache).

The update timestamp cache - the last time a table was written to.

The last cache is very important, since it ensures that the cache will not serve stale results.

Now, when we come to actually using the cache, we have the following semantics.

Each session is associated with a timestamp on creation.

Every time we put query results in the cache, the timestamp of the executing session is recorded.

The timestamp cache is updated whenever a table is written to, but in a tricky sort of way:

When we perform the actual writing, we write a value that is somewhere in the future to the cache. So all queries that hit the cache now will not find it, and then hit the DB to get the new data. Since we are in the middle of transaction, they would wait until we finish the transaction. If we are using low isolation level, and another thread / machine attempts to put the old results back in the cache, it wouldn't hold, because the update timestamp is into the future.

When we perform the commit on the transaction, we update the timestamp cache with the current value.

Now, let us think about the meaning of this, shall we?

If a session has perform an update to a table, committed the transaction and then executed a cache query, it is not valid for the cache. That is because the timestamp written to the update cache is the transaction commit timestamp, while the query timestamp is the session's timestamp, which obviously comes earlier.

The update timestamp cache is not updated until you commit the transaction! This is to ensure that you will not read "uncommitted values" from the cache.

Please note that if you open a session with your own connection, it will not be able to put anything in the cache (all its cached queries will have an invalid timestamp!)

In general, those are not things that you need to concern yourself with, but I spent some time today just trying to get tests for the second level caching working, and it took me time to realize that in the tests I didn't used transactions and I used the same session for querying as for performing the updates.

Collections and the second level cache

Let's assume the following scenario: we have a blog which can have many posts. See the diagram below.

The corresponding code to define the entities is as follows

public class Blog

    public virtual int Id { get; set; }

    public virtual string Author { get; set; }

    public virtual string Name { get; set; }

    public virtual IList<Post> Posts { get; set; }

    public Blog()

        Posts = new List<Post>();

public class Post

    public virtual int Id { get; private set; }

    public virtual string Title { get; set; }

    public virtual string Body { get; set; }

and we can define the mapping of the blog and the post entity like this

<?xml version="1.0" encoding="utf-8" ?>

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

                   namespace="Caching"

                   assembly="Caching">

  <class name="Blog">

    <cache usage="read-write"/>

    <id name="Id">

      <generator class="hilo"/>

    </id>

    <property name="Author"/>

    <property name="Name"/>

    <bag name="Posts" cascade="all" lazy="true">

      <cache usage="read-write"/>

      <key column="BlogId"/>

      <one-to-many class="Post"/>

    </bag>

  </class>

  <class name="Post">

    <cache usage="read-write"/>

    <id name="Id">

      <generator class="hilo"/>

    </id>

    <property name="Title"/>

    <property name="Body"/>

  </class>

</hibernate-mapping>

Note that I have added a <cache> element to the mapping for the Blog entity. This is enough to cache all simple Blog property values (e.g. Id, Name and Author) but not the state of associated entities or collections. Collections require their own <cache> element. In our case I added a <cache> element to the Posts collection (which is mapped as a bag). This cache will be used when enumeration the collection blog.Posts, for example. Please be aware that a collection cache only holds the identifiers of the associated post instances. That is, if we have a blog with three posts having id's 1,2 and 3 respectively then the second level cache will contain the values of simple properties of the blog and in addition an array with the ids {1,2,3}. If we require the post instances themselves to be cached, then we must enable caching of the Post class by adding a <cache> element to it's mapping.

Let me resume: by adding a <cache> element to the Blog, the Posts collection and the Post itself I have declared that I want NHibernate to cache not only my blog entities but also the associated Post collection in full detail.

Attention: dragons ahead

A common error (It happened to me as well!) is to forget to commit or omit a transaction when adding or changing an entity/aggregate to the database. If we now access the entity/aggregate from another session then the 2nd level cache will not be prepared to provide us the cached instances and NHibernate makes an (unexpected round trip to the database). The reason why this is the case is described in the chapter "Inside the second level cache" above.

What does this mean? Let's have a look at the code I use to setup the context for our unit tests regarding the Blog-->Posts problem.

blog = new Blog{ Author = "Gabriel", Name = "Keep on running"};

blog.Posts.Add(new Post{Title = "First post", Body = "Some text"});

blog.Posts.Add(new Post { Title = "Second post", Body = "Some other text" });

blog.Posts.Add(new Post { Title = "Third post", Body = "Third post text" });

using (var session = SessionFactory.OpenSession())

using(var tx = session.BeginTransaction())

    session.Save(blog);

    tx.Commit();        // important otherwise caching does NOT work!

In the above code I create a new blog having three assigned posts. The blog instance is then saved to the database inside a transaction. If I would omit the transaction or if I would forget to commit the transaction then the above samples would not work as expected and the 2nd level cache would not be used as desired.

Caching queries in the second level cache

We cannot only cache entities loaded by their respective unique id but also any query. For this we have to define the query as cacheable and set the desired cache mode. Let's have a look at a typical sample

[Test]

public void trying_to_cache_a_query()

    using (var session = SessionFactory.OpenSession())

        Console.WriteLine("---> using query first time");

        var query = session

            .CreateQuery("from Blog b where b.Author = :author")

            .SetString("author", "Gabriel")

            .SetCacheable(true);

        var list = query.List<Blog>();

    using (var session = SessionFactory.OpenSession())

        Console.WriteLine("---> using query second time");

        var query2 = session

            .CreateQuery("from Blog b where b.Author = :author")

            .SetString("author", "Gabriel")

            .SetCacheable(true);

        var list2 = query2.List<Blog>();

In the above sample I use the same query from different sessions. Please not that I have set cacheable to true for the query. In this case the query will be cached in the second level cache the first time it is executed. Any subsequent calls using the very same query will not hit the database. It is important to note however that if I change the value of the parameter(s) in the query then the query is reloaded again from the database. So it is the query and the set of parameter values that define the key under which the query is stored in the 2nd level cache.

The result of the above test looks as follows

Of course I can also use named queries and cache them. A named query is defined inside a mapping file, e.g.

<query cacheable="true" cache-mode="normal" name="query1">

  <![CDATA[from Blog b where b.Name like :name]]>

  <query-param name="name" type="String"/>

</query>

The above query is called "query1" and has a single parameter called "name". The cache mode for this query is set to "normal". I can use such a query as follows

[Test]

public void trying_named_query()

    using (var session = SessionFactory.OpenSession())

        Console.WriteLine("---> using named query first time");

        var list = session.GetNamedQuery("query1")

            .SetString("name", "Keep%")

            .List<Blog>();

    using (var session = SessionFactory.OpenSession())

        Console.WriteLine("---> using named query second time");

        var list2 = session.GetNamedQuery("query1")

            .SetString("name", "Keep%")

            .List<Blog>();

The session object has a method GetNamedQuery to retrieve the query. The output produced by the above test is then

If the content of the table on which the cached query is based is changed then the query is evicted from the second level cache and the next time the query is executed the query must be reloaded.

Cache Regions

If we don't use cache regions the second level cache can only be cleared as a whole. If you need to clear only part of the second level cache then use regions. Regions are distinguished by their name. One can put any number of different queries into a named cache region. The command to clear a cache region is as follows
SessionFactory.EvictQueries("My Region");
where SessionFactory is the session factory instance currently used and "My Region" is the name of the cache region.

Source Code

The full source code used for this post can be found here.

Summary

NHibernate provides two types of caches. The first level cache and the second level cache. The first level cache is also called the identity map and is used not only to reduce the number of round trips to the database to improve the speed of an application but also to guarantee that there do not exist two distinct instances of an object having the very same id. NHibernate provides us two methods to load an entity by its unique id from the database. The Get method returns null if an entity with the given id does not exist or returns the fully loaded entity to the caller. The Load method on the other hand returns a proxy to the caller and only loads the entity from the database if another property than the identity is accessed. One can also call this a deferred load.

The second level cache is not used by default and should be used with caution. It can provide a huge scalability gain if used wisely but also reduce the performance of the overall system and introduce unnecessary complexity if used wrong.

The second level cache is related to the session factory, that is all session instances of a given session factory use the same 2nd level cache. That's differs from the behavior of the 1st level cache which is related to an individual session instance. One can cache individual entities or whole aggregates in the 2nd level cache. But one can also cache (complex and/or time consuming) queries in the 2nd level cache. The 2nd level cache can be fragmented into regions for a more fine grained control.

Enjoy.

The Repository Pattern

NHibernate's Answers — Wed, 08 Oct 2008 13:42:03 GMT

Introduction

When accessing data from a data source we have several well documented possibilities. Martin Fowler e.g. describes several of them in his PoEAA book.

Table data gateway
Row data gateway
Active record
Data mapper

When applying DDD (domain driven design) we often use the so called Repository Pattern to access the data needed by the domain model.

What is a Repository

Martin Fowler writes:

"A Repository mediates between the domain and data mapping layers, acting like an in-memory domain object collection. Client objects construct query specifications declaratively and submit them to Repository for satisfaction. Objects can be added to and removed from the Repository, as they can from a simple collection of objects, and the mapping code encapsulated by the Repository will carry out the appropriate operations behind the scenes. Conceptually, a Repository encapsulates the set of objects persisted in a data store and the operations performed over them, providing a more object-oriented view of the persistence layer. Repository also supports the objective of achieving a clean separation and one-way dependency between the domain and data mapping layers."

Implementation

In DDD we have the notion of aggregates. An aggregate is "A cluster of associated objects that are treated as a unit for the purpose of data changes. External references are restricted to one member of the Aggregate, designated as the root. A set of consistency rules applies within the Aggregate's boundaries.".

Usually one defines a repository per aggregate in the domain. That is: we don't have a repository per entity! If we have a look at a simple order entry system the entity Order might be the root of a Order aggregate. Thus we will have an Order Repository.

The interface (or contract) of the repository is considered as a part of the domain model where as the implementation of the repository is infrastructure specific and thus does NOT belong to the domain model.

When dealing with aggregates most of the time we need exactly 3 persistence related operations

get an aggregate by it's id (primary key)
add a new aggregate to the repository
remove an aggregate from the repository

Depending on the context there might be other persistence related operations that are needed but the most common and often used ones are the three mentioned above. This leads us to the following minimal contract (interface) with the repository

public interface IOrderRepository

    Order GetById(int id);

    void Add(Order order);

    void Remove(Order order);

In the above sample we assume that the primary key of the Order is a surrogate key and is of type int.

Now let's assume that we have identified a second aggregate in our domain model, the Product aggregate. Then we can immediately deduce the appropriate repository interface from the interface to the order repository. We have

public interface IProductRepository

    Product GetById(int id);

    void Add(Product product);

    void Remove(Product product);

Now this looks very similar to the first interface and we can generalize the interface by using a generic parameter. We then have

public interface IRepository<T>

    T GetById(int id);

    void Add(T entity);

    void Remove(T entity);

Now the interfaces to the product and the order repository will just be

public interface IOrderRepository : IRepository<Order> { }

public interface IProductRepository : IRepository<Product> { }

A fake repository

For testing purposes we can implement a fake repository for the product aggregate. In this case it will be a dictionary with some predefined products. The key to each product will be its primary key. In our simple sample the Product aggregate consists only of the Product entity

public class Product

    public virtual int Id { get; set; }

    public virtual string Name { get; set; }

    public virtual int ReorderLevel { get; set; }

    public virtual bool Discontinued { get; set; }

This is a very simple entity but it is sufficient for our purposes. Now let's have a look at the implementation of the faked repository

public class ProductRepositoryFake : IProductRepository

    private readonly Dictionary<int, Product> dictionary;

    public ProductRepositoryFake()

        dictionary = new Dictionary<int, Product>();

        dictionary.Add(1, new Product {Id = 1, Name = "Product 1", ReorderLevel = 10, Discontinued = false});

        dictionary.Add(2, new Product {Id = 2, Name = "Product 2", ReorderLevel = 15, Discontinued = false});

        dictionary.Add(3, new Product {Id = 3, Name = "Product 3", ReorderLevel = 10, Discontinued = false});

        dictionary.Add(4, new Product {Id = 4, Name = "Product 4", ReorderLevel = 12, Discontinued = false});

        dictionary.Add(5, new Product {Id = 5, Name = "Product 5", ReorderLevel = 20, Discontinued = true});

    public Product GetById(int id)

        return dictionary[id];

    public void Add(Product product)

        dictionary.Add(product.Id, product);

    public void Remove(Product product)

        dictionary.Remove(product.Id);

In the constructor I instantiate a dictionary which takes as key an int (the type of the primary key in our case) and as value a Product instance. Then I define several sample Product instances which I fill into the dictionary. The implementation of the three methods GetById, Add and Remove is straight forward and needs no further explanation.

Now let's write some unit tests where we use this implementation of the repository. Note that the special methods (e.g. ShouldEqual, ShouldNotBeNull, ShouldBeThrownBy, etc.) found in the code below are extension methods and can be found in the code accompanying this post. They aid to make the test code more readable than when using the Assert.Equals(...), etc. syntax.

[TestFixture]

public class FakeRepositoryTester

    private IProductRepository repository;

    [SetUp]

    public void SetupContext()

        repository = new ProductRepositoryFake();

    [Test]

    public void can_load_a_product_by_its_id_from_the_repository()

        var product = repository.GetById(2);

        product.ShouldNotBeNull();

        product.Id.ShouldEqual(2);

    [Test]

    public void can_add_a_new_product_to_the_repository()

        repository.Add(new Product {Id = 99, Name = "Product 99", ReorderLevel = 13, Discontinued = false});

        // let's try to load this new product

        var product = repository.GetById(99);

        product.Id.ShouldEqual(99);

        product.Name.ShouldEqual("Product 99");

    [Test]

    public void can_remove_an_existing_product_from_the_repository()

        var product = repository.GetById(1);

        repository.Remove(product);

        typeof (KeyNotFoundException).ShouldBeThrownBy(() => repository.GetById(1));

In the SetupContext method (which will be executed before each test) I define the repository to be an instance of type ProductRepositoryFake. Note that the repository field is declared as type of IProductRepository!

The first test method verifies that the GetById method works as expected. Which indeed it does since when running the test it is green. The second test verifies that the Add method works. First I add a new (non existing) product instance. Then I immediately try to reload this new instance by its id. Then the reloaded instance is tested whether it is the one expected (by comparing some of its properties).

Last but not least the third method tests the Remove method. In the first line I load a product instance from the repository which I know exists. This instance is then removed from the repository. In the third line I test whether the product was really removed from the repository by expecting an exception when trying to get the (previously removed) product from the repository again.

Please note that in the above test code there is only one place where the specific implementation of the repository is of interest. It's the line in the SetupContext method where the repository instance is created. The rest of the code is fully agnostic regarding the specific implementation of the repository. That's an important fact to remember. That means that I can exchange the implementation used in the above code by only changing a single line of code!

An implementation for NHibernate

Now let's try a first implementation for the repository that uses NHibernate. First I need a session provider. I use the following implementation

public class SessionProvider

    private static Configuration configuration;

    private static ISessionFactory sessionFactory;

    public static Configuration Configuration

get

            if(configuration == null)

                configuration = new Configuration();

                configuration.Configure();                              // A

                configuration.AddAssembly(typeof (Product).Assembly);   // B

            return configuration;

    public static ISessionFactory SessionFactory

get

            if (sessionFactory == null)

                sessionFactory = Configuration.BuildSessionFactory();

            return sessionFactory;

    private SessionProvider()

{ }

    public static ISession GetSession()

        return SessionFactory.OpenSession();

In the above sample code the session factory is only built on demand and only once during the life-time of the application (the construction of the session factory is an expensive operation, on the other hand the session factory is thread safe). I make the following assumptions

the existence of a hibernate.cfg.xml for configuration of the connection properties (A)
all mapping files for the domain entities can be found in the assembly where the Product entity is defined (B)

With the aid of this SessionProvider class the implementation of the repository for e.g. the Product entity is really trivial

public class ProductRepositoryNH : IProductRepository

    private static ISession GetSession() { return SessionProvider.GetSession(); }

    public Product GetById(int id)

        using (var session = GetSession())

            return session.Get<Product>(id);

    public void Add(Product product)

        using (var session = GetSession())

            session.Save(product);

    public void Remove(Product product)

        using (var session = GetSession())

            session.Delete(product);

We have a private helper function GetSession which just returns a new session object whenever accessed. The other methods use this helper property for their operations. Note the usage of the using statement to guarantee that the session object is released whenever the database operation is finished.

But the above implementation (although working) has an important flaw and thus can hardly be used in a real application! It's the fact that the repository uses a different session instance for each operation. In a real application often several operations have to be executed inside a single transaction and thus inside a single session (the reason is that a transaction cannot span multiple sessions - at least when not using distributed transactions).

The Unit of Work to the rescue

We can resolve the above dilemma by applying the Unit of Work (UoW) pattern (for a profound discussion of this patterns please refer to this article)! The UoW manages a session for us. I can then refactor my implementation of the product repository as follows

public class ProductRepository : IProductRepository

    private ISession Session { get { return UnitOfWork.CurrentSession; } }

    public Product GetById(int id)

        return Session.Get<Product>(id);

    public void Add(Product product)

        Session.Save(product);

    public void Remove(Product product)

        Session.Delete(product);

Unit Tests

First I implement a base class for unit testing repositories. This base class configures my unit of work and re-creates the schema for each test (I'm using SqLite in in-memory mode as my database)

public class RepositoryFixtureBase<T>

    [TestFixtureSetUp]

    public void TestFixtureSetup()

        UnitOfWork.Configuration.AddAssembly(typeof(T).Assembly);

    [SetUp]

    public void SetupContext()

        UnitOfWork.Start();

        new SchemaExport(UnitOfWork.Configuration)

            .Execute(false, true, false, false, UnitOfWork.CurrentSession.Connection, null);

        Context();

    [TearDown]

    public void TearDownContext()

        UnitOfWork.Current.TransactionalFlush();

        UnitOfWork.Current.Dispose();

    protected virtual void Context() { }

with the aid of the above base class the unit tests for my product repository look like this

[TestFixture]

public class ProductRepository_Tester : RepositoryFixtureBase<Product>

    private IProductRepository repository;

    private Product[] products;

    protected override void Context()

        products = new[]

                           new Product {Id = 1, Name = "Product 1", ReorderLevel = 10, Discontinued = false},

                           new Product {Id = 2, Name = "Product 2", ReorderLevel = 15, Discontinued = false},

                           new Product {Id = 3, Name = "Product 3", ReorderLevel = 10, Discontinued = false},

                           new Product {Id = 4, Name = "Product 4", ReorderLevel = 12, Discontinued = false},

                           new Product {Id = 5, Name = "Product 5", ReorderLevel = 20, Discontinued = true},

};

        foreach (var product in products)

            UnitOfWork.CurrentSession.Save(product);

        UnitOfWork.CurrentSession.Flush();

        UnitOfWork.CurrentSession.Clear();

        repository = new ProductRepository();

    [Test]

    public void can_load_product()

        var p = repository.GetById(2);

        p.ShouldNotBeNull();

        p.Id.ShouldEqual(products[1].Id);

    [Test]

    public void can_add_a_product_to_the_repository()

        repository.Add(new Product { Id = 6, Name = "Product 6", ReorderLevel = 6, Discontinued = false });

        UnitOfWork.CurrentSession.Flush();

        UnitOfWork.CurrentSession.Clear();

        var prod = UnitOfWork.CurrentSession.Get<Product>(6);

        prod.ShouldNotBeNull();

    [Test]

    public void can_remove_product_from_repository()

        repository.Remove(products[2]);

        UnitOfWork.CurrentSession.Flush();

        UnitOfWork.CurrentSession.Clear();

        var prod = UnitOfWork.CurrentSession.Get<Product>(products[2].Id);

        prod.ShouldBeNull();

In the Context method (which is executed before each test) I set up my boundary conditions (=the context). I define an array of products which are then inserted into the database. After inserting these products the current session is flushed and then cleared.

In the first test method can_load_product I try to load a product with the id equal to 2. This product exists in the database since I have applied the boundary conditions. After loading the product I check whether it has really been loaded (ShouldNotBeNull) and that I indeed received the product with the requested id.

In the second test method can_add_a_product_to_the_repository I first try to add a new product instance to the repository. I then flush the current session and clear it. Then I try to re-load the new product from the repository and verify that it is not null. Note that if I wouldn't clear the session after inserting the product, the product would still be in the first level cache and NHibernate would not query the database when I execute the ...Get<Product>(id) method but rather return the object in the cache.

In the third and last test method can_remove_product_from_repository test I try to remove an existing product from the repository. Now when trying to reload the deleted product I should get null.

A generic base repository

When having a look again at our product repository (and possibly at the order repository whose implementation I leave as an exercise for you) we can see some room left for improvement. What if I implement a base repository which in a generic way implements all the common functionality. This leads to the following implementation

public class Repository<T> : IRepository<T>

    public ISession Session { get { return UnitOfWork.CurrentSession; } }

    public T GetById(int id)

        return Session.Get<T>(id);

    public ICollection<T> FindAll()

        return Session.CreateCriteria(typeof(T)).List<T>();

    public void Add(T product)

        Session.Save(product);

    public void Remove(T product)

        Session.Delete(product);

I have taken the code from the ProductRepository class and just replaced any occurrence of Product with the generic parameter T.

Note that this base class can now easily be extended to contain more functionality which is used across repositories for different entities. As an example I have added a FindAll method in the above implementation which just returns a list of all items of the specific type.

Do we still need the ProductRepository and/or OrderRepository classes? Well, it depends. If our application has no other needs regarding the product and order repository then no, we can just use the generic base repository. On the other hand if we want to provide a specific query for the product aggregate (which in turn makes no sense for the order aggregate) we explicitly define a product repository which is a child of the generic base repository.

Let's take this as an example

public interface IProductRepository : IRepository<Product>

    ICollection<Product> FindAllDiscontinuedProducts();

Here I have declared the need for a query that returns the list of discontinued products (note that there is no notion of discontinued orders...). The implementation is straight forward

public class ProductRepository : Repository<Product>, IProductRepository

    public ICollection<Product> FindAllDiscontinuedProducts()

        return Session.CreateCriteria(typeof (Product))

            .Add(Restrictions.Eq("Discontinued", true))

            .List<Product>();

The above method hides the infrastructure related details from my domain and/or application and provides a business friendly interface

Let's have a look how I can test the above method

public void can_load_all_discontinued_products()

    var discontinuedProducts = repository.FindAllDiscontinuedProducts();

    discontinuedProducts.Count.ShouldBeGreaterThan(0);

    discontinuedProducts.ToList().ForEach(p=>p.Discontinued.ShouldBeTrue());

I expect the method to return at least 1 product and each returned product should have its property Discontinued set to true.

Code

The code to this post can be found here.

Summary

I have discussed the repository pattern which is used to retrieve data from external data sources (e.g. databases) in an easy and consistent way. Its main benefit is a clean separation of the domain and the data mapping layer. I have presented an implementation of the pattern for NHibernate. This implementation makes use of the Unit of Work which is another well known pattern which I have introduced in a previous post.

Enjoy

How to map a tree in NHibernate

NHibernate's Answers — Wed, 14 May 2008 22:19:37 GMT

Introduction

Lately there have been many questions regarding how to best map a tree structure in NHibernate. In this post I'll try to show you various techniques how one can deal with a tree structure.

The code for this sample you can get from here.

Domain Model

Let's define a very simple domain model for this sample. We have a single class called Equipment that has a parent of type Equipment and 0 to many children of type Equipment. The tree has a single root node. The root node is specific by the fact that it's property Parent is equal to null. On the other hand a tree has leaf nodes. A leaf node is defined to have no children.

You could as well replace the class Equipment by e.g. a Person class. The principles shown here would not change.

Where is my Aggregate?

A Aggregate in DDD is defined as "A cluster of associated objects that are treated as a unit for the purpose of data changes. External references are restricted to one member of the Aggregate, designated as the root. A set of consistency rules applies within the Aggregate's boundaries."

Depending on our Use Cases or User Stories we can define our Aggregate either as

that is, the aggregate includes the equipment (which is the root) and its children.

Or we could define the Aggregate as follows

here only the equipment object is part of the aggregate (it is at the same time the root of the aggregate).

In the following I choose the former aggregate (equipment and children). This corresponds to the use case where I want to edit an equipment and its children in a single business transaction.

Note: Normally one defines a Repository for each Aggregate in the domain model.

Mapping

Let's have a look at the mapping for the Equipment class.

<?xml version="1.0" encoding="utf-8" ?>

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

                   assembly="TreeStructure"

                   namespace="TreeStructure">

  <class name="Equipment">

    <id name="Id">

      <generator class="guid"/>

    </id>

    <property name="Name" length="50" not-null="true" unique="true"/>

    <many-to-one name="Parent" class="Equipment" column="ParentId" />

    <set name="Children" cascade="all-delete-orphan" >

      <key column="ParentId" foreign-key="fk_Equipment_ParentEquipment"/>

      <one-to-many class="Equipment"/>

    </set>

  </class>

</hibernate-mapping>

The name property of the equipment must be defined and unique. The name can be at most 50 characters long.

The parent property is not mandatory (this is the default, i.e. not_null=false) since the root node has Parent equal to null.

I have defined the children collection as a Set, that is an unordered collection of unique objects. I have chosen cascade="all-delete-orphan" to instruct NHibernate that he automatically saves, updates or deletes the children of an equipment too when I save, update or delete the equipment. I also have defined that the foreign key constraint that will be defined on the database between the equipment and its parent has a friendly name (fk_Equipment_EquipmentParent).

Now I can write a unit test to check whether NHibernate can create the correct schema for me. In this sample I use a SQL Server 2005 database (the express edition is ok too) since later on I want to show some specific features only available in SQL Server. The code of the test is

[Test]

public void Can_generate_schema()

    var configuration = new Configuration();

    configuration.Configure();

    configuration.AddAssembly(typeof (Equipment).Assembly);

    // show the schema for debugging purposes

    new SchemaExport(configuration).Execute(true, false, false, false);

    // generate the schema in the database

    new SchemaExport(configuration).Execute(false, true, false, false);

This test runs successfully and generates the following output (SQL script)

if exists (select 1 from sys.objects

           where object_id = OBJECT_ID(N'[fk_Equipment_ParentEquipment]')

           AND parent_object_id = OBJECT_ID('Equipment'))

  alter table Equipment  drop constraint fk_Equipment_ParentEquipment

if exists (select * from dbo.sysobjects

           where id = object_id(N'Equipment')

           and OBJECTPROPERTY(id, N'IsUserTable') = 1)

  drop table Equipment

create table Equipment (

  Id UNIQUEIDENTIFIER not null,

  Name NVARCHAR(50) not null unique,

  ParentId UNIQUEIDENTIFIER null,

  primary key (Id)

alter table Equipment

add constraint fk_Equipment_ParentEquipment

foreign key (ParentId) references Equipment

The first part of the script drops the database objects if they are already there and in the second part of the script the table Equipment is generated as well as the foreign key constraint between the equipment and its parent. The create script for the table looks exactly like expected.

The Repository

A Repository is defined as "a mechanism for encapsulating storage, retrieval, and search behavior which emulates a collection of objects."

As said above, for each Aggregate in the domain model one defines a Repository. Since we only have one aggregate in our simple domain we also will have only one repository. Let us call it EquipmentRepository.

Now I want to be able to eager load the complete aggregate given the id of the aggregate root. I write the following unit test

[Test]

public void Can_load_aggregate_by_id()

    var equipmentId = ...;    // some id

    var equipment = _repository.GetAggregateById(equipmentId);

    Assert.IsNotNull(equipment);

    Assert.IsTrue(NHibernateUtil.IsInitialized(equipment.Parent));

    Assert.IsTrue(NHibernateUtil.IsInitialized(equipment.Children));

    Assert.AreEqual(3, equipment.Children.Count);

With this test I assert that a) I get an aggregate and b) the aggregate is fully populated. To check whether the aggregate is fully populated I use the NHibernateUtil utility class. The test assumes the existence of a equipment tree fragment in the database. Please refer to the project (here) for any details how I create this tree fragment in the SetUp of the test fixture.

A possibility to eager load an aggregate is by using a HQL query as below

public Equipment GetAggregateById(Guid equipmentId)

    using (var session = SessionManager.OpenSession())

        var sql = "from Equipment e" +

                  " left join fetch e.Parent p" +

                  " left join fetch e.Children c" +

                  " where e.Id = :id";

        var equipment = session.CreateQuery(sql)

            .SetGuid("id", equipmentId)

            .UniqueResult<Equipment>();

        return equipment;

I use left joins since either Parent can be null or the equipment has no children. The SessionManager class is a helper class which I use to provide me session objects. Please have a look at the project which you can find here for any details.

Finding the root aggregate is easy. We just have to look for an equipment whose parent is equal to null

public Equipment GetRootAggregate()

    using (var session = SessionManager.OpenSession())

        var sql = "from Equipment e" +

                  " left join fetch e.Children c" +

                  " where e.Parent is null";

        var equipment = session.CreateQuery(sql)

            .UniqueResult<Equipment>();

        return equipment;

Now some times we want to find all leaf nodes of the tree. Remember that a leaf node has by definition no children. We could use the following code for this

public ICollection<Equipment> GetAllLeafNodes()

    using (var session = SessionManager.OpenSession())

        var sql = "from Equipment e" +

                  " left join fetch e.Parent p" +

                  " where e.Children.size = 0";

        var leafs = session.CreateQuery(sql)

            .List<Equipment>();

        return leafs;

here we use the handy size function for collections provided by HQL. Note that this method delivers all leaf nodes of the tree. To only select the leaf nodes of a sub-tree starting at a given equipment node is trivial now and I leave for you as an exercise.

Eager load ancestors and descendants

To eager load all ancestors or descendants of a given equipment node we have to use native TSQL since HQL (as well as the criteria API) does not provide a generic way of doing it. Fortunately SQL server 2005 provides us the means to achieve the desired result. We have to construct a hierarchical query as below

public ICollection<Equipment> GetAllDescendantsOfEquipment(Guid equipmentId)

    using (var session = SessionManager.OpenSession())

        var sql = "with Hierachy(Id, Name, ParentId, Level)" +

                  " as" +

                  " (" +

                  "   select Id, Name, ParentId, 0 as Level" +

                  "   from Equipment e" +

                  "   where e.Id = :id" +

                  "  union all" +

                  "   select e.Id, e.Name, e.ParentId, eh.Level + 1" +

                  "   from Equipment e" +

                  "   inner join Hierachy eh" +

                  "      on e.ParentId = eh.Id" +

                  " )" +

                  " select Id, Name, ParentId" +

                  " from Hierachy" +

                  " where Level > 0";

        var list = session.CreateSQLQuery(sql)

            .AddEntity(typeof(Equipment))

            .SetGuid("id", equipmentId)

            .List<Equipment>();

        return list;

The last where statement in the SQL assures that the given equipment is not included in the list of descendants.

Analogous we can get the list of ancestors of a given equipment node

public ICollection<Equipment> GetAllAncestorsOfEquipment(Guid equipmentId)

    using (var session = SessionManager.OpenSession())

        var sql = "with Hierachy(Id, Name, ParentId, Level)" +

                  " as" +

                  " (" +

                  "   select Id, Name, ParentId, 0 as Level" +

                  "   from Equipment e" +

                  "   where e.Id = :id" +

                  "  union all" +

                  "   select e.Id, e.Name, e.ParentId, eh.Level + 1" +

                  "   from Equipment e" +

                  "   inner join Hierachy eh" +

                  "      on e.Id = eh.ParentId" +

                  " )" +

                  " select Id, Name, ParentId" +

                  " from Hierachy" +

                  " where Level > 0";

        var list = session.CreateSQLQuery(sql)

            .AddEntity(typeof(Equipment))

            .SetGuid("id", equipmentId)

            .List<Equipment>();

        return list;

Note that we had just to adjust the inner join between the Equipment table and the Hierarchy (temp) table. Again the last where statement in the SQL assures that the given equipment is not included in the list of ancestors.

An alternative approach

We can also choose another approach for the tree problem. The solution I want to show works for any database even if it does not support hierarchical queries. This time our simple domain model looks as follows

Here we have a node object which can have a parent and a collection of children. Additionally we have defined the two collections descendants and ancestors which contain all descendants (children, children of the children and so on) and all parents of the given node.

The code for the Node class is given by

public class Node

    public Guid Id { get; set; }

    public string Name { get; set; }

    public Node Parent { get; set; }

    public ISet<Node> Children { get; set; }

    public ISet<Node> Ancestors { get; set; }

    public ISet<Node> Descendants { get; set; }

The mapping for the node is defined as

<?xml version="1.0" encoding="utf-8" ?>

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

                   assembly="TreeStructure"

                   namespace="TreeStructure">

  <class name="Node">

    <id name="Id">

      <generator class="guid"/>

    </id>

    <property name="Name" length="50" not-null="true" unique="true"/>

    <many-to-one name="Parent" class="Node" column="ParentId" />

    <set name="Children" inverse="true" cascade="all" >

      <key column="ParentId" foreign-key="fk_Node_ParentNode"/>

      <one-to-many class="Node"/>

    </set>

    <set name="Descendants" table="NodeHierarchy" inverse="true" >

      <key column="ParentId" foreign-key="fk_HierarchyNode_ParentNode"/>

      <many-to-many class="Node" column="ChildId" foreign-key="fk_HierarchyNode_ChildNode" />

    </set>

    <set name="Ancestors" table="NodeHierarchy" >

      <key column="ChildId" />

      <many-to-many class="Node" column="ParentId" />

    </set>

  </class>

</hibernate-mapping>

Note that we define the descendants and ancestors of a node as a many-to-many relation in the database. So the SQL script created by the SchemaExport class of NHibernate is

if exists (select 1 from sys.objects

           where object_id = OBJECT_ID(N'[fk_Node_ParentNode]')

           AND parent_object_id = OBJECT_ID('Node'))

  alter table Node  drop constraint fk_Node_ParentNode

if exists (select 1 from sys.objects

           where object_id = OBJECT_ID(N'[fk_HierarchyNode_ChildNode]')

           AND parent_object_id = OBJECT_ID('NodeHierarchy'))

  alter table NodeHierarchy  drop constraint fk_HierarchyNode_ChildNode

if exists (select 1 from sys.objects

           where object_id = OBJECT_ID(N'[fk_HierarchyNode_ParentNode]')

           AND parent_object_id = OBJECT_ID('NodeHierarchy'))

  alter table NodeHierarchy  drop constraint fk_HierarchyNode_ParentNode

if exists (select * from dbo.sysobjects

           where id = object_id(N'Node')

           and OBJECTPROPERTY(id, N'IsUserTable') = 1)

  drop table Node

if exists (select * from dbo.sysobjects

           where id = object_id(N'NodeHierarchy')

           and OBJECTPROPERTY(id, N'IsUserTable') = 1)

  drop table NodeHierarchy

create table Node

  Id UNIQUEIDENTIFIER not null,

  Name NVARCHAR(50) not null unique,

  ParentId UNIQUEIDENTIFIER null,

  primary key (Id))

create table NodeHierarchy

  ParentId UNIQUEIDENTIFIER not null,

  ChildId UNIQUEIDENTIFIER not null,

  primary key (ParentId, ChildId)

alter table Node add constraint fk_Node_ParentNode

foreign key (ParentId) references Node

alter table NodeHierarchy add constraint fk_HierarchyNode_ChildNode

foreign key (ChildId) references Node

alter table NodeHierarchy add constraint fk_HierarchyNode_ParentNode

foreign key (ParentId) references Node

we can see here that the script creates a n-to-m mapping table called NodeHierarchy as well as the necessary foreign keys between this table and the table Node.

To account for this special situation I define an AddChild method on the Node class

public virtual void AddChild(Node childNode)

    Children.Add(childNode);

    childNode.Parent = this;

    childNode.Ancestors.AddAll(this.Ancestors);

    childNode.Ancestors.Add(this);

    this.Descendants.Add(childNode);

This method is responsible for the book-keeping when adding a new child node to an existing node.

If I now want to eager load a node given by its id with all collections populated then I can use code similar to this one

public Node GetAggregateById(Guid nodeId)

    using (var session = SessionManager.OpenSession())

        var sql = "from Node e" +

                  " left join fetch e.Parent p" +

                  " left join fetch e.Children c" +

                  " where e.Id = :id";

        var node = session.CreateQuery(sql)

            .SetGuid("id", nodeId)

            .UniqueResult<Node>();

        // load the ancestors

        var sql2 = "from Node e" +

                  " left join fetch e.Ancestors a" +

                  " where e.Id = :id";

        node = session.CreateQuery(sql2)

            .SetGuid("id", nodeId)

            .UniqueResult<Node>();

        // load the descendants

        var sql3 = "from Node e" +

                  " left join fetch e.Descendants d" +

                  " where e.Id = :id";

        node = session.CreateQuery(sql3)

            .SetGuid("id", nodeId)

            .UniqueResult<Node>();

        return node;

For an in depth discussion of how to eager load a complex object graph please refer to this post.

Note that depending on the depth of the tree you should eventually avoid to eager load the descendants collection since this collection can become huge... In may sample I assume a tree with limited depth (e.g. less than 5) and a limited amount of children per node (e.g. less than 5).

Enjoy

Your first NHibernate based application

NHibernate's Answers — Tue, 01 Apr 2008 12:29:46 GMT

In a previous article I showed how to setup a developer machine to start using NHibernate as an ORM tool during the development of an application. I advocated a domain driven design (DDD) approach and a test driven development (TDD) style. This is the second article in a series of introductory chapters.

Define the Domain

Lets start by defining a very simple domain. For the moment it consists of one entity called Product. The product has 3 properties Name, Category and Discontinued.

Add a folder Domain to the FirstSample project of your solution. Add a new class Product.cs to this folder. The code is very simple and uses automatic properties (a feature of the new C# 3.0 compiler)

namespace FirstSolution.Domain

    public class Product

        public string Name { get; set; }

        public string Category { get; set; }

        public bool Discontinued { get; set; }

Now we want to be able to persist instances of this entity in a (relational) database. We have chosen NHibernate for this task. An instance of an entity in the domain corresponds to a row in a table in the database. So we have to define a mapping between the entity and the corresponding table in the database. This mapping can be done either by defining a mapping file (an xml-document) or by decorating the entity with attributes. I'll start with the mapping file.

Define the Mapping

Create a folder Mappings in the FirstSample project. Add a new xml-document to this folder and call it Person.hbm.xml. Please note the "hbm" part of the file name. This is a convention used by NHibernate to automatically recognize the file as a mapping file. Define "Embedded Resource" as Build Action for this xml file.

In the Windows Explorer locate the nhibernate-mapping.xsd in the src folder of NHibernate and copy it to your SharedLibs folder. We can now use this xml schema definition file when defining our mapping files. VS will then provide intellisense and validation when editing an xml mapping document.

Back in VS add the schema to the Product.hbm.xml file

Let's start now. Each mapping file has to define a <hibernate-mapping> root node

<?xml version="1.0" encoding="utf-8" ?>

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

                   assembly="FirstSolution"

                   namespace="FirstSolution.Domain">

  <!-- more mapping info here -->

</hibernate-mapping>

In a mapping file when referencing a domain class you always have to provide the fully qualified name of the class (e.g. FirstSample.Domain.Product, FirstSample). To make the xml less verbose you can define the assembly name (in which the domain classes are implemented and the namespace of the domain classes in the two attributes assembly and namespace of the root node. It's similar to the using statement in C#.

Now we have to first define a primary key for the product entity. Technically we could take the property Name of the product since this property must be defined and has to be unique. But it is common to use a surrogate key instead. For thus we add a property to our entity and call it Id. We use Guid as the type of the Id but it can as well be an int or a long.

using System;

namespace FirstSolution.Domain

    public class Product

        public Guid Id { get; set; }

        public string Name { get; set; }

        public string Category { get; set; }

        public bool Discontinued { get; set; }

The complete mapping file

<?xml version="1.0" encoding="utf-8" ?>

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

                   assembly="FirstSolution"

                   namespace="FirstSolution.Domain">

  <class name="Product">

    <id name="Id">

      <generator class="guid" />

    </id>

    <property name="Name" />

    <property name="Category" />

    <property name="Discontinued" />

  </class>

</hibernate-mapping>

NHibernate doesn't get in our way such as that it defines many reasonable defaults. So if you don't provide a column name for a property explicitly it will name the column according to the property. Or NHibernate can automatically infer the name of the table or the type of the column from the class definition. As a consequence my xml mapping file is not cluttered with redundant information. Please refer to the online documentation for more detailed explanation of the mapping. You can find it here.

Your solution explorer should look like this now (Domain.cd contains the class diagram of our simple domain)

Configure NHibernate

We now have to tell NHibernate which database product we want to use and provide it the connection details in form of a connection string. NHibernate supports many many database products!

Add a new xml file to the FirstSolution project and call it hibernate.cfg.xml. Set its property "Copy to Output" to "Copy always". Since we are using SQL Server Compact Edition in this first sample enter the following information into the xml file

<?xml version="1.0" encoding="utf-8" ?>

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

  <session-factory>

    <property name="connection.provider">NHibernate.Connection.DriverConnectionProvider</property>

    <property name="dialect">NHibernate.Dialect.MsSqlCeDialect</property>

    <property name="connection.driver_class">NHibernate.Driver.SqlServerCeDriver</property>

    <property name="connection.connection_string">Data Source=FirstSample.sdf</property>

    <property name="show_sql">true</property>

  </session-factory>

</hibernate-configuration>

With this configuration file we tell NHibernate that we want to use MS SQL Server Compact Edition as our target database and that the name of the database shall be FirstSample.sdf (=connection string). We have also defined that we want to see the SQL NHibernate generates and sends to the datbase (highly recommended for debugging purposes during development). Double check that you have no typos in the code!

Add an empty database called FirstSample.sdf to the FirstSample project (choose Local Database as template)

Click Add and ignore the DataSet creation wizard (just hit Cancel).

Test the Setup

It's now time to test our setup. First verify that you have the following files in your SharedLibs folder

The last 8 files you can find in the "Microsoft SQL Server Compact Edition" directory in your Programs folder.

Note: the System.Data.SqlServerCe.dll is located in the sub-folder Desktop.

All other files can be found in the NHibernate folder

Add a reference to the FirstSample project in your test project. Additionally add references to NHibernate.dll, nunit.framework.dll and Systm.Data.SqlServerCe.dll (remember to reference the files located in the SharedLibs folder!). Pay attention to set the property "Copy Local" to true for the assembly System.Data.SqlServerCe.dll since by default it is set to false!

Add a class called GenerateSchema_Fixture to your test project. Your test project should now look like this

We further need the 7 files sqce*.dll in the output directory. We can do this by using a post-build event in VS. Enter the following command in the "Post-build event command line"

copy $(ProjectDir)..\..\SharedLibs\sqlce*.dll $(ProjectDir)$(OutDir)

Now add the following code to the GenerateSchema_Fixture file

using FirstSolution.Domain;

using NHibernate.Cfg;

using NHibernate.Tool.hbm2ddl;

using NUnit.Framework;

namespace FirstSolution.Tests

    [TestFixture]

    public class GenerateSchema_Fixture

        [Test]

        public void Can_generate_schema()

            var cfg = new Configuration();

            cfg.Configure();

            cfg.AddAssembly(typeof (Product).Assembly);

            new SchemaExport(cfg).Execute(false, true, false, false);

The first line of the test method creates a new instance of the NHibernate configuration class. This class is used to configure NHibernate. In the second line we tell NHibernate to configure itself. NHibernate will look out for configuration information since we do not provide any information here in the test method. So NHibernate will search for a file called hibernate.cfg.xml in the output directory. That's exactly what we want since we have defined our settings in this file.

In the third line of the code we tell NHibernate that it can find mapping information in the assembly which contains also the class Product. At the time being it will only find one such file (Product.hbm.xml) as an embedded resource.

The fourth line of code uses the SchemaExport helper class of NHibernate to auto-"magically" generate the schema in the database for us.

Note: with this test method we do NOT want to find out whether NHibernate does its job correctly (you can be sure it does) but rater whether we have setup our system correctly.

If you have TestDriven.Net installed you can now just right click inside the test method and choose "Run Test(s)" to execute the test.

If every thing is ok you should see the following result in the output window

If you have ReSharper installed you can just start the test by clicking the yellow-green circle on the left border and choose Run.

The result is as follows

In case of Problems

If your test fails double check that you find the following files in your target directory (that is: m:dev\projects\FirstSolution\src\FirstSolution.Tests\bin\debug)

Double check also if you have no typos in the NHibernate configuration file (hibernate.cfg.xml) or in the mapping file (Product.hbm.xml). Finally check whether you have set the "Build Action" of the mapping file (Product.hbm.xml) to "Embedded Resource". Only continue if the test succeeds.

Our first CRUD operations

Now obviously our system is ready to start. We have successfully implemented our Domain, defined the mapping files and configured NHibernate. Finally we have used NHibernate to automatically generate the database schema from our Domain (and our mapping files).

In the spirit of DDD (see e.g. Domain Driven Design by Eric Evans) we define a repository for all crud operations (create, read, update and delete). The repository interface is part of the domain where as the implementation is not! The implementation is infrastructure specific. We want to keep our domain persistence ignorant (PI).

Add a new interface to the domain folder of our FirstSolution project. Call it IProductRepository. Let's define the following interface

using System;

using System.Collections.Generic;

namespace FirstSolution.Domain

    public interface IProductRepository

        void Add(Product product);

        void Update(Product product);

        void Remove(Product product);

        Product GetById(Guid productId);

        Product GetByName(string name);

        ICollection<Product> GetByCategory(string category);

Add a class ProductRepository_Fixture to the test project of the solution and add the following code

    [TestFixture]

    public class ProductRepository_Fixture

        private ISessionFactory _sessionFactory;

        private Configuration _configuration;

        [TestFixtureSetUp]

        public void TestFixtureSetUp()

            _configuration = new Configuration();

            _configuration.Configure();

            _configuration.AddAssembly(typeof (Product).Assembly);

            _sessionFactory = _configuration.BuildSessionFactory();

In the fourth line of the method TestFixtureSetUp we create a session factory. This is an expensive process and should thus be executed only once. That's the reason why I put it into this method which is only executed once during a test cicle.

To keep our test methods side effect free we re-create our database schema before the execution of each test method. Thus we add the following method

        [SetUp]

        public void SetupContext()

            new SchemaExport(_configuration).Execute(false, true, false, false);

And now we can implement the test method to add a new product instance to the database. Start by adding a new folder called Repositories to your FirstSolution project. Add a class ProductRepository to this folder. Make the ProductRepository inherit from the interface IProductRepository.

using System;

using System.Collections.Generic;

using FirstSolution.Domain;

namespace FirstSolution.Repositories

    public class ProductRepository : IProductRepository

        public void Add(Product product)

            throw new NotImplementedException();

        public void Update(Product product)

            throw new NotImplementedException();

        public void Remove(Product product)

            throw new NotImplementedException();

        public Product GetById(Guid productId)

            throw new NotImplementedException();

        public Product GetByName(string name)

            throw new NotImplementedException();

        public ICollection<Product> GetByCategory(string category)

            throw new NotImplementedException();

Manipulating Data

Now go back to the ProductRepository_Fixture test class and implement the first test method

        [Test]

        public void Can_add_new_product()

            var product = new Product {Name = "Apple", Category = "Fruits"};

            IProductRepository repository = new ProductRepository();

            repository.Add(product);

The first run of the test method will fail since we have not yet implemented the Add method in the repository class. Let's do it. But wait, we have to define a little helper class first which provides us session objects on demand.

using FirstSolution.Domain;

using NHibernate;

using NHibernate.Cfg;

namespace FirstSolution.Repositories

    public class NHibernateHelper

        private static ISessionFactory _sessionFactory;

        private static ISessionFactory SessionFactory

get

                if(_sessionFactory == null)

                    var configuration = new Configuration();

                    configuration.Configure();

                    configuration.AddAssembly(typeof(Product).Assembly);

                    _sessionFactory = configuration.BuildSessionFactory();

                return _sessionFactory;

        public static ISession OpenSession()

            return SessionFactory.OpenSession();

This class creates a session factory only the first time a client needs a new session.

Now we can define the Add method in the ProductRepository as follows

        public void Add(Product product)

            using (ISession session = NHibernateHelper.OpenSession())

                using (ITransaction transaction = session.BeginTransaction())

                    session.Save(product);

                    transaction.Commit();

The second run of the test method will again fail with the following message

That's because NHibernate is by default configured to use lazy load for all entities. That is the recommended approach and I warmly recommend not to change it for a maximum of flexibility.

How can we solve this issue? It's easy we have to just make all our properties (and methods) of the domain object(s) virtual. Let's do this for our Product class

    public class Product

        public virtual Guid Id { get; set; }

        public virtual string Name { get; set; }

        public virtual string Category { get; set; }

        public virtual bool Discontinued { get; set; }

Now run the test again. It should succeed and we get the following output

Note the sql spit out by NHibernate.

Now we think that we have successfully inserted a new product into the database. But let's test it whether it is really so. Let's extend our test method

        [Test]

        public void Can_add_new_product()

            var product = new Product {Name = "Apple", Category = "Fruits"};

            IProductRepository repository = new ProductRepository();

            repository.Add(product);

            // use session to try to load the product

            using(ISession session = _sessionFactory.OpenSession())

                var fromDb = session.Get<Product>(product.Id);

                // Test that the product was successfully inserted

                Assert.IsNotNull(fromDb);

                Assert.AreNotSame(product, fromDb);

                Assert.AreEqual(product.Name, fromDb.Name);

                Assert.AreEqual(product.Category, fromDb.Category);

Run the test again. Hopefully it will succeed...

Now we are ready to implement also the other methods of the repository. For testing this we would rather have a repository (that is database table) already containing some products. Nothing easier than this. Just add a method CreateInitialData to the test class as follows

        private readonly Product[] _products = new[]

                     new Product {Name = "Melon", Category = "Fruits"},

                     new Product {Name = "Pear", Category = "Fruits"},

                     new Product {Name = "Milk", Category = "Beverages"},

                     new Product {Name = "Coca Cola", Category = "Beverages"},

                     new Product {Name = "Pepsi Cola", Category = "Beverages"},

};

        private void CreateInitialData()

            using(ISession session = _sessionFactory.OpenSession())

                using(ITransaction transaction = session.BeginTransaction())

                    foreach (var product in _products)

                        session.Save(product);

                    transaction.Commit();

Call this method from the SetupContext method (after the create schema call) and we are done. Now each time after the database schema is created the database is populated with some products.

Let's test the Update method of the repository with the following code

        [Test]

        public void Can_update_existing_product()

            var product = _products[0];

            product.Name = "Yellow Pear";

            IProductRepository repository = new ProductRepository();

            repository.Update(product);

            // use session to try to load the product

            using (ISession session = _sessionFactory.OpenSession())

                var fromDb = session.Get<Product>(product.Id);

                Assert.AreEqual(product.Name, fromDb.Name);

When running for the first time this code will fail since the Update method has not yet been implemented in the repository. Note: This is the expected behavior since in TDD the first time you run a test it should always fail!

Analogous to the Add method we implement the Update method of the repository. The only difference is that we call the update method of the NHibernate session object instead of the save method.

        public void Update(Product product)

            using (ISession session = NHibernateHelper.OpenSession())

            using (ITransaction transaction = session.BeginTransaction())

                session.Update(product);

                transaction.Commit();

Run the test again an watch it succeed.

The delete method is straight forward. When testing whether the record has really been deleted we just assert that the value returned by the session's get method is equal to null. Here is the test method

        [Test]

        public void Can_remove_existing_product()

            var product = _products[0];

            IProductRepository repository = new ProductRepository();

            repository.Remove(product);

            using (ISession session = _sessionFactory.OpenSession())

                var fromDb = session.Get<Product>(product.Id);

                Assert.IsNull(fromDb);

and here the implementation of the Remove method in the repository

        public void Remove(Product product)

            using (ISession session = NHibernateHelper.OpenSession())

                using (ITransaction transaction = session.BeginTransaction())

                    session.Delete(product);

                    transaction.Commit();

Querying the Database

We still have to implement the three methods which query the database for objects. Let's start with the most easy one, the GetById. First we write the test

        [Test]

        public void Can_get_existing_product_by_id()

            IProductRepository repository = new ProductRepository();

            var fromDb = repository.GetById(_products[1].Id);

            Assert.IsNotNull(fromDb);

            Assert.AreNotSame(_products[1], fromDb);

            Assert.AreEqual(_products[1].Name, fromDb.Name);

and then the code to fulfill the test

        public Product GetById(Guid productId)

            using (ISession session = NHibernateHelper.OpenSession())

                return session.Get<Product>(productId);

Now that was easy. For the following two methods we use a new method of the session object. Let's start with the GetByName method. As usual we write the test first

        [Test]

        public void Can_get_existing_product_by_name()

            IProductRepository repository = new ProductRepository();

            var fromDb = repository.GetByName(_products[1].Name);

            Assert.IsNotNull(fromDb);

            Assert.AreNotSame(_products[1], fromDb);

            Assert.AreEqual(_products[1].Id, fromDb.Id);

The implementation of the GetByName method can be done by using two different approaches. The first is using HQL (Hibernate Query Language) and the second one HCQ (Hibernate Criteria Query). Let's start with HQL. HQL is a object oriented query language similar (but not equal to) SQL.

        public Product GetByName(string name)

            using (ISession session = NHibernateHelper.OpenSession())

                Product product = session

                    .CreateQuery("from Product p where p.Name=:name")

                    .SetString("name", name)

                    .UniqueResult<Product>();

                return product;

In the above sample I have introduced a commonly used technique when using NHibernate. It's called fluent interfaces. As a result the code is less verbose and easier to understand. You can see that a HQL query is a string which can have embedded (named) parameters. Parameters are prefixed by a ':'. NHibernate defines many helper methods (like SetString used in the example) to assign values of various types to those parameters. Finally by using UniqueResult I tell NHibernate that I expect only one record to return. If more than one record is returned by the HQL query then an exception is raised. To get more information about HQL please read the online documentation.

The second version uses a criteria query to search the requested product.

        public Product GetByName(string name)

            using (ISession session = NHibernateHelper.OpenSession())

                Product product = session

                    .CreateCriteria(typeof(Product))

                    .Add(Restrictions.Eq("Name", name))

                    .UniqueResult<Product>();

                return product;

Many users of NHibernate think that this approach is more object oriented. On the other hand a complex query written with criteria syntax can quickly become difficult to understand.

The last method to implement is GetByCategory. This method returns a list of products. The test can be implemented as follows

        [Test]

        public void Can_get_existing_products_by_category()

            IProductRepository repository = new ProductRepository();

            var fromDb = repository.GetByCategory("Fruits");

            Assert.AreEqual(2, fromDb.Count);

            Assert.IsTrue(IsInCollection(_products[0], fromDb));

            Assert.IsTrue(IsInCollection(_products[1], fromDb));

        private bool IsInCollection(Product product, ICollection<Product> fromDb)

            foreach (var item in fromDb)

                if (product.Id == item.Id)

                    return true;

            return false;

and the method itself might contain the following code

        public ICollection<Product> GetByCategory(string category)

            using (ISession session = NHibernateHelper.OpenSession())

                var products = session

                    .CreateCriteria(typeof(Product))

                    .Add(Restrictions.Eq("Category", category))

                    .List<Product>();

                return products;

Summary

In this article I have shown you how to implement a basic sample domain, define the mapping to a database and how to configure NHibernate to be able to persist domain objects in the database. I have shown you how to typically write and test CRUD methods for your domain objects. I have taken MS SQL Compact Edition as sample database but any other supported database can be used (you only have to change the hibernate.cfg.xml file accordingly). Ee have no dependencies on external frameworks or tools other than the database and NHibernate itself (.NET of course never counts here).