Before We Start

You will need a Visual Studio 2010/2012/2013 (any edition, including Express) and a SQL Server 2008 installation (any edition). The SQL Server instance must be using the TCP/IP protocol and must be accessible from the host where the examples will run. You will need permissions on the SQL Server to create a database; call it Succinctly.

Getting NHibernate

You can get NHibernate from a number of sources:

  • NuGet.
  • As source code from a GitHub repository.
  • As a downloadable .zip package from SourceForge.

NuGet

On Visual Studio 2010/2012/2013, with an open .NET project, fire up the Package Manager Console and enter the following command:

This is probably the most convenient way to obtain NHibernate and to wire up references. It also allows you to update automatically when new versions are available. The NHibernate package will bring along log4net and Iesi.Collections; these are required dependencies (more on this later).

By default, the package installer will only add references to the added packages in the current project, but you can add them explicitly to the other projects by clicking on Manage NuGet Packages for Solution and selecting the other projects:

Figure 1: Manage NuGet Packages

Downloadable Packages

There are packages available for download for current and past versions, including source code and reference documentation, on the SourceForge site at http://sourceforge.net/projects/nhibernate. Navigate to the Files page and select the version you want:

Figure 2: Manage Packages for Solution

Download the binary distribution (the one ending in .bin), extract the files into a local folder, and add references to the DLLs NHibernate.dll, Iesi.Collections.dll, and log4net.dll to your projects so that you can start using NHibernate right away.

Source Code

The NHibernate source code repository can be found on GitHub under the name nhibernate-core. You need to install a Git client (which you can download from http://git-scm.com) and clone this repository into your local drive. Using the command line, it would look something like this:

Figure 3: NHibernate Project at SourceForge

There’s a web interface for this repository available at https://github.com/nhibernate/nhibernate-core where you see the latest changes, browse through the folders, and view individual files including their content and individual changes.

Figure 4: NHibernate Project's GitHub Web Interface

Once you have the files locally, enter the nhibernate-core folder and run the ShowBuildMenu.bat script:

Figure 5: Cloning the NHibernate GitHub Repository

When you run this script for the first time, you need to first select option A for setting up the Visual Studio files. This is only needed once; afterwards, to obtain a build package, either choose option E or F for Debug or Release builds. After the build process terminates, binaries will be available on the nhibernate-core\build\<version>folder and you can add them as references to your projects.

Figure 6: Building NHibernate from Source Code

There are some things you should keep in mind when using the source code repository:

  • You can get the latest changes at any time by running git pull.
  • The files you are obtaining are the latest unstable ones; that is, they are the result of individual contributions and experimental features as soon as they are submitted, and may not be so thoroughly tested as the official packages (the ones you get from NuGet or SourceForge).
  • You are free to experiment and make modifications to the local source code files. Don’t be alarmed; you can always revert if something goes wrong. Or you can implement some new functionality or fix some bugs, in which case you may want to make these modifications available to everyone using NHibernate. More on this in the last chapter, Additional References.
Figure 7: Getting Latest Changes

What’s Inside

The NHibernate binary distribution consists of three files: Nhibernate.dll, Iesi.Collections.dll, and log4net.dll. Some explanation about their purpose is as follows:

  • NHibernate.dll contains the core NHibernate libraries; these are the ones you need to work with NHibernate. This is a .NET 3.5 assembly which, as you probably know, is basically .NET 2.0 with some additional libraries and support for LINQ syntax. Thanks to backwards compatibility, NHibernate still targets .NET 2.0 (which doesn’t mean you can’t use it in a .NET 4.0 or .NET 4.5 project because, indeed, you can).
  • Iesi.Collections.dll contains some collection definitions and implementations that, as of .NET 2.0/3.5, didn’t exist in the .NET Base Class Library. The most notable of these is a set interface and some implementations; the NHibernate.dll internally makes use of this assembly and most likely you will, too, so it must also be present. Its source code is together with NHibernate’s.
  • log4net.dll is actually an external project; you can find its home page at http://logging.apache.org/log4net and, if you don’t know, it’s a general purpose logger. Internally, NHibernate uses log4net for its own logging including runtime warnings, debug messages, exceptions, and generated SQL queries. Although strictly not required-NHibernate will detect whether log4net is present at startup and won’t complain if it is not-it may be very useful, especially when debugging your projects. Of course, log4net is a very mature library used in several projects and you may also be interested in using it for your own logging purposes.

Which One Shall I Choose?

It is up to you which one you choose but I would recommend NuGet due to its simplicity and ease of use. On the other hand, if you want to live dangerously and stay up to date with the latest development on the NHibernate core, by all means, use the source!