Sunday, April 15, 2007

NHibernator - The simple but yet powerful NHibernate helper

Overview
Working with NHibernate requires the use of a framework to configure NHibernate and to manage the session. The NHibernate wiki contains documentation about the recommended way to do it (see http://www.hibernate.org/363.html) especially in an ASP.NET environment.

Frameworks like Spring.Net and Castle provide a full-featured solution for integrating NHibernate in an application, but for some applications it's considered as overkill.
That's why most applications use some kind of homemade NHibernate Helper, based on code examples from the Internet. Some of them can be found at the bottom of http://www.hibernate.org/363.html.

So I was searching for a simple NHibernate Helper that is simple to integrate, but still provides the feature I need, like working with multiple databases, support for ASP.NET and Winform environment, and more...

NHibernator
I created the NHibernator as a solution for a simple NHibernate Helper, I will upload it to SourceForge as an open source so people can contribute. Meanwhile you can download it here.

Main features:
1. Easy configuration at the bootstrap, with a specific configuration file.
2. Support for multiple databases.
3. OpenSessionInViewModule for ASP.NET applications.
4. Thread bounded session management for Winform application.
5. NHibernatorTransaction for easy transaction management, with automatic Rollback and easy snippet for easy coding.

NHibernator supports 3 session management mechanisms.
1. OpenSessionInViewModule: Just define a module in the web.config and the session will be opened when needed and released at the end of each request.
2. Session per Transaction: In a non-web applications session will be opened at the beginning the transaction and closed at the end of it.
3. Manual session management: Session will be opened and closed manually with NHibernator.OpenSession() and NHibernator.CloseSession() respectively.

How to use?
1. Basic Configuration: Just place "hibernate.cfg.xml" file in the executable directory, as an alternative you can use the "NHibernatorConfigFileLocation" key in the appSettings section of the web.config. For example:


<appSettings>
  <
add key="NHibernatorConfigFileLocationvalue="~Config\hibernate.cfg.xml"/>
</
appSettings>


This can either be full path or relative path using ~. For multiple databases use semicolon, for example:


<appSettings>
  <
add key="NHibernatorConfigFileLocationvalue="~Config\hibernate1.cfg.xml;~Config\hibernate2.cfg.xml"/>
</
appSettings>


2. ASP.NET: For a web application you will probably want to use the OpenSessionInViewModule for handling the session at the http-request level.
This can be done by adding this to your web.config file.


<system.web>
  <
httpModules>
    <
add name ="NHibernatortype="NHibernatorFramework.OpenSessionInViewModule, NHibernator"/>
  </
httpModules>
</
system.web>


3. Using NHibernator
  1. Add a reference to the NHibernator assembly.
  2. Add a using to NHibernatorFramework.
  3. Get the session with NHibernator.GetSession(). When using a Data Access Layer in your application, it's recommended to use a BaseDal like this:



public class BaseDAO
{
  
protected ISession session = null;

  
public BaseDAO()
  {
        session = NHibernator.GetSession();
  }
}



When using multiple databases, you will have to specify the name of the sessionFactory to use, like this:
NHibernator.GetSession("SomeDB")
respectively with the name defined in the xml


<hibernate-configuration xmlns="urn:nhibernate-configuration-2.2">
  <
session-factory name="SomeDB">
    <
property name="hibernate.connection.connection_string">...</property>

  </
session-factory>


4. NHibernatorTransaction: Using NHibernatorTransaction will provide Auto Rollback on exceptions, and Automatic session-per-transaction management for a non-web application.
For example:


using (NHibernatorTransaction transaction = new NHibernatorTransaction())
{
    
// some dal code here
    
transaction.Commit();
}



This can also be done using the "NHibernator Transaction" Snippet, like this:





That's it, Please comment if you have remarks or suggestions.

11 comments:

Anonymous said...

This looks like a cool helper, but it's a 2.0 Framework library. I'm still developing 1.1 apps, unfortunately.

Any chance the source code could be posted on SourceForge so I can compile it in 1.1? Or having a 1.1 version released?

Thanks!

Tomer Avissar said...

Now posted to SourceForge, see http://oracleatdotnet.blogspot.com/2007/05/nhibernator-in-sourceforge.html

Anonymous said...

where is src of you library ???

Tomer Avissar said...

You can find the source code in SourceForge, see post "NHibernator in SourceForge"

Anonymous said...

Netffc You have a talant! Write more!

Anonymous said...

MAu0ho Please write anything else!

Anonymous said...

4IDyWD The best blog you have!

Anonymous said...

7g5bsM actually, that's brilliant. Thank you. I'm going to pass that on to a couple of people.

Anonymous said...

Please write anything else!

Anonymous said...

actually, that's brilliant. Thank you. I'm going to pass that on to a couple of people.

Anonymous said...

Hello all!