Upgrade to NHibernate 3.0.0

I recently upgraded to NHibernate 3.0.0. NHibernate 3.0.0 has a good backward compatible with version 2.1.2. It includes a new Linq provider that fully supports Linq. When upgrading to NHibernate 3.0.0 I stumble into the following issues:

· The new Linq provider is included in NHibernat 3.0.0 and I didn’t have to download it separately.

· The method session.Linq<T>() is replaced by session.Query<T>().

· The new Linq provider has full support for Linq and I had to update some Linq queries. For example, it manages eager load differently. It includes new methods, Fetch and FetchMany, to define what shall be fetched eagerly.

So, it was quite easy to upgrade and I didn’t have that much trouble. Still need to explore all new features and re-factor the code whenever possible to take advantage of them. First impression of NH 3.0.0 is very good.

Troubleshooting NHibernate

There are many different ways to troubleshoot NHibernate. I mainly use show_sql, log4net and SQL Server Profile.


In the configuration of NHibernate, there is a property called show_sql. If you set this to true, NHibernate will output all generated sql to the console.

You enable show_sql by adding the following piece of code to the configuration file.

<property name=”show_sql”>true</property>

To view the output from a unit test, you must select the unit test in the Test Result window and use View Test Result Details.

The unit test’s result window displays the output.


If you need more detailed debug information you can use log4net. Log4Net is an open source library that NHibernate uses to log all interesting events. You can use it to log information to a file, the console or both. To use it, you have to add some information to the configuration file. First declare the log4net section.

<section name=”hibernate-configuration” type=”NHibernate.Cfg.ConfigurationSectionHandler, NHibernate” />
<section name=”log4net” type=”log4net.Config.Log4NetConfigurationSectionHandler, log4net”/>

Here is an example how you can configure log4net to write events from NHibernate both to a file and the console. Read more about log4net on the homepage.

<appender name=”NHibernateFileLog” type=”log4net.Appender.RollingFileAppender”>
<file value=”c:\nhibernate2.txt” />
<appendToFile value=”true” />
<rollingStyle value=”Size” />
<maxSizeRollBackups value=”10″ />
<maximumFileSize value=”100KB” />
<staticLogFileName value=”true” />
<layout type=”log4net.Layout.PatternLayout”>
<conversionPattern value=”%d{HH:mm:ss.fff} [%-5p] %c – %m%n” />
<appender name=”Console” type=”log4net.Appender.ConsoleAppender, log4net”>
<layout type=”log4net.Layout.PatternLayout,log4net”>
<param name=”ConversionPattern” value=”%d{ABSOLUTE} %-5p %c{1}:%L – %m%n” />
<level value=”DEBUG”/>
<appender-ref ref=”Console” />
<logger name=”NHibernate” additivity=”false”>
<level value=”DEBUG”/>
<appender-ref ref=”NHibernateFileLog”/>
<appender-ref ref=”Console” />

You also have to initialize log4net from the application

//Start Log4Net

The output now contains much more information about the internal works of NHibernate:

SQL Server Profiler

SQL Server Profiler can be very useful when you line step an application and want to view each database call NHiberante makes. In this way you can follow how NHibernate flushes changes to the database and manages caching. SQL Server Profiler can be started from SQL Server Management Studio.

To use it your user must be a member of sysadmin.

When the Profiler is started, you can create a new trace and view each database call NHibernate makes.

Flushing in NHibernate

NHibernate has a two layer caching system. The first layer is always active and designed to optimize performance. The second cache is optional and pluggable. You can choose your own provider. The second layer cache is, for example, a good place to cache reference data that doesn’t change so much. If used correctly, the caching mechanism can improve performance significantly.

When changes are made to the persistent objects, they are not immediately propagated to the database. NHibernate stores them in the first layer cache. In this way many changes can be combined into fewer database requests. For example, if a property is updated several times during a session, NHibernate only needs to execute one single SQL update. But when are the changes synchronized with the database? NHibernate calls the synchronization with the database for flushing, and it occurs when:

1) When a transaction commits to make the changes durable.

2) Before a query executes, if the first layer cache contains modified data that affects the result of the query.

3) When the application explicitly calls Flush().

It is also possible to change the default behavior by changing the FlusMode property in the session. As I understand this is not recommended.

NHibernate and Intellisense

NHibernate is OR mapping tool for Microsoft’s .Net platform. It is used to map an object-oriented domain model to a relation database. It also includes features to query and retrieve data. The mapping files are in XML format and it can be a bit hard to know the syntax. Luckily there is support for Intellisense in Visual Studio, which makes it much easier to work with the mapping files. Here is how I set it up for NHibernate 2.1.2 and Visual Studio 2008.

1) Copy the files nhibernate-configuration.xsd and nhibernate-mapping.xsd from the Required_Bins folder in the NHibernate distribution directory.

2) Paste them into C:\Program Files (x86)\Microsoft Visual Studio 9.0\Xml\Schemas.

3) Restart Visual Studio.