NHibernate
The object-relational mapper for .NET
In this post I'll introduce how to prepare a developer machine to use NHibernate as a ORM (Object Relational Modeling) tool.
This approach describes the minimal setup needed to use NHibernate when developing an application.
In this article the focus is on TDD (Test Driven Development) and we want to approach the topic by adhering to DDD (Domain Driven Design). Although NHibernate can also be used to generate the domain model by starting from an existing database schema I'll concentrate on the opposite direction and start with a domain model first and let NHibernate generate the database schema from the model (and the mapping meta data).
First you have to download NHibernate. Since NHibernate is an open source project anybody has free access to the (most current) binaries and/or source code. The source code is stored in a SVN repository (Subversion Source Control System) and can be found here. The most current source code is called the "trunk".
I expect you are working on a machine with one of the following operating systems
We use the brand new NHibernate 2.0 Alpha 1 version. This version of NHibernate can work either with .NET 2.0 or .NET 3.5. For the former version you should have at least Visual Studio 2005 Professional installed and for the latter you need at least VS 2008 Professional. Of course you can also work with the Express Edition but they have some serious limitations (e.g. you cannot use any Add-In with VS). Now if you have some money left I strongly recommend you install the ReSharper Add-In as your productivity tool. I promise you it'll boost your productivity by factors! This investment is worth every penny.
You can grab the latest NHibernate binaries here. At the time being this is the Alpha 1 release of the version2.0.0. Download the file "NHibernate-2.0.0.Alpha1-bin.zip". Extract the zip files to a folder where you will place all your Open Source Software (OSS). That is create a new folder, e.g. "m:\dev\OSS\NHibernate" and extract the binaries to this folder. The binaries are compiled against .NET 2.0. If you prefer to have binaries compiled agains .NET 3.5 you have to build NHibernate from the trunk as described in the next chapter. Otherwise you can skip the following chapter and move directly to the chapter "Prepare for TDD".
To download the source code you need a SVN client application installed on your developer machine. There exist various open source as well as commercial clients. One of the most known (open source) clients is TortoiseSVN and can be found here. TortoiseSVN integrates very nicely with Windows Explorer. Download and install it on your machine. Restart your machine after the installation.
Create a (sub-)directory OSS (Open Source Software; e.g. m:\dev\OSS). Create a subdirectory NHibernate within the OSS directory.
Right click on the NHibernate directory and choose the context menu "SVN checkout...". In the dialog box enter the url to the trunk as shown below. Double check the checkout directory and then press OK.
The SVN client will immediately start to download the NHibernate source code as well as the documentation. Depending on the speed of your Internet connection this may take some time to finish. You should see some thing like this
When the download is completed we can now compile NHibernate (remember: we have downloaded the source code and not the binaries!). Don't fear, this is an automated process. But wait, for this to work we need NAnt, another open source tool.
You can get the latest release of NAnt here. This time we download the binaries (and not the source code) since it is "only" a helper tool for now. At the time of this writing I recommend downloading the 0.86 Beta 1 release since this release is the first one that can compile .NET 3.5 projects.
Download and extract the NAnt binaries (nant-0.86-beta1-bin.zip) into a directory on your developer machine (e.g. m:\dev\OSS\NAnt).
Now it's definitively time to compile NHibernate. Open a console and go to the root directory of the NHibernate source (e.g. m:\dev\OSS\NHibernate\nhibernate). There you should find amongst others a file called default.build. This file contains the instructions for NAnt how to compile NHibernate. You can either compile NHibernate for .NET 3.5 (it's the default) or for .NET 2.0. In the console enter the following commands for the 2 scenarios (assuming you have NAnt installed in the same OSS folder as NHibernate)
The source code should now be compiled and after some time you should see some thing like this
It's important that the second last line states "BUILD SUCCEEDED".
After compiling the source code you should find a new sub-folder "build" in your NHibernate folder which contains all the binaries. Depending on the chosen scenario you will find the binaries in either a sub-folder "net-3.5" or "net-2.0". Didn't I tell you that it's easy...!
Are we ready now? Nope! Since we're proud fellows of the ALT.NET way we don't want just start coding. No, we do TDD. Doing so we need a test framework. There exist several well known frameworks (e.g. NUnit, MbUnit, XUnit, etc.). In our examples we either use NUnit or MbUnit. Let's start with NUnit since NHibernate uses it too for its own test (you can download it from here). Note: we don't have to download it, since we can use the binaries provided with NHibernate (the only files we actually need are nunit.framework.dll and nuni.core.dll).
Although this article doesn't explain these two topics you still should be prepared to develop in a team and to use continuous integration. Why do I mention this? Well, we should do some further configuration of our environment to be prepared for this situations. Since it's easy to do - why not do it NOW...
A solution at best should have no external dependencies (ok, .NET we don't count here). If it has, then these dependencies should become a part of the solution (setup). What does this mean for us? Well our projects will have external dependencies, NHibernate is one of them. Another one is NUnit and still another one the database we'll use. A possible solution for this scenario is to not rely on assemblies registered in the GAC or any other "common" or "programs" folders of the system. Instead create a directory called e.g. SharedLibs which will be part of your solution and copy all external assemblies into this folder. The solution then only references external assemblies from this folder (an exception are all the .NET assemblies). If you use a source control system (and you should!) then put this folder under version control too!
Create a folder FirstSample (e.g. m:\dev\projects\FirstSolution). Create a sub-folder SharedLibs. Copy the following assemblies into this folder (from the NHibernate bin folder which was created during compilation of NHibernate)
Create a sub-folder src (e.g. m:\dev\projects\FirstSolution\src).
Run VS 2008 and create a new solution. Choose C# Class Library as Template and call it FirstSolution. Choose "m:\dev\projects\FirstSolution\src" as location and uncheck "Create directory for solution". Click OK now.
Immediately add an additional class library project to the solution and call it FirstSolution.Tests. This project will contain all our test classes (remember we're doing TDD). You should then have a structure similar to this one:
In this article I have shown how to prepare a developer machine for using the very latest version of NHibernate as an ORM tool in an application that is developed by using TDD and DDD. First we installed the prerequisites then we either downloaded the NHibernate binaries or we download and compiled the source code of NHibernate and finally we prepared a first .NET solution to start with.
In this article I discuss how implement this very first NHibernate based solution.
