#NHibernate 3.1.0 on #NuGet – Important Details

If you don’t know what is NuGet, please skip to the end first

NHibernate Package

For some time NHibernate 3.0 package on Nuget was listed as owned by Fabio Maulo (@fabiomaulo), a main comitter to NHibernate, but was not owned by him until NHibernate 3.1 came out and there was a need to upgrade the package, which happened today.


You can find NHibernate package on Nuget by searching for the word NHibernate in the gallery, or going to the package page directly on :


Do Not Install This Package Directly

However, in this page (or summary pane in Nuget tool in Visual Studio when you select the package, you’ll read:

DONT INSTALL IT DIRECTLY Only as reference for others frameworks. NHibernate is a mature, open source object-relational mapper for the .NET framework. It’s actively developed , fully featured and used in thousands of successful projects.

Why Is That?

The reason for that is that NHibernate requires using something called a proxy factory. This is the tool that creates proxies of your entities (usually in runtime) for things like Lazy Loading to work. NHibernate has built-in support for those proxy factories, Castle Dynamic Proxy, .LinFu Dynamic Proxy, Spring AOP Framework.

So, What Should I Install ?

What you should actually do is to choose whether you want to use the Castle, LinFu, or Spring proxies, and based on that, install one (and –typically- only one) of the following packages:


NHibernate.Castle –


NHibernate.LinFu –


NHibernate.Spring –



Those packages all created by Fabio as well and depend on the main package. I will not give any differentiation between them and/or when to use them, but maybe if you use FluentNHibernate, you’ll want to use Castle Dynamic Proxy as this is their default.


FluentNHibernate/ConfORM & Other Libraries Depending on NHibernate

The way NHibernate package works from now on will make it a bit confusing to get other packages. For example, if you want to get FluentNHibernate / ConfORM, you will find that it explicitly depends on NHibernate package, but in the same time you are likely to need to install any of the other proxy-specific packages which is not set in the package dependencies.

The creator of FluentNHibernate may decide to depend on a proxy specific package instead, but this will be a problem if another NHibernate-dependent library may decide to depend on another proxy-specific package and it becomes a mess. So, I guess library creators will better not do that and we’ll need to live with the non-explicit dependency that is still likely required.



There is a really nice article on how to install for how to install NHibernate 3.0, and Windsor both from NuGet on ASP.NET MVC projects, The same rules though apply to NHibernate 3.1 and other types of projects than ASP.NET MVC.’

Create an ASP.NET MVC application with Windsor and NHibernate at the speed of nuget

Other than that, there is something you need to be careful of, assembly versions:


Installing Libraries That Depend on Specific Earlier Version of NHibernate|

Covers FLuentNHibenrate

Let’s take FluentNHibernate a an obvious example. FluentNHibernate package on NuGet is set to depend on a pre-release version of NHibernate 3.0. Not much changed in the FluentNHibernate library since then that will make you worry, so, to install it you need to do the following:

  1. Install one of the proxy packages, preferably NHibernate.Castle since this is the default in FluentNHibernate
  2. Install FluentNHibernate (don’t install it first so that it doesn’t just install old version of NH package as dependency)
  3. Apply Assembly Binding Redirect (see below)


Assembly Binding Redirect

Assembly Redirect is a way in .NET that you can use if you reference an assembly with specific version , and you want to use a different version of this assembly without recompiling your code or anything, you can tell .NET to redirect any request for the old version of the assembly to the new one. This is exactly what FluentNHibernate and any library that references specific old version of NHibernate need to do.

God news is, NuGet can setup the correct assembly redirects for you. In the current version of NuGet you need to explicitly call this functionality though. Next version of NuGet will run it automatically when you install a package.

Here is how to do it:


Make sure you build your solution once after adding the packages and before you do this, or else, the NuGet command will not do anything!

From VS 2010, Go to tools –>


The NuGet consolse will show up – Make sure the project you installed NHibernate and FluentNHibernate to is the one selected in the console:


Then type “Add-“ (no quotes) and press TAB, you’ll get intellisense, choose from there “Add-BindingRedirect” (no quotes) and press ENTER.


This should get you the following result (If not, try to build your project and do it again):


Now, you should find you application configuration file (web.config for web projects, app.config otherwise) having a similar section to this one (NuGet will create the file if not exists):


This is the assembly redirection that should allow things to work. Try it!


Other Notes


What Libraries on Nuget are updated to support NHibernate 3.1?

By the time of writing, the only package that supports NHibenrate 3.1 package is ConfORM (also created by Fabio

ConfOrm –



What is NHibernate.Linq Package?

There is another package on NuGet called NHibernate.Linq. Do NOT install this package is you work with NHibernate 3.x. This is the old LINQ provider that is created for NHibernate 2.1, and is no longer maintained.

LINQ support is now built into NHibenrate itself, not any separate package.


Boring Introductions Pushed To The End

If you feel lost going through this post, check out the below questions. If you still have confusion, just leave a comment with your question.


What is there in NHibernate 3.1.0?

Starting NHibernate 3.0.400, NHibernate ORM had interesting features like LINQ support and new query API called QueryOver, as long as hooks for writing entity mapping by code (as used in another library called ConfORM).

NHibernate 3.1.0 adds more LINQ support for more use cases, and adds more bug fixes and improvements on the same paths as 3.0.


What is NuGet?

If you know Ruby/Rails, it’s enough to say it’s Microsoft equivalent of Ruby Gems. Since few of my readers are Ruby guys. I’d explain this by saying it’s a tool that allows you to get software libraries (like NHibernate, Log4Net, Entity Framework 4 Code First CTPs, Castle Windsor etc..) from central repository (feed) where they are published. It allows you to get the library and all its dependencies (for example, NHibernate depends on Iesi.Collections) at one time without having to worry what those are. Each library is expressed by a package, where the package creator can include the library as code or binary and define library version and dependencies of other libraries/packages, and you just point your Visual Studio at the package and get them all, and easily update to future versions later.

It also comes with a PowerShell console inside Visual Studio that allows you to run those commands via scripts and do some interesting things like have libraries that support different versions of dependencies than the latest versions to support those latest versions by assembly redirection.

You can learn more about NuGet by going to