The Freak Parade

NHibernate is a rich and robust open source Object Relational Mapping (ORM) tool. See my preambles to this post for a brief overview of NHibernate and some architectural prerequisites.

NHibernate is currently in version 2.0, which is being billed as a complete (or mostly complete) port of Hibernate version 3.2. That means that in addition to these resources, books and materials relating to Hibernate 3.2 should also apply in large part to NHibernate 2.0.

The Official Documentation & Project Resources

NHForge
Strange name, but promising new NHibernate community website. It is a little lightly populated at the very moment, but this looks like it will be a one stop shop for downloading NHibernate core libraries and the many satellite projects, documentation, etc.

NHibernate Wiki
This is a new resource that was made available along with the release version of NHibernate. I believe the formal NHibernate 2.0 docs live there now.

NHibernate Deep Grok
This funkily-named resource is an app-engine / google-custom-search powered search engine focused entirely on NHibernate. If you need to do an Internet search for NHibernate related material, this is a very good place to start.

NHibernate 1.2 Documentation
A complete reference for NHibernate 1.2, the precursor to 2.0 and the latest official release.

NHibernate Users Forum & E-Mail Discussion List
A Google group / mailing list for asking and responding to NHibernate questions. Invaluable resource. If you haven’t participated in an e-mail list (which is like an e-mail based discussion forum) you should try it, you learn a lot and it is fun.

Source Code On SourceForge
This is the SourceForge home page where you can download the latest releases or, if you have the constitution for it, check out the latest version from the trunk.

The Project Home Page
The official home of the project at hibernate.org.

NH Contrib Project Project Page
The contrib project has some nice components that aren’t part of the core, but are hugely useful anyway. These include LINQ to NHibernate, a validation framework, a session context framework (Burrow) and other good things.

Getting Started

The REAL starting place is here. But if you’ve digested those materials and are ready to start writing some code, check out these resources:

Learn How to use NHibernate with the Summer of NHibernate Screencast
This is a post by Scott Hanselman pointing to the Summer of NHibernate Screencast series. I linked to this post instead of directly to the screencast page because Scott compiles some other learning materials in the post, and provides commentary.

Your first NHibernate based application
Setting up NHibernate 2.0
Using NHibernate as an ORM Solution for .NET

Crucial Community Resources

NHibernate FAQ
This is an NHibernate blog, and a fantastic one at that. A good portion of the links on this page are from that blog - if you are going to develop with NHibernate, you will want to not only subscribe to this blog but take the time to read the archives.

Ayende’s NHibernate Category
This is just a link to the RSS feed for the NHibernate category on Ayende Rahien’s blog (a contributor to NH). Lots of great stuff here.

NHibernate Resharper Plugin
If you use Resharper, this plugin will validate your NHibernate xml mappings.

Best Practices & Reference Applications

NHibernate Best Practices with ASP.NET, 1.2nd Ed. - Billy McCafferty
This is a code project article about using NHibernate and a reference app using DDD and an ASP.NET MVP pattern.

S#arp Architecture
This is a CodePlex project providing a reference app and an article included as documentation that provides a reference architecture for using ASP.NET MVC, NHibernate and Castle Windsor. A discussion list for this forum is here.

Foundations of Programming Learning Application
This is an application designed to be a reference app for doing DDD. This also uses ASP.NET MVC and NHibernate.

Code Store Reference App
Another reference app utilizing NHibernate. Also uses Castle Windsor and Tree Surgeon.

How to review a NHibernate application
Ayende’s list of best practices when designing a system using NHibernate.

NHibernate 2.0 Announcements & New Features

NHibernate 2.0 Alpha is out!
NHibernate 2.0 Announcement from InfoQ

Rhino Commons

Rhino Commons is part of Rhino Tools, and must be downloaded from the trunk of that project. Rhino Commons is several things ("just a utility library" isn’t one of them) which you can discover for yourself, but one of the things it is is a dash of infrastructure that really smoothes out the wrinkles when working with NHibernate. I can’t tell you how many posts are on the web relating to setting up a UnitOfWork object and managing sessions, or implementing a generic Repository to abstract working with NHibernate sessions. Rhino Commons provides very usable implementations of these concepts. Rhino Tools, by the way, contains a few sample/reference apps for using Rhino Commons as well as NHibernate. Check out Hibernating Forums, for example. Most of these links are about using Rhino Commons with an ASP.NET MVC app. Not sure why that is, but it works for me.

Beginning System.Web.MVC with Rhino Tools, Castle Active Record and Nhibernate, Pt 2, Pt3
RhinoCommons, NHibernate and ASP.NET MVC Part 1, Pt2, Pt3, Pt4, Pt5
NHibernate and the Unit of Work Pattern <–Not strictly about Rhino Commons, but explains the concepts behind it
Adaptive Domain Models with Rhino Commons
AOP With Windsor: Adding Caching to IRepository based on T’s attributes 

Note: In the NHibernate Contrib project is a tool called NHibernate Burrow - it feels to me like the intention of this project and the intention of the session management in Rhino Commons may be the same - but I haven’t dug any further than that. Anyone wish to clarify in the comments?

