Of course, not everyone remembers to set those lengths, so I thought it'd be great if I could force people to do this. With a little creative use of Fluent NHibernate's conventions, it's quite easy to enforce this:

public class StringsMustHaveLengthConvention: IPropertyConvention, IPropertyConventionAcceptance
{
    public void Apply(IPropertyInstance instance)
    {
        var msg = string.Format("The string property '{0}' of type '{1}' does not have a length value specified, " +
            "which is required for performance reasons. Add something like this to your mapping override:\r\n" + 
            "\tmapping.Map(e => e.{0}).Length(50); // with an appropriate length for this property",
            instance.Property.Name, instance.EntityType.Name);

        throw new MappingException(msg);
    }

    public void Accept(IAcceptanceCriteria<IPropertyInspector> criteria)
    {
        criteria.Expect(x => x.Type == typeof(string)).Expect(x => x.Length == 0);
    }
}

With that convention in place, you won't even be able to run your code until you've specified the string lengths

Bart and his team were the first people to attend the course almost 2 months ago, so i wasn't entirely sure yet of the format and the content at that time. This week i'm actually doing the course for the third time, and apart from some very minor changes and tweaks, it's pretty much the exact same as when i did it the first time, except that i'm not nearly as nervous now as i was when i did it the first time. Luckily for me, his team was fun to hang out with and there was plenty of joking around which definitely made it easy to just be comfortable instead of being a nervous wreck

• optimistic concurrency
  • optimistic-lock="all"
  • optimistic-lock="dirty"
  • version
• pessimistic locking
• performance
  • executable hql (updates/deletes)
  • extra lazy collection
  • futures
  • paging through collections
  • proxies
• querying
  • aggregate functions (HQL/Criteria/LINQ/QueryOver)
  • eager fetching (HQL/Criteria/LINQ/QueryOver)
  • group by (HQL/Criteria/LINQ/QueryOver)
  • ordering (HQL/Criteria/LINQ/QueryOver)
  • paging (HQL/Criteria/LINQ/QueryOver)
  • polymorphism (HQL/Criteria/LINQ/QueryOver)
  • projections (HQL/Criteria/LINQ/QueryOver)
  • restrictions (HQL/Criteria/LINQ/QueryOver)
  • subqueries (HQL/Criteria/LINQ/QueryOver)
  • unique results (HQL/Criteria/LINQ/QueryOver)
  • native sql
  • stored procedures

And there's quite a bit more to come in the next 2 weeks or so...

The examples now also run on SQL Server with both Fluent NHibernate as well as normal mapping files. If you're interested, you can get them here.

The solution consists of a suite of automated tests that run on a SQLite database, which demonstrate some features of NHibernate. All tests currently run with the classic HBM mapping files and FluentNHibernate. Choosing which of the two is used can be done by selecting the correct build configuration (either HBMSQLITE or FLUENTSQLITE) before running the tests. Running the tests doesn't require any software to be installed or any configuration to be performed by you. Though you can obviously run the tests on different databases if you want to. The object model that is used is based on Northwind with a couple of changes. The object model can evolve into whatever it needs to be to showcase NHibernate features/usage. Some other models might also be introduced later on to show features that wouldn't fit well with the Northwind-based model.

These examples could be useful to people who are new to NHibernate, but could be interesting for experienced NHibernate users as well, if only as a playground to quickly experiment with some features that you're unsure of.

You can find the code here or you can always download the latest version here.

To those who did register: thanks for wanting to come, and sorry that you won't be able to. Perhaps some other time.

Update: First customer for having the course on-site has signed up. If you're interested in that as well, get in touch. Update 2: new date for the public course is June 20-22

This is the agenda for the course:

Day 1:

• Quick ORM Introduction
• Configuration
• Classes & Mapping (hbm & fluent-nhibernate)
  • Entities
  • One-to-many associations
  • Many-to-one associations
  • Inheritance
• Session/Transaction Management
  • In web applications
  • In service layers
• Transitive Persistence
  • Transient & Persistent Entities
  • Cascades
  • Detached Entities

Day 2:

• Querying
  • HQL
  • Criteria
  • QueryOver
  • LINQ
  • Polymorphic Queries
  • Named Queries
• Performance Optimizations
  • Paging
  • Projections
  • Future Queries
  • Batching DML statements
  • Executable HQL (deletes/updates)
  • Stored Procedures/Views
  • Using native SQL
• Optimistic Concurrency strategies
• Pessimistic Locking

Day 3:

• Identifier strategies
• Inheritance strategies
• Advanced mappings
  • Value type collections
  • Components
  • Component collections
  • (composite) User Types
  • Many-to-Many associations
  • Polymorphic associations
• 2nd Level cache
  • Caching entities
  • Caching collections
  • Caching queries
• Stateless Sessions

