The NHibernate documentation is often very handy when working on NHibernate based project. I keep PDF copies of the documentation to NHibernate 1.0 and 1.2 on my hard drive as I never know when I will need to reference them. Unfortunately the NHibernate team seems to have dropped the ball in regards to version 2.0. Not only does the NHibernate website lack any documentation on version 2.0, the website acts as if version 2.0 hasn’t even been released yet. Unlike previous updates to the framework, version 2.0 represents a complete refactoring of the code base with many namespaces and objects either removed or renamed. Despite the lack of official documentation there are still several resources to help you migrate your existing NHibernate 1.2 application to NHibernate 2.0.

List of breaking changes

The NHibernate forum has a thread discussing the breaking changes between version 1.2 and an alpha pre-release of 2.0. For the complete list check out the forum, however here are the ones you will be most likely to face.

Problem: The NHibernate.Expression namespace no longer exists.

Overview: Most notable of the items formerly kept in this namespace was the Expression object used when creating ICriteria. Fortunately the object still existing in the NHibernate.Criterion namespace.

Solution: Replace all “using” statements to reflect the namespace change.

//using NHibernate.Expression; //this line is no longer needed in NH 2.0
using NHibernate.Criterion;    //replace it with this line.

Problem: The nhibernate configuration section (most likely in your web.config or app.config) is no longer used.

Overview: NHibernate 2.0 no longer looks at the configuration section named nhibernate, instead it looks for a configuration section called hibernate-configuration (notice the lack of an “n” in hibernate). Moreover the configuration section wasn’t simply renamed, it bears and entirely different schema.

Solution: In short the entire configuration section is going to have to be reworked slightly.

For starters your configuration section declaration will have to change its name and type:

<configuration>
   <configSections>
      <section name="hibernate-configuration" type="NHibernate.Cfg.ConfigurationSectionHandler, NHibernate" requirePermission="false"/>
   </configSections>

Notice how the name changed (as described above) and the type is now a configuration section handler defined in the NHibernate library. This also implies that NHibernate.dll must be reference from your UI were it previously was not required unless you were doing data access in your UI… and you shouldn’t have been doing that anyway.

Once the configSection is updated you will have to update the the actual configuration. Take for example a NHibernate 1.2 configuration from one of my applications:

  <nhibernate>
    <add key="hibernate.connection.provider" value="NHibernate.Connection.DriverConnectionProvider"/>
    <add key="hibernate.dialect" value="NHibernate.Dialect.MsSql2005Dialect"/>
    <add key="hibernate.connection.driver_class" value="NHibernate.Driver.SqlClientDriver"/>
    <add key="hibernate.connection.connection_string" value="SQL CONNECTION STRING HERE"/>
    <add key="hibernate.bytecode.provider" value="null"/>
    <add key="hibernate.show-sql" value="false" />
  </nhibernate>

I had to rewrite the above into this:

  <hibernate-configuration xmlns="urn:nhibernate-configuration-2.2">
    <bytecode-provider type="null"/><!-- Important under Medium Trust -->
    <reflection-optimizer use="false"/>
    <session-factory>
      <property name="connection.provider">NHibernate.Connection.DriverConnectionProvider</property>
      <property name="dialect">NHibernate.Dialect.MsSql2005Dialect</property>
      <property name="connection.driver_class">NHibernate.Driver.SqlClientDriver</property>
      <property name="connection.connection_string">SQL CONNECTION STRING HERE</property>
      <property name="show_sql">false</property>
    </session-factory>
  </hibernate-configuration>

The differences are not minor, and the values of the configurations are about the only thing that doesn’t change. Notice how the key name is now just called name, and the leading hibernate prefix has been dropped. Additionally notice how the configuration section now has a hierarchy that pushes most of the configuration detail down into the session-factory section, with the notable exceptions of the bytecode provider and the reflection optimization settings.

Additional Resources

In addition to the above resources I also used the xsd schema definition that ships with NHibernate 2 to figure out how to write the new configuration section. .NET Reflector was also useful for verifying the new locations of various classes. And finally, the Hibernate documentation will come in more use these days as the latest version of NHibernate allegedly is closer in design to its Java cousin than its predecessor.

Final Thoughts

Other than the lack of official documentation, I must say that I am pleased with the ease of converting a NHibernate 1.2 application to version 2.0. Those of you who experienced the joy of converting a 1.0 application to 1.2 remember the amount of tedious mapping modification that were needed. I can thankfully say that this conversion does not (at least in my circumstances) require you to change any of your mapping files.