Misc. Concepts

Implementing Frictionless Soft Deletes in NHibernate

Soft Delete in NH

Mapping & Collections

Testing Mappings & Fluid Interface for Mapping 
The above link explores a mechanism to do NHibernate mappings in code instead of XML, giving you all kinds of benefits.

[UPDATE] Apparently a full blown open source project has been established to build a fluent interface for doing NHibernate mappings, which is exciting. The project source code repository is here, the Google group / users form is here and a blog post introducing the library and providing a quick start is here.

Mapping Collections in NHibernate (Part 1)
Custom Collections with NHibernate, Part I: Who Cares?
Custom Collections with NHibernate, Part II: The Basics
Custom Collections with NHibernate, Part III: Refactored

Generating / Synchronizing the Database Schema from a NHibernate Model

Create and Update Database Schema

Querying & LINQ to NHibernate
Linq to NHibernate in 10 Minutes
Linq to NHibernate
Kyle Baley - Trying out Linq to NHibernate
My NHibernate 2.0 Supa’ Layer (something new from Rob Eisenberg)

NHibernate Query Generator
[Update (see comments)] NHibernate Query Generator will create strongly typed queries when working with NHibernate using .NET 2.0. LINQ to NHibernate supercedes the NHibernate Query Generator, so if you are working in .NET 3.5, prefer to use LINQ for your strongly typed queries. For .NET 2.0 apps, however, NHibernate Query Generator is a strong alternative.

Lazy Loading & Eager Loading

Lazy Loading - Eager Loading
Eager loading aggregate with many child collections

Entity Joins & Relationships

When to use many-to-one(s) vs. many-to-many with NHibernate
Performing Join Queries with NHibernate CreateAlias

Misc

Audit Options with NH
Integrating Castle Windsor and NHibernate with WCF - Throwing the WCF facility and some Rhino Tools in the mix
Book review: NHibernate in Action
Using Entity-Assigned ID’s

NHibernate is an Object Relational Mapper (ORM) tool - which is to say it takes your living, squirming objects from a running application and stuffs them into some kind of database. It also will be happy dig into the database, grab some sleeping object, shake it awake and toss it back into your running application when you need it.

As a standalone tool, this can be very useful. It saves you writing a metric ton of SQL, it saves you from having to type out a bunch of tedious boilerplate ADO.NET code to execute that SQL and then find something useful to do with the awkward, pointy data sets and data tables and data readers that are returned.

You can get a lot of mileage from just learning how to use NHibernate, replacing your existing data access code, and leaving it at that. Taking that approach, though, would be leaving a great deal of what NHibernate has to offer on the table. ORM’s such as NHibernate, very much like Inversion of Control containers, are components of a particular kind of loosely coupled, domain centric application design that is all the rage these days (though for very good reasons) called Domain Driven Design (DDD).

For the uninitiated, wholesome, mamma’s boy Microsoft developer picking up a tool like NHibernate or an Inversion of Control Container like Castle Windsor  can often be the first step towards experimenting with Domain Driven Design (championed by the ALT.NET community), introducing you to a different kind of crowd that does things in a different kind of way, much like smoking Marijuana is considered the "gateway drug" to other, "harder" drugs. In the same way that smoking a Marijuana cigarette while listening to your favorite Jazz records with some new friends on Saturday will often lead you to snorting lines of cocaine off of the floor of a public bathroom in a Tijuana brothel on Sunday, learning and using tools like NHibernate will often lead you towards learning a more maintainable, more flexible and generally more fun way of building your software systems.

In concert with Inversion of Control containers, NHibernate supports the concept of "Persistence Ignorance" (PI) - which more or less means that your domain objects have no idea where, how or even that they are being persisted. This dramatically reduces the coupling of your business logic to its infrastructure, which dramatically increases its maintainability, reusability and ultimately its life span. I’m no expert in this field, so I’ll leave it to the experts to do the teaching, but I do feel pretty strongly that before (or in parallel with) learning NHibernate, or any other ORM, it is important to also learn about the kind of architecture it was designed to serve. The resources below should be a very good start:

1. Foundations of Programming - a free e-book by Karl Seguine
This should really be called "An introduction to the ALT.NET approach to Domain Driven Design and Test Driven Development" - it is far more of an introduction to a particular style of building software(despite the "how memory works" chapter) that it is to the foundations of programming in general, but nevertheless it is a very easy to read, very humbly written and very useful introduction to writing modern enterprise software using .NET. If you’re already a grizzled ALT.NET warrior, well you aren’t reading this post, and you probably won’t get much out of this book, but for those of us that don’t fit into that category, I highly suggest reading this short, concise introductory text.

2. Domain Driven Design Quickly
This is a summary of Eric Evan’s seminal book on Domain Driven Design (which you should also read) in the form of a free e-book. This book will get you out of the starting gate. This is much longer than the Foundations of Programming e-book, so you may want to print it out on the old laser jet and take it home.

3. Onion Architecture Part 1, Part 2 and Part3
The name, perhaps, is rather silly, but Jeffrey Palermo does a very nice job of describing how an ideal DDD architecture should be constructed, and how application layers should communicate with one another in contrast to more traditional n-tier architecture.