(Sorry for this shameless plug, but you'd do it too if you were me )

I just made a list of stuff that i'd like to cover, which is already pretty long. I'd rather start off with a long list and if necessary make some cuts if it turns out to be too much. If you guys have any tips on what else i should include, please let me know

Here's the current list:

• Configuration
• Classes & Mapping (hbm and FluentNHibernate)
  • entities
  • one-to-many associations (unidirectional & bidirectional)
  • many-to-one associations (unidirectional & bidirectional)
  • inheritance
• Session/Transaction Management
  • session/transaction management in a web app
  • session/transaction management in a service layer
• Transitive Persistence
  • transient and persistent entities
  • cascades
  • detached entities
• Querying
  • HQL
  • criteria
  • QueryOver
  • LINQ
  • polymorphic queries
  • named queries
• Performance optimisations
  • paging
  • projections
  • future queries
  • batching DML statements
  • executable HQL
  • retrieving data from stored procedures / views
  • using native SQL
• optimistic concurrency
• pessimistic locking
• identifier strategies
• inheritance strategies
• advanced mappings
  • value types collections
  • components
  • component collections
  • (composite) user types
  • many-to-many associations (unidirectional & bidirectional)
  • polymorphic associations (one-to-many, many-to-one)
• 2nd Level Cache
  • entities
  • collections
  • queries
• stateless sessions (bulk data processing)
• extending nhibernate
  • custom implementations of NHibernate components
  • event listeners

As the title says, it's a cookbook. It consists of a bunch of recipes for a very large variety of NHibernate-related tasks. These kind of books are usually pretty low on theory, but this one does a good job of backing up most of the recipes' practical steps with just enough of the background theory that you do need to use NHibernate effectively. I still prefer the approach used in NHibernate In Action, which is more heavy on theory, but that book unfortunately targets NHibernate 1.2. This one covers a lot of the new things that have been introduced in NHibernate 2, 2.1 and the upcoming 3.0 version and as such, is the most suitable NHibernate book available right now.

I'm not gonna go over each chapter like i usually do, so if you want to get a a glimpse of what the book covers, just click here. And as you can see, it covers quite a lot. As usual with NHibernate books, i'd like to see a bit more pages being spent on querying, but this task only becomes harder as NHibernate keeps adding more querying API's. Yes, both QueryOver and the LINQ Provider are covered. Unfortunately, the whole chapter that deals with querying covers HQL, Criteria, QueryOver and LINQ in a mere 44 pages. And while there are some examples of each, none of them are really covered in depth. That's probably not the goal of this book, and it would indeed be hard for any book to cover all of those querying API's in depth while not boring the hell out of your readers, but it is something that a lot of readers are going to need to look into a bit more if they're going to use NHibernate in real applications.

But don't let my nitpicking on the querying chapter fool you. This book is very useful to people who are new to NHibernate, and a lot of people who already have experience with it will learn a few new useful tricks or learn some things they didn't know yet. And while it contains a lot of useful information, it also manages to be a pretty quick read. And if you need any more convincing, just take a look at the price of the electronic version of this book

We have a scenario which consists of 15 'actions'. For these actions, we use some tables from the Chinook database, basically just Artist/Album/Track/Genre/MediaType. The actions are the following:

1. Retrieve single track without joins, and access each non-reference property
2. Retrieve single track with joins, and access all properties, including references
3. Retrieve single track without joins, and access all properties, including references (triggers lazy-loading)
4. Create and persist object graph: one artist with two albums with 13 tracks each
5. Retrieve created artist from nr 4, add a new album with another 13 tracks, change the title of the first album from nr 4, and remove the second album from nr 4 including its tracks
6. Retrieve created artist from nr 4 and delete its entire graph
7. Create a single track
8. Retrieve single track from step 7 and update it
9. Retrieve single track from step 7 and update the name of one of its referenced properties
10. Retrieve single track from step 7 and change one of the reference properties so it references a different instance
11. Delete the track from step 7
12. Retrieve 100 tracks and access each non-reference property
13. Retrieve 200 tracks and access each non-reference property
14. Retrieve 100 tracks without joins and access all properties, including references (triggers lazy-loading)
15. Retrieve 100 tracks with joins and access all properties, including references

Note: when i say we access reference properties to trigger lazy loading, i mean that we access a non-id property of the referenced property to make sure it indeed hits the database.

The scenario is ran 500 times with regular C# objects, and 500 times with Ruby objects. We keep track of the average time of each action in the scenario, as well as the total duration of the scenario. Also, keep in mind that we ran these tests on a local database.

The following graph shows the average duration of each action in milliseconds on the Y axis, and the number of the action on the X axis:

(you can click on the graph to watch it in its full size)

Before i'll discuss these results, i'd also like to show the following graph which shows the average difference in milliseconds between the static and the dynamic execution of each action:

Two actions immediately stand out: the last two which both deal with fetching a set of items and accessing all of their properties. They're both about 6ms slower than their static counterparts, which is a performance penalty of 71% for action 14, and 87% for action 15. That deals with a part of code that we can't really optimize any more. Well, it probably is possible but we've already done a lot of work on that, and this is the best we can come up with so far.

Now, those 2 actions are things we avoid as much as possible in real code anyway, so maybe they aren't that big of an issue. The other 2 actions where there is a noticable difference (though it actually means an increase in average execution time of 1.1ms using a local database) is the creation and persistance of an object graph (step 4), and the retrieval/modification/persistence of that same graph (step 5). Most other actions don't have a noticeable difference, and in some cases the dynamic version is actually faster than the static one, no doubt because NHibernate has in some cases less work to do when using the Map EntityMode (which we rely on for the dynamic stuff) compared to the Poco EntityMode.

We also wanted to see whether the performance difference would get worse when spreading the workload evenly over a set of threads, or even a 'pool' of IronRuby engines. I was pretty happy to see that it didn't really lead to a noticeable difference.

The following graph shows the average duration of the entire scenario in a couple of different situations:

I do have to mention that the numbers shown in this graph aren't averages, but the result from running the scenario once in each situation. We did however ran the scenarios in each situation more than once, and while we didn't list the averages, the numbers are representative of each testrun... we didn't see any really noticeable differences over multiple runs. The percentage difference for each situation is shown in this graph:

As you can see, the performance penalty of the entire scenario in each situation varies between 15% and 26%.

Now, considering the fact that we prefer to avoid loading 'large' sets of data through NHibernate into entities (we prefer to use projections instead for that) we wanted to see what the difference would be for the entire duration of the scenario in each situation, without the final 4 actions. Basically, just the typical CRUD scenarios:

Now the difference varies between 6% and 15%.

Now, suppose that we have a compelling reason to actually go ahead with using this approach (we do actually, but i'm not gonna get into that here), do you think we can trust these numbers? Is there anything else we're missing? Are we complete idiots for testing the performance difference like this? Do you have any feedback whatsoever? Then please leave a comment

Suppose we have the following 2 NHibernate mappings:

  <class entity-name="Artist">
    <id name="id" column="ArtistId" type="int">
      <generator class="identity"/>
    </id>

    <property name="name" length="50" type="string" />

    <bag name="albums" cascade="all-delete-orphan" inverse="true" >
      <key column="ArtistId"/>
      <one-to-many class="Album" />
    </bag>
  </class>

  <class entity-name="Album">
    <id name="id" column="AlbumId" type="int">
      <generator class="identity"/>
    </id>

    <property name="title" length="50" type="string" not-null="true" />
    <many-to-one name="artist" column="ArtistId" not-null="true" class="Artist" />
  </class>

And suppose we have the following 2 classes:

class Artist
  attr_accessor :id, :name, :albums
  
  def initialize
    self.albums = System::Collections::ArrayList.new
  end
  
  def add_album(album)
    self.albums.add(album)
    album.artist = self
  end
  
  def remove_album(album)
    self.albums.remove(album)
    album.artist = nil
  end
end

class Album
  attr_accessor :id, :title, :artist
end

The only atypical thing about that Ruby code is the usage of System::Collections::ArrayList. That's something i haven't been able to workaround yet: if you want to use collections, you'll need to use the .NET ones for now.

I'm relying on 2 things to get everything working. One is NHibernate's Map EntityMode, the other is my own Ruby magic which i'll cover later. The important thing to know is that the Map EntityMode basically works without classes, but with dictionaries. Instead of instances of entity classes, NHibernate will return or accept dictionaries where the keys correspond to property names and the values correspond to their respective property's value. Though the goal was that the developer need not use the dictionaries directly, as the above 2 Ruby classes show. I'll get into the details of the Ruby magic later on in this post, but for now it's important to know that there's an ObjectFactory class which takes care of transforming the dictionaries that i get from NHibernate to either real instances of entity classes, or proxies of them.

First, let's take a look at transitive persistence:

    using (var session = sessionFactory.OpenSession())
    {
        var artist = ruby.Artist.@new();
        artist.name = "Rage Against The Machine";

        var album1 = ruby.Album.@new();
        album1.title = "Rage Against The Machine";

        var album2 = ruby.Album.@new();
        album2.title = "Evil Empire";

        artist.add_album(album1);
        artist.add_album(album2);

        session.Save("Artist", artist);

        session.Flush();

        artistId = artist.id();
    }

The output of running that code is this:

NHibernate: INSERT INTO Artist (name) VALUES (@p0); select SCOPE_IDENTITY();@p0 = 'Rage Against The Machine' [Type: String (50)]
NHibernate: INSERT INTO Album (title, ArtistId) VALUES (@p0, @p1); select SCOPE_IDENTITY();@p0 = 'Rage Against The Machine' [Type: String (50)], @p1 = 355 [Type: Int32 (0)]
NHibernate: INSERT INTO Album (title, ArtistId) VALUES (@p0, @p1); select SCOPE_IDENTITY();@p0 = 'Evil Empire' [Type: String (50)], @p1 = 355 [Type: Int32 (0)]

As you can see, transitive persistence is working nicely, even with collections. Now let's see how we can retrieve that data from the database and into our Ruby objects. First i need to show the following 2 helper methods for displaying the data:

    private static void PrintArtistData(dynamic artist)
    {
        Console.WriteLine("Artist: " + artist.name());
        PrintAlbumData(artist.albums());
    }

    private static void PrintAlbumData(dynamic albums)
    {
        foreach (dynamic album in albums)
        {
            Console.WriteLine("\tAlbum: " + album.title());
        }
        Console.WriteLine();
    }

Now we can get the artist we just created with a simple call to session.Get:

    using (var session = sessionFactory.OpenSession())
    {
        dynamic artist = ruby.ObjectFactory.create_from_nhibernate_hash(session.Get("Artist", artistId));
        Console.WriteLine("display output from session.Get");
        PrintArtistData(artist);
    }

And here's the output of that in the console:

NHibernate: SELECT artist0_.ArtistId as ArtistId0_0_, artist0_.name as name0_0_ FROM Artist artist0_ WHERE artist0_.ArtistId=@p0;@p0 = 355 [Type: Int32 (0)]
display output from session.Get
Artist: Rage Against The Machine
NHibernate: SELECT albums0_.ArtistId as ArtistId1_, albums0_.AlbumId as AlbumId1_, albums0_.AlbumId as AlbumId1_0_, albums0_.title as title1_0_, albums0_.ArtistId as ArtistId1_0_ FROM Album albums0_ WHERE albums0_.ArtistId=@p0;@p0 = 355 [Type: Int32 (0)]
        Album: Rage Against The Machine
        Album: Evil Empire

As you can see, the lazy loading of the albums collection works just as you'd expect it to. Speaking of lazy-loading, we can do the same thing with a call to session.Load instead of session.Get:

    using (var session = sessionFactory.OpenSession())
    {
        dynamic artist = ruby.ObjectFactory.create_proxy_from_nhibernate_hash(session.Load("Artist", artistId), "Artist", artistId);
        Console.WriteLine("display output from session.Load");
        PrintArtistData(artist);
    }

As you may or may not know, session.Load returns a proxy of an entity instead of actually fetching it from the database immediately (unless the instance is already in the session cache, which my current ruby code can't handle yet). NHibernate doesn't hit the database until you access any of the properties of the entity outside of the identifier, which the output of this code clearly shows:

display output from session.Load
NHibernate: SELECT artist0_.ArtistId as ArtistId0_0_, artist0_.name as name0_0_ FROM Artist artist0_ WHERE artist0_.ArtistId=@p0;@p0 = 355 [Type: Int32 (0)]
Artist: Rage Against The Machine
NHibernate: SELECT albums0_.ArtistId as ArtistId1_, albums0_.AlbumId as AlbumId1_, albums0_.AlbumId as AlbumId1_0_, albums0_.title as title1_0_, albums0_.ArtistId as ArtistId1_0_ FROM Album albums0_ WHERE albums0_.ArtistId=@p0;@p0 = 355 [Type: Int32 (0)]
        Album: Rage Against The Machine
        Album: Evil Empire

Notice that the select statement is outputted right before we access the name of the artist, instead of immediately as in the previous example.

We've got lazy-loading covered, but what about eager loading? Well, take a look at the following code:

    using (var session = sessionFactory.OpenSession())
    {
        var artistHash = session.CreateCriteria("Artist")
            .Add(Restrictions.IdEq(artistId))
            .SetFetchMode("albums", FetchMode.Join)
            .List()[0];

        dynamic artist = ruby.ObjectFactory.create_from_nhibernate_hash(artistHash);
        Console.WriteLine("display output from session.CreateCriteria without any lazy loading");
        PrintArtistData(artist);
    }

This fetches our artist and immediately joins its albums in the same query. When we access the albums of the artist, it no longer needs to go to the database:

NHibernate: SELECT this_.ArtistId as ArtistId0_1_, this_.name as name0_1_, albums2_.ArtistId as ArtistId3_, albums2_.AlbumId as AlbumId3_, albums2_.AlbumId as AlbumId1_0_, albums2_.title as title1_0_, albums2_.ArtistId as ArtistId1_0_ FROM Artist this_ left outer join Album albums2_ on this_.ArtistId=albums2_.ArtistId WHERE this_.ArtistId = @p0;@p0 = 355 [Type: Int32 (0)]
display output from session.CreateCriteria without any lazy loading
Artist: Rage Against The Machine
        Album: Rage Against The Machine
        Album: Evil Empire

Obviously, if we omit setting the fetchmode of the albums association we get the same output as we would get from using session.Get:

    using (var session = sessionFactory.OpenSession())
    {
        var artistHash = session.CreateCriteria("Artist")
            .Add(Restrictions.IdEq(artistId))
            .List()[0];

        dynamic artist = ruby.ObjectFactory.create_from_nhibernate_hash(artistHash);
        Console.WriteLine("display output from session.CreateCriteria with lazy loading of albums");
        PrintArtistData(artist);
    }

NHibernate: SELECT this_.ArtistId as ArtistId0_0_, this_.name as name0_0_ FROM Artist this_ WHERE this_.ArtistId = @p0;@p0 = 355 [Type: Int32 (0)]
display output from session.CreateCriteria with lazy loading of albums
Artist: Rage Against The Machine
NHibernate: SELECT albums0_.ArtistId as ArtistId1_, albums0_.AlbumId as AlbumId1_, albums0_.AlbumId as AlbumId1_0_, albums0_.title as title1_0_, albums0_.ArtistId as ArtistId1_0_ FROM Album albums0_ WHERE albums0_.ArtistId=@p0;@p0 = 355 [Type: Int32 (0)]
        Album: Rage Against The Machine
        Album: Evil Empire

Eager fetching also works in the other direction, when fetching albums with their artist included automatically:

    using (var session = sessionFactory.OpenSession())
    {
        var albumsList = session.CreateCriteria("Album")
            .CreateAlias("artist", "a", JoinType.InnerJoin)
            .SetMaxResults(5)
            .List();

        dynamic albums = ruby.ObjectFactory.create_multiple_from_nhibernate_list(albumsList);

        foreach (dynamic album in albums)
        {
            Console.WriteLine(string.Format("'{0}' by '{1}'", album.title(), album.artist().name()));
        }
    }

This results in the following output:

NHibernate: SELECT TOP (@p0) this_.AlbumId as AlbumId1_1_, this_.title as title1_1_, this_.ArtistId as ArtistId1_1_, a1_.ArtistId as ArtistId0_0_, a1_.name as name0_0_ FROM Album this_ inner join Artist a1_ on this_.ArtistId=a1_.ArtistId;@p0 = 5 [Type: Int32 (0)]
'For Those About To Rock We Salute You 2' by 'Accept'
'Balls to the Wall' by 'Accept'
'Restless and Wild' by 'Accept'
'Let There Be Rock' by 'AC/DC'
'Big Ones' by 'Aerosmith'

Finally, we'll retrieve our artist and modify some of its data:

    using (var session = sessionFactory.OpenSession())
    {
        dynamic artist = ruby.ObjectFactory.create_from_nhibernate_hash(session.Get("Artist", artistId));

        artist.name = "RATM";
        artist.albums()[1].title = "The Battle Of Los Angeles";

        artist.remove_album(artist.albums()[0]);

        dynamic newAlbum = ruby.Album.@new();
        newAlbum.title = "Renegades";
        artist.add_album(newAlbum);

        session.Flush();
    }

If we then run the following code again:

    using (var session = sessionFactory.OpenSession())
    {
        dynamic artist = ruby.ObjectFactory.create_from_nhibernate_hash(session.Get("Artist", artistId));
        Console.WriteLine("display output from session.Get");
        PrintArtistData(artist);
    }

We can see that the data has indeed been changed as it should:

NHibernate: SELECT artist0_.ArtistId as ArtistId0_0_, artist0_.name as name0_0_ FROM Artist artist0_ WHERE artist0_.ArtistId=@p0;@p0 = 355 [Type: Int32 (0)]
display output from session.Get
Artist: RATM
NHibernate: SELECT albums0_.ArtistId as ArtistId1_, albums0_.AlbumId as AlbumId1_, albums0_.AlbumId as AlbumId1_0_, albums0_.title as title1_0_, albums0_.ArtistId as ArtistId1_0_ FROM Album albums0_ WHERE albums0_.ArtistId=@p0;@p0 = 355 [Type: Int32 (0)]
        Album: The Battle Of Los Angeles
        Album: Renegades

Ok, so how does this all work? After all, NHibernate returns and expects dictionaries and as you can see in the code of the ruby classes, there are no dictionaries being used. The answer is actually pretty simple. NHibernate returns and expects dictionaries. I return and expect entity instances. Clearly, all we need to do is make sure that our entities pretend to be dictionaries and NHibernate will never need to know what on earth we're doing.

The first thing we need to do is to modify the implementation of the ruby classes that we have created for our entities. Obviously, i wouldn't want anyone to have to do that manually, so my ruby magic just does this at runtime. The only limit that is placed on the code you write in ruby is that within the entity classes, you can never touch the private instance fields of the attributes that you've defined. You always have to go through the accessors. Because of that limit, i can just replace all of the accessor methods with implementations that use the dictionary that NHibernate gives me as the backing store of the data instead of using instance fields. I also make sure that all equality checks are based on the underlying dictionary instead of the actual object. This passes everything but a straight-up reference check. Finally, we need to make sure that our objects can be cast to an IDictionary and that we implement the indexer property of the IDictionary interface because NHibernate will use that when we pass it transient instances to insert into the database.

First, let's take a look at the ObjectFactory class, which has a couple of class methods that we use from our .NET code to create entities based on the dictionaries that we get from NHibernate:

class ObjectFactory
  def self.create_from_nhibernate_hash(hashtable)
    entity_name = hashtable[NHibernator::TYPE_KEY_NAME.to_clr_string]
    entity = const_get(entity_name.to_sym).new
    entity.hydrate_from hashtable
    entity    
  end
  
  def self.create_proxy_from_nhibernate_hash(hashtable, entity_name, id)
    proxy = const_get("#{entity_name}Proxy".to_sym).new
    proxy.hydrate_from hashtable, id
    proxy
  end
  
  def self.create_multiple_from_nhibernate_list(list)
    entities = []
    # TODO: differentiate between proxies and normal entities in the list
    list.each { |hash| entities << create_from_nhibernate_hash(hash) }
    entities
  end
end

(as you can see from the TODO statement, this whole thing is still a work in progress)

Pretty simple stuff so far... We either create a new instance of the entity class, or of a proxy class for that entity type (i'll cover the creation of proxy classes soon). We then call its hydrate_from method, which is also added to each entity class dynamically. There's another (temporary) limitation here... i search for the class name constant in Object, which means that our current approach doesn't work when our entities have namespaces. Not really a problem for this example, and is easy to add later on when i actually need it. That's it for the ObjectFactory... the real magic is all contained in the NHibernator module. And no, i couldn't come up with a better name. Long-time readers should know by now that i absolutely suck at coming up with good names so that's why we ended up with the NHibernator module.

The NHibernator module does 2 things: it offers a method that you need to use when initializing your application so we can create the proxy classes based on NHibernate's metadata, and it also modifies the accessor methods and adds some new methods whenever it is mixed in to another class. I'm going to show the code of the NHibernator module in multiple steps to hopefully keep everything as clear as possible. First of all, i'm gonna show the declaration of a constant and a simple helper method that we're going to need:

  TYPE_KEY_NAME = "$type$"

  def self.each_writeable_accessor_of(klass, &block)
    setters = klass.public_instance_methods(true).select { |name| name =~ /\w=$/ }
    setters.each { |setter| yield setter }
  end  

The TYPE_KEY_NAME constant contains the string that NHibernate uses as the key in its dictionaries for the value which returns the current entity's type name. And the each_writeable_accessor_of method executes the given block for each writeable acessor that a class contains.

And this is how we initialize everything:

  def self.initialize(session_factory)
    all_class_metadata = session_factory.get_all_class_metadata
    
    all_class_metadata.keys.each do |key|
      metadata = all_class_metadata[key]
      realclass = Object::const_get(key)
      realclass.send :include, NHibernator
      create_proxy_class_for realclass, metadata.identifier_property_name
    end
  end
  
  def self.create_proxy_class_for(klass, identifier_name)
    proxyclass = Class.new(klass)
    Object::const_set "#{klass.name}Proxy", proxyclass
    
    proxyclass.class_eval do
      define_method identifier_name do
        @id
      end
      
      def hydrate_from(hashtable, id)
        @nhibernate_values = hashtable
        @id = id
      end
    end
    
    each_writeable_accessor_of(klass) do |setter|
      proxyclass.class_eval do
        define_method setter do |value|
          # execute the getter to force NH's lazy proxymap to fetch the data
          send setter.to_s.chop
          super value
        end
      end
    end
  end

The initialize class method takes an NHibernate ISessionFactory instance and retrieves each mapped entity with the information that we need about it. Each mapped entity's class is sent the include message with the NHibernator module as a parameter. This basically mixes in the functionality of the NHibernator module into each entity's class. I'll discuss this in the next part of the post. After we've mixed the module into the entity classes, we call the create_proxy_class_for method for each class. As you can see, creating the proxy classes is very easy stuff. Any proxy class that we create inherits from the class of the entity, and overrides the accessor method to retrieve the identifier value so that it immediately returns the identifier value. If we would've kept the default implementation, it would access the dictionary that we got from NHibernate, which would cause a select statement for this proxy to be issued, which we obviously don't want. Again, this is a work in progress and one limitation that this current proxy implementation has is that you'll get a reference to a dictionary instead of an entity when you access a reference-property of a proxy. That too will be easy to fix

Next up, we need to cover what happens when the NHibernator module is mixed into an entity class. Ruby has a great hook method for that, which is this:

  def self.include(base)
    # everything you do within this method will be executed whenever
    # this module is included in a class... the base parameter is
    # the class that included the module
    
    # ...
  end

I'm doing quite a bit within that method and i want to cover each item in detail. So, the next couple of pieces of code are all part of the self.include(base) method implementation. The first thing we do when this module gets included in a class is this:

    each_writeable_accessor_of(base) do |setter|
      getter = setter.to_s.chop
      
      base.class_eval do
        undef_method getter
        undef_method setter
        
        define_method getter do
          return nil if @nhibernate_values.nil?
          value = @nhibernate_values[getter.to_clr_string]
          return value unless value.is_a? System::Collections::IEnumerable
          # TODO: cache the WrappedList instance
          WrappedList.new(value)
        end
        
        define_method setter do |value|
          @nhibernate_values = System::Collections::Hashtable.new if @nhibernate_values.nil?
          @nhibernate_values[setter.to_s.chop.to_clr_string] = value
        end
      end
    end

This is pretty simple, we're just getting rid of all of the original accessor methods and replacing them with our own implementations that use the dictionary we get from NHibernate as the backing store. Note that i will discuss the WrappedList class that you see in those getters soon. The setter methods will also instantiate a new Hashtable if we don't already have a dictionary. This is necessary for transient instances since NHibernate will treat them as IDictionary instances when we pass them to the session. Speaking of which, this is the next thing we do:

    base.send :include, System::Collections::IDictionary

This single line enables any piece of .NET code to cast our instances to an IDictionary reference. Note that we haven't even implemented any of the IDictionary interface's methods yet. We don't need to implement all of them anyway, just the ones that we know will be used.

Finally, we add all of the following methods to each class that included this module:

    base.class_eval do
      def nhibernate_values
        @nhibernate_values
      end

      def hydrate_from(hashtable)
        @nhibernate_values = hashtable
        referenced_entities = Hash.new

        hashtable.keys.each do |key|
          value = hashtable[key.to_clr_string]
                    
          if value.is_a? System::Collections::IDictionary
            if value.is_a? System::Collections::Hashtable
              referenced_entity = ObjectFactory.create_from_nhibernate_hash(value)
            else
              type = value.hibernate_lazy_initializer.entity_name
              id = value.hibernate_lazy_initializer.identifier
              referenced_entity = ObjectFactory.create_proxy_from_nhibernate_hash(value, type, id)
            end
          
            referenced_entities[key] = referenced_entity
          end
        end

        referenced_entities.keys.each { |key| send "#{key}=", referenced_entities[key] }
      end
      
      def Equals(other)
        self == other
      end

      def GetHashCode
        hash
      end
            
      def ==(other)
        return false if other.nil?
        return @nhibernate_values.Equals(other) if other.is_a? System::Collections::IDictionary
        return false unless other.respond_to? :nhibernate_values
        other.nhibernate_values.Equals(@nhibernate_values)        
      end
            
      def hash
        @nhibernate_values.GetHashCode()
      end
                                                
      def [](key)
        self.send key
      end 

      def []=(key, value)
        self.send "#{key}=", value
      end      
    end

I think that code speaks for itself, except for the Equals and GetHashCode methods... those are just there because i had some issues with IronRuby mapping calls to Equals or GetHashCode to their corresponding ruby alternatives (== and hash). I eventually upgraded to the latest IronRuby revision from GitHub, because i didn't get correct results with the IronRuby 1.1 alpha 1 to get the equality checks working correctly.

Finally, i needed the following 2 helper classes to make the albums bag work correctly:

class WrappedList
  include System::Collections::IList
  
  def initialize(list)
    @list = list  
  end
  
  def each(&block)
    @list.each do |item|
      if item.respond_to? :nhibernate_values
        yield item
      else
        yield ObjectFactory.create_from_nhibernate_hash(item)
      end
    end
  end

  def GetEnumerator
    WrappedListEnumerator.new(self)
  end

  def add(item)
    @list.add item
  end
  
  def clear
    @list.clear
  end
  
  def contains(item)
    @list.contains item
  end
  
  def count
    @list.count
  end
  
  def remove(item)
    original_count = count
    if item.respond_to? :nhibernate_values
      @list.remove item.nhibernate_values
    else
      @list.remove item
    end
    original_count != count
  end
  
  def is_read_only
    @list.is_read_only
  end
  
  def index_of(item)
    @list.index_of item
  end
  
  def insert(index, item)
    @list.insert index, item
  end
  
  def remove_at(index)
    @list.remove_at index
  end
  
  def [](index)
    item = @list[index]
    return item if item.respond_to? :nhibernate_values
    ObjectFactory.create_from_nhibernate_hash(item)
  end
  
  def []=(index, item)
    @list[index] = item
  end
  
  def Equals(other)
    self == other
  end

  def GetHashCode
    hash
  end
            
  def ==(other)
    return false if other.nil?
    @list.Equals(other)
  end
        
  def hash
     GetHashCode
  end
end

class WrappedListEnumerator
  include System::Collections::IEnumerator
  
  def initialize(wrappedlist)
    @wrappedlist = wrappedlist
    reset
  end
  
  def reset
    @current_index = -1
  end
  
  def current
    @wrappedlist[@current_index]
  end
  
  def move_next
    @current_index += 1
    return false if @current_index >= @wrappedlist.count
    true
  end
end

And that's all there is to it. This is probably the longest blog post i've ever written, but the amount of code involved in getting this working really isn't that much. Granted, there are still limitations to this approach so some stuff will need to be added to it. I'm also not saying that this is actually a great idea or that you should start doing this from now on, but well, at least this is possible now

    using (var session = sessionFactory.OpenSession())
    {
        var artist = ruby.ObjectFactory.CreateArtist();
        artist.Name = "some name";
        session.Save("Artist", artist);
        session.Flush();
        // and this actually prints out the id of the artist (in this case, it's defined as an identity in sql server)
        Console.WriteLine(artist.ArtistId());
    }

and

    using (var session = sessionFactory.OpenSession())
    {
        var albumId = 1;
        var artistId = 1;

        var album = ruby.ObjectFactory.create_from_nhibernate_hash(session.Get("Album", albumId));
        // the following line does NOT issue a select statement
        Console.WriteLine(album.Artist().ArtistId());
        // but this one obviously will trigger the lazy loading of the Artist instance
        Console.WriteLine(album.Artist().Name());

        var realArtist = ruby.ObjectFactory.create_from_nhibernate_hash(session.Get("Artist", artistId));

        album.Title = album.Title() + " 2";
        realArtist.Name = realArtist.Name() + " 2";

        if (album.Artist() == realArtist && album.Artist().Name() == realArtist.Name())
        {
            // this actually persists the changes
            session.Flush();
        }
        else
        {
            throw new InvalidOperationException("The universe should collapse");
        }
    }

I can't get property syntax working properly (as in: without requiring the parentheses) when accessing mapped properties due to an issue with IronRuby that needs to be fixed first, but other than that i'm pretty happy with how this works

Full details will be posted once i've taken care of a few more things

Suppose i have a screen where i need to display entries based on the following DTO class:

    public class AuthorizationDto
    {
        public long Id { get; set; }
        public Guid ApplicationId { get; set; }
        public string ApplicationName { get; set; }
        public Guid? UserGroupId { get; set; }
        public string UserGroupName { get; set; }
        public Guid? UserId { get; set; }
        public string Username { get; set; }
        public Guid PermissionId { get; set; }
        public string PermissionName { get; set; }
        public string PermissionDescription { get; set; }
    }

This DTO basically contains data from 4 entities: Application, UserGroup, User and Permission. I could easily do something like this with NHibernate:

            var items = Session.CreateCriteria<Authorization>()
                .CreateAlias("Application", "a", JoinType.InnerJoin)
                .CreateAlias("User", "u", JoinType.LeftOuterJoin)
                .CreateAlias("UserGroup", "g", JoinType.LeftOuterJoin)
                .CreateAlias("Permission", "p", JoinType.InnerJoin)
                .Future<Authorization>();

            var dtos = new AuthorizationDtoMapper().ToDtos(items);

As you can see, that's very easy to do. Unfortunately, this code really does a lot of stuff that you might not realize. For starters, it retrieves all of the Authorization instances with its related Application, User, UserGroup and Permission instances. It also fetches those entities in their entirety, which means it's retrieving all of their properties while i only need their Id and Name properties really. And finally, NHibernate will set up all of the things that enable its magic for all of these entity instances. That takes a few more CPU cycles and uses more memory than you truly need for the scenario of fetching entities merely to return DTO's. This extra cost obviously becomes worse depending on the size of the resultset that you're fetching.

A better way to do this, is to simply let NHibernate fetch only the data (columns) that you need, and to let it populate the DTO's itself. You can easily do this using projections and the AliasToBeanResultTransformer class. The code would look like this:

            var dtos = Session.CreateCriteria<Authorization>()
                .CreateAlias("Application", "a", JoinType.InnerJoin)
                .CreateAlias("User", "u", JoinType.LeftOuterJoin)
                .CreateAlias("UserGroup", "g", JoinType.LeftOuterJoin)
                .CreateAlias("Permission", "p", JoinType.InnerJoin)
                .SetProjection(Projections.ProjectionList()
                    .Add(Projections.Id(), "Id")
                    .Add(Projections.Property("a.Id"), "ApplicationId")
                    .Add(Projections.Property("a.Name"), "ApplicationName")
                    .Add(Projections.Property("u.Id"), "UserId")
                    .Add(Projections.Property("u.UserName"), "Username")
                    .Add(Projections.Property("g.Id"), "UserGroupId")
                    .Add(Projections.Property("g.Name"), "UserGroupName")
                    .Add(Projections.Property("p.Id"), "PermissionId")
                    .Add(Projections.Property("p.Name"), "PermissionName")
                    .Add(Projections.Property("p.Description"), "PermissionDescription"))
                .SetResultTransformer(new AliasToBeanResultTransformer(typeof(AuthorizationDto)))
                .Future<AuthorizationDto>();

Granted, you need to write a bit more code. But that code will do far less than the first version.

System.InvalidOperationException: Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.

We’ve been using NHibernate in almost all of our projects for about 2 years now and we’ve never had this issue before.  The thing is though, we never used System.Transactions’ TransactionScope class before and always used NHibernate’s transactions directly.  In this project, we’re using TransactionScope for the first time (mostly because we need distributed transactions occasionally) so i immediately suspected that we were either doing something wrong with it, or that there was a bug somewhere.

After a while i managed to reproduce the problem with the following simple test fixture:

If you assign counter a value that is greater than your ‘Max Pool Size’ value of your connection string, then you will get the following exception once you’re going through the loop for the ‘Max Pool Size’ + 1 time:

System.InvalidOperationException : Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.

Bingo!

In normal situations, you would obviously call the Complete method of the TransactionScope instance before it is disposed to commit the current database transaction.  But in a situation where you can’t call the Complete method (as in: when an exception has occurred and you want to rollback the transaction), your database connection will actually leak until you’ve used up all of the connections in your connection pool. 

So the question is: How can we use a TransactionScope with NHibernate without leaking connections when we throw an exception (which should result in an automatic rollback of the current transaction)? 

I was always under the impression that merely opening an NHibernate session within a transaction scope was actually OK and that the session’s connection would make use of the current ambient transaction (the one created by the outer TransactionScope).  Pretty much every session-related action you perform in NHibernate results in calling the CheckAndUpdateSessionStatus method of the SessionImpl class, which in turn calls the EnlistInAmbientTransactionIfNeeded method.  That (as you can probably guess) will automatically enlist the current NHibernate session in the ambient transaction, which is the one that was created by the TransactionScope.  So, as i understand it, it should indeed be sufficient to open an NHibernate session within a TransactionScope to have every action performed by that session being enlisted in the current ambient transaction.   And it actually behaves as transactional as you’d expect it to be.  Your transaction is properly committed if you call the Complete method of the TransactionScope and it is indeed rolled back if you do not call the Complete method.  The only problem (and it’s a major one obviously) is that you’re connection will leak when the transaction is rolled back. 

Interestingly enough, if we change the test code to this:

Then the problem goes away.  Transactions are correctly rolled back, and none of the connections leak anymore.  It’s too bad that we still need to use NHibernate’s transactions only for the sake of being able to rollback in case of failure without leaking the connection, because again, when you’re not using an NHibernate transaction but are within a TransactionScope, your Session’s connection will indeed be enlisted in the transaction being governed by the TransactionScope.  So there certainly appears to be some kind of bug in NHibernate when it comes to cleaning up the connection of a session that has been enlisted in a TransactionScope’s transaction which is rolled back instead of committed.

Now, since i frequently see people on the intarweb showing examples of using an NHibernate session together with a TransactionScope yet without using an NHibernate transaction, i’d might as well post the way that i believe is the safest, and that shouldn’t leak any connections.

If you need to rollback, simply throw an exception within the using block of the NHibernate transaction (before the transaction.Commit() call obviously) and everything takes care of itself.

Now the thing is, i’d either expect DTC to fail outright or to just work.  But it shouldn’t fail in one situation, and work in another.  On my machine, it failed in the following situation (which i’ll further refer to as Situation A):

1. open a transaction scope
2. open an nhibernate session
3. hit the db
4. publish a message through nservicebus
5. close the nhibernate session
6. complete and close the transaction scope

Step 4 and 5 could be switched around but it didn’t make a difference.  In Situation A, i always got a TransactionManagerCommunicationException with the following message:

Network access for Distributed Transaction Manager (MSDTC) has been disabled. Please enable DTC for network access in the security configuration for MSDTC using the Component Services Administrative tool.

Everyone who’s worked with MSDTC before probably knows that exception since it usually takes some fiddling with the settings to make things work.  The thing is, i was pretty sure that my settings, as well as the ones on the database server were correct.  Unfortunately, DTCPing didn’t confirm that since that too failed.

However, i also tried the following sequence of events (Situation B):

1. open a transaction scope
2. open an nhibernate session
3. publish a message
4. hit the db
5. close the nhibernate session
6. complete and close the transaction scope

And guess what.  That actually worked.  With full DTC transaction semantics.  The DTC statistics on the server confirmed that it was indeed using a DTC transaction, and if i made the code fail with an exception both the database action and the published message were correctly rolled back.

So the question is: why on earth does it only work when i publish a message before i hit the db?

During my investigation i noticed that in Situation A, the internal transaction that the transaction scope was using was a SqlDelegatedTransaction.  Which, if i’m not mistaken is an LTM transaction.  When trying to send a message to a message queue, the transaction manager tries to promote the current transaction to an OletxCommittableTransaction since the OleTx transaction protocol is required when using MSMQ (it doesn’t support LTM transactions).  For some reason, promoting the SqlDelegatedTransaction to a full DTC (OleTx) transaction fails on my machine.

In Situation B, the internal transaction is promoted to an OletxCommittableTransaction as soon as you try to send the message to a message queue.  Once it’s time to hit the DB, NHibernate nicely works together with the OletxCommittableTransaction and everything just works.

Now, i have no idea on earth why promotion of a SqlDelegatedTransaction fails, but after a long number of attempts and experiments to get it working correctly, i sorta gave up and figured i’d have to resort to a hack.  What i basically needed was for the transaction scope’s internal transaction to automatically be promoted to an OletxCommittableTransaction before i’d hit the database and without having to publish a dummy message at the beginning of the transaction.

I found one way of doing this which, while being a huge hack, is still relatively clean i think.  I wrote the following class:

Then, right after opening the transaction scope and before doing anything else, i do this:

This basically tells the System.Transactions infrastructure that we’re adding our own Resource Manager to the current transaction.  And because it’s a durable Resource Manager, it now automatically promotes the internal transaction to an OletxCommittableTransaction and everything just works.  While our Resource Manager participates in the 2-phase-commit process, it doesn’t actually do anything.  It’s sole purpose is to force the creation of an OletxCommittableTransaction.

Like i said, it’s a hack but it’s still relatively clean.  I still have no idea why i needed to resort to this hack though… If anyone can shed some light on this, i’d highly appreciate it

Also, if you ever want to learn more about transactions in .NET or distributed transactions in particular, you really need to check out this article.  Without it, i probably wouldn’t have figured out what to do

First of all, the idea is to make sure that managing the NHibernate session (creating it, starting a transaction, committing or rolling back the transaction and closing the session) is taken care of automatically so you no longer have to worry about it.  I also want to avoid passing the NHibernate session around all the time.  This means that it will be created automatically when a request is sent to your service layer and stored in some place that will keep the instance alive during the handling of the service layer request.  Every class that needs a reference to the current session (ideally only classes that deal purely with data access) will be able to retrieve it very easily, all in a thread-safe manner that can never be influenced by other concurrent requests.

First of all, you need something to wrap NHibernate’s ISessionFactory.  I use the ISessionProvider for that:

In my case, i configure the IOC container to pass the name of the assembly that contains the mappings to the constructor of the SessionProvider class.  If you’re using this code directly in your application, you could just as well hardcode the name of the assembly here.

You’ll also need something that allows you to store and retrieve the NHibernate session for the duration of the current request.  I use the IActiveSessionManager for that:

This class will store the ISession instance in the current request state (definitely click on that link if you don’t know IRequestState yet).

Now we can create our own Unit Of Work.  This is not a pure Unit Of Work because it doesn’t do any change tracking or anything like that, but it does take care of creating an NHibernate session (which does do change tracking and anything that a real Unit Of Work should do) and cleaning it up when the Unit Of Work is completed.  Here’s my implementation:

The idea is very simple.  When the Unit Of Work is created, it asks the IActiveSessionManager if there is already an active session available.  If not, it will create a new session through the ISessionProvider, and store it as the active session through the IActiveSessionManager.  In the old implementation, the Unit Of Work would automatically create a new session in the constructor, but this obviously causes problems if you want to reuse a certain request handler from another request handler if they both depend on a IUnitOfWork instance.   The IUnitOfWork interface doesn’t expose a lot of functionality but it’s all you need to manage your session in your service layer.  It gives you the ability to create a transaction, clear the session and flush the session.  When the IUnitOfWork is disposed, it will clean up the session and instruct the IActiveSessionManager to get rid of the session for this request. 

Once you have this, you have all you need to prepare your service layer to take care of NHibernate session management automatically.  I’m going to base the following service layer code example on Agatha (just because i think it’s the easiest way to implement a service layer ) but you can do exactly the same in your service layer.  The important part is that you should configure your IOC container to inject a new instance of IUnitOfWork into the class that handles your service request.  When the container injects the new instance, the NHibernate session will be created and stored in the IActiveSessionManager so there’s no more reason why you would have to do this yourself.

Now, i use the following class as the base class for all my request handlers that need NHibernate support:

(Note: the real implementation contains a bit more logging but other than that this is the real thing)

If you don’t understand the whole request handling concept, please check out the first 3 posts in this series.  Regardless of whether you’re using Agatha, your own Request/Response Service Layer or a classic (dare i say old-school?) service layer, the idea should be the same.  Make sure this code is centralized in one place so you don’t have to repeat yourself all over your service layer code.   Btw, in this case the IUnitOfWork instance is injected by the IOC container through Setter Injection instead of Constructor Injection.  I’ve already discussed the reasons on why i prefer Setter Injection in this case here.

Now, you’re going to have some classes that will need to use an ISession instance to perform their tasks.  I always create Repository classes for that, but the following approach would be similar for any other type of class which needs an ISession.   Call them Data Access Objects, Data Access Classes or Sloppy Joes for all i care.   Whatever you call these classes, they need a dependency on the IActiveSessionManager.   Simply declare the IActiveSessionManager to be a dependency of your Sloppy Joe, i mean, Repository or DAO or whatever, like this:

Now you can write request handlers like this:

Obviously, this is a simple example but it works just as well for complex request handlers.  Your NHibernate session is created and cleaned up automatically, without you having to write that code every single time. Each request handler will run in a transaction, and it will be committed or rolled back automatically without you having to do anything for it.  And you only need to access the ISession instance in your Sloppy Joes.

Also keep in mind that you can also use the the ISessionProvider, IActiveSessionManager and IUnitOfWork in a purely web-based scenario as well if you want to.

Simply inherit from this class, implement the BuildEntity, ModifyEntity, AssertAreEqual and AssertValidId methods and that’s it.  Those methods are usually pretty simple.  In BuildEntity you just create an unpersisted entity and assign values to the properties, in ModifyEntity you modify the properties, and in AssertAreEqual you compare the properties of both instances.  In AssertValidId, you make sure that the ID value is ok (depending on your identifier strategy).

This is good for regular CRUD operations, though we typically add extra tests when we want to test cascades or one-to-many associations mapped with inverse=”true”.

Grant Palin recently asked me for an in-depth article on TDD’ing an NHibernate application. While this post won’t be very in-depth, it might be helpful already.  There are basically two approaches that i’ve seen used with good results, though there are obviously more approaches that you can use.  I’m going to limit the scope of this post to the following two approaches though, and i’ll also discuss exactly what we test.

Creating a new database for each test (or testfixture)

This approach creates the database at the beginning of each test (or testfixture), runs the test (or tests in the fixture), and then destroys the database after the test (or testfixture) completed.  The easiest way to do this is to create a base test class that all of you data access test class should inherit from.  Here’s a simple example:

This class will create the database from scratch once for each TestFixture, which means that each test in the fixture will use the same database.  It also destroys the database at the end of the fixture.  It creates the database based on your mappings, and as you can see, you really don’t have to do a lot for this.  If you want the database to be recreated and dropped for each test, then you obviously need to move the code in the TestFixtureSetup and TestFixtureTearDown methods to your regular SetUp and TearDown methods.  If you go that route, i’d advise you to include empty template methods before and after the setup and teardown so you can plug in some extra code before and after these operations in your derived test classes.

The biggest benefit of this approach is that you don’t have any possibly present state in the database that can influence your tests.  The downside is that you can’t rely on certain data (eg reference data) to be present and you have to recreate it whenever you need it.   You can also use multiple transactions in your tests, though you are also responsible for cleaning any data that is left in the database at the end of each test.  You also need to guarantee that this always happens because any data that is left by one test might influence another one.   Also, if you leave data in the database, that might lead to problems when dropping the database, so you really need to be careful with this.

Another problem with this example is that there is no automatic way to push the ISession instance to your data access components.  That could easily be added though, depending on how your data access components retrieve a reference to a valid ISession.

Tests that automatically roll back their transactions

This is the approach that we always use at work.  These tests require your database to be set up in a valid manner before your tests begin.  Each test uses one transaction, which is automatically rolled back at the end of the test to prevent the possibility of any test data remaining in the database.   With this way of testing, it’s also possible to provide some kind of ‘known state’ in the database (eg reference data) that you can use from within your code.

Here’s the NHibernateTest class that our NHibernate test classes all inherit from:

Now, this example uses our UnitOfWork and ActiveSessionManager classes (read this if you haven’t seen those yet) to make sure that our data access components can access the current ISession instance.  Each test has a valid ISession present, which has already created a transaction and we can create/modify/delete data, run our queries, modify some stuff again, run our queries again and perform our assertions, all in the same transaction.  After the test is completed, the transaction is never committed (and thus, automatically rolled back) so none of that data ever remains in the database.

What Exactly Do We Test?

Well, we test everything basically.  We test all of our CRUD operations (again, with a simple base class which only requires you to implement the BuildEntity, ModifyEntity and AssertEqual methods and does all of the operations and checks automatically) for each entity.  That’s right, for each entity.  The extra work that this requires really doesn’t take a lot of time and it lets us know for a fact that our mappings are valid.

We also test every custom query that we write, always using the following approach: create some test data, flush the session, perform your query and verify that the expected data has indeed been returned by the query, and also that data that shouldn’t have been returned isn’t there.

And that’s pretty much it.  We mock the data layer in all of our other tests, so our CRUD and query tests are the only ones that actually use NHibernate and the database.  But CRUD actions and queries are tested very extensively.

NHibernate allows a private default constructor for Value Objects, but for Entities you will need a default public or protected constructor as private is not sufficient.

I got the following comment from someone:

I too am trying to determine how well NHibernate lives up to the promise of persistence ignorance. I can definitely live with unnecessary private constructors, but I’m dubious about adding protected constructors just to support an ORM.At any rate, I was surprised by the sentence I quoted, because I didn’t realize there were any circumstances in which NHibernate required protected default constructors.

Once again, the answer is related to the dynamic proxies that NHibernate uses. Value Objects will never be proxied by NHibernate, so NHibernate only needs a private default constructor to create the instances. If an entity is eligible for lazy loading however, then NHibernate will create a type which inherits from your entity (this is described in depth here and here). Which means that we really need either a public or protected constructor in entity classes that are eligible for lazy loading. Consider the following class:

    public class SomeEntity
    {
        public SomeEntity(string someRequiredValue)
        {
        }
 
        private SomeEntity()
        {
        }
    }

If we try to create the following derived class:

    public class SomeEntityProxy : SomeEntity
    {
    }

We get the following compiler error:

Error 1 'ConsoleApplication1.SomeEntity.SomeEntity()' is inaccessible due to its protection level

It's a silly example, but it does show why entity types need at least a public or a protected default constructor and why a private one isn't sufficient.

Once again, this is the code example:

Instead of making everything virtual, only properties that are eligible for lazy-loading have been made virtual. Now, the line of code that is problematic is obviously the one where the DiscountPercentage of the customer backing field is accessed. I will address using the field instead of the property later on in this post so bear with me for now.

There are 2 situations in which this code will fail badly. The first situation is when you're dealing with a proxy of an Order. If you have an uninitialized proxy of Order, and you call the non-virtual CreateOrderLine method then you will get a NullReferenceException because the proxy can't intercept the call to CreateOrderLine, and because it also can't intercept accessing the customer field, which will be null at that time. This problem was correctly spotted by one of the people who left a comment.

The other problem is far worse, IMO. Suppose you have a genuine instance of an Order object, but its reference properties haven't been loaded yet and are uninitialized proxies. If there is no requirement for every public member of a proxy-able type to be virtual, then we can pretty much assume that the DiscountPercentage of the Customer class is also non-virtual. Which means that with this code, we have no possible way of intercepting the call to the Customer's proxy's DiscountPercentage property. Unfortunately, DiscountPercentage will have its default value of 0, so you won't get an exception... instead, the customer gets no discount even though its record in the database might have a discount set.

The possibility of running into one of these problems due to usage of an ORM and depending on how an object is loaded is simply unacceptable. Some people commented on the usage of the customer backing field instead of the Customer property with a "then simply don't do that" response. That's not an acceptable solution to this problem, it's a lame workaround at best. There are plenty of reasons why people would use the backing field in their code instead of the property and if they run into this problem, they definitely will blame the ORM. And rightfully so, i might add.