4. Default Architecture: Layers
A less accessible but still useful post describing how Ayende Rahien (author of Rhino Mocks) approaches his application architecture.

5. NHibernate Best Practices with ASP.NET, 1.2^nd Ed.
Despite the title, in this article Billy McCafferty talks quite a bit about application architecture especially as it relates to ORM, Persistence Ignorance and NHibernate, and is definitely worth reading. He has an updated reference architecture which he calls S#arp Architecture, and it is available on Google Code, along with some documentation that contains a hidden gem of morbidly dark humor that is beautifully out of place with the style of the article. I’ll let you find it yourself, but the guide is a good read.

6. Object Relational Impedance Mismatch
This is a useful concept to understand before diving into using an ORM for the first time as well, as it is the Object Relational Impedance Mismatch that NHibernate or any other ORM exists to solve. (For a mild debate/discussion of this see this post and this one). In a nutshell, the "impedance" mismatch is the vast conceptual and structural difference between an object oriented domain model and a table-oriented, set-based relational database. Cramming OO objects into a relational database and the difficulties doing so are the OR Impedance mismatch. FYI, the term "Impedance Mismatch" comes from the EE world, where "impedance" is the resistance of a system to the flow of energy. If energy is to flow consistently from one system to an
other when two systems are connected together, then their "impedance" must be matched or bridged. I suppose in the case of a software system the "energy" is the representation of the state of the domain, and for that representation to flow consistently in between the boundary between an object graph and a relational data store, both with very different levels of resistance to the state representation (the object model having the far smaller impedance)  a mechanism is required to bridge or match the impedance of the two systems, and in the case of NHibernate that mechanism is the ORM toolset.

In the next post I’ll provide specific links to NHibernate resources that I’ve found to help actually learn the tool.

Why?
For the past several years we have been using a home grown ORM tool as part of a larger application framework. It works pretty well, but there are a few drawbacks:

• It’s home grown - unless we divert attention from building our business applications, it stays frozen in time. This is a drawback of every home grown tool, and why a community or third party library should always be considered when good ones are available.
• It’s tied to SQL Server. Getting it to run on another database platform would be quite a bit of work.
• No LINQ support, in fact, no query language of any kind. When we want custom queries, we put them in our model editor and generate new code. This get’s us a method on our DAL to execute the query, but that means there is this whole open-model-editor, make change, generate code, compile code and test cycle for every little query we may need.
• As an internal tool, it is rather poorly documented. Training new developers requires using in-house staff. No pointing to a list of links on the web and saying, “here, go learn this and we’ll get started”
• It means nothing when you put it on a resume

As we are embarking on a new set of projects, the time seems right to consider the possibility of moving to a mainstream ORM tool with a healthy community and plenty of learning material. I won’t go through the selection process, but we looked at some commercial tools and we looked at NHibernate, and while the commercial tools have some nice polish on them and comprehensive documentation, the community surrounding NHibernate is so vibrant (and so distinguished) that we’re strongly leaning in that direction.

NHibernate does lack some polish. It’s an engine that requires some build-out of infrastructure to make it comfortable to use, but much of that build out has been contributed by community members and where it hasn’t, the blogosphere has filled the gaps with any number of helpful walk-through’s and best practices posts. I’ll post links to the resources I’ve identified in a subsequent post.

Active Record
Perhaps the most prominent of these community contributed build-outs is the oh-so-famous ActiveRecord implementation that is part of the Castle Project. NHibernate, in its raw, unprocessed form, handles persisting Plain Old CLR Objects (POCO’s) to a persistence medium by way of XML mapping files which must be hand crafted. The mapping file contains which fields of a persistent object will be stored to the database, and can control every detail of the mapping between a field and a corresponding database column. The mappings also communicate to NHibernate how entities relate to one another, such as many-to-one, many-to-many, etc.

All this is very powerful, but perhaps not so much fun to manage (although many people prefer to do so manually). Active Record is a design pattern for object relational mapping that maintains one Class for each Table in a data store, more or less, and Castle Windsor provides an implementation of this pattern such that a combination of Convention over Configuration and .NET Attributes remove the need for creating and maintaining NHibernate mapping files. In fact, when you use Castle’s ActiveRecord, you may not know you’re using NHibernate at all as the whole experience is nicely abstracted. To make this happen it is understood when you use Active Record your objects will be saved to the database in a certain way, and you are OK with that, because it saves you many small decisions and many XML code edits.

Whether or not to use ActiveRecord is, I think, largely a matter of taste and your personal relationship with Convenience(Cost) vs Control, the yin and yang of the Build vs Buy decision. We haven’t settled on ActiveRecord yet, although we are pretty sure that if we don’t use ActiveRecord, we’ll be rolling our own code generator to maintain both NHibernate Mapping Files and the Database Schema, and possibly the Entity classes themselves, based on a metadata model. Maintaining a few trillion XML mapping files doesn’t sound like a lot of fun to me.

Next I’ll talk a little about architecture, and then drown you in NHibernate hyperlinks.

NHibernate Reference PDF