The application of this tutorial mimics a (very simple) shop. The main (and only) managed class is the Order.

Order is a class which has an identifier that makes it unique. Its properties are:

Shop is a class that can be used to do some operations related to Order. You can ask the shop to:

Now, run the executable file NHibernateEg.Tutorial1A.exe to see all these operations in action.

Note that you just have to create the database and configure its access; the application will fill it (after dropping the conflicting tables).

When running the application, you should get something like:

Application is starting...

Configuration of NHibernate...

Use database: <MSSQL>

NHibernate.Mapping.Attributes.HbmSerializer.Default.Serialize()...

new NHibernate.Tool.hbm2ddl.SchemaExport(cfg).Create()...
drop table SimpleOrder
create table SimpleOrder (
  Id INT IDENTITY NOT NULL,
   Date DATETIME null,
   Product NVARCHAR(255) not null,
   Quantity INT null,
   TotalPrice INT null,
   primary key (Id)
)

sessionFact = cfg.BuildSessionFactory();


Saving 3 aleatory orders...

3 orders found!
  Order N°1,  Date=2005-11-09 21:54:11Z,  Product=P1
  Order N°2,  Date=2005-11-09 21:54:11Z,  Product=P2
  Order N°3,  Date=2005-11-09 21:54:11Z,  Product=P3

Loading order N° 1...

Order N°1
 Date = wednesday 9 november 2005 20:54:11
 Product=P1 (updated),  Quantity=3,  TotalPrice=9

Update the order N° 1...

Save the order N° 0...

Change the time zone of all orders: n=25...
4 updated orders!

Deleting the order N° 2...

3 orders found!
  Order N°1,  Date=2005-11-10 22:54:11Z,  Product=P1 (updated)
  Order N°3,  Date=2005-11-10 22:54:11Z,  Product=P3
  Order N°4,  Date=2005-11-10 22:54:12Z,  Product=New

Application is closed!

If you get an exception, read it to understand what the exact problem is (it is probably related to your database installation or your connection string).

Study this output to understand what we will achieve in the next sections.

Here is the code of the method Program.Main() which generate this output:

	string database = System.Configuration.ConfigurationSettings.AppSettings["Database"];
	string connectionString = System.Configuration.ConfigurationSettings.AppSettings[database + ".ConnectionString"];

	Shop shop = new Shop(database, connectionString);

	shop.GenerateRandomOrders(3);

	shop.WriteAllOrders();

	Order o = shop.LoadOrder(1);

	o.Product += " (updated)";
	shop.Write(o);
	shop.Save(o);

	shop.Save( new Order("New", 4, 2) );

	shop.ChangeTimeZone(25);

	shop.Delete(2);

	shop.WriteAllOrders();

The strings database and connectionString are extracted from the file NHibernateEg.Tutorial1A.exe.config and sent to the Shop for its configuration.

Then we do some CRUD operations on Order: Create, Retrieve, Update and Delete. Their implementations will exhibit the usage of NHibernate for basic operations.

If you are familiar with ADO.NET, you can quickly create the application we described following these steps:

This method has some drawbacks (which increase with the complexity of the software):

After the theoric presentation made in the section called “Object / Relational Mapping”, we will focus on the practical aspect.

An Object / Relational Mapping solution allows focusing on the object model when designing an application. The database is hidden by a persistence framework.

While implementing the Shop, you will see that we almost never speak about the database (except to configure its access) and we will never manipulate tables/rows or SQL queries.

You will discover the benefits of this technology when using it.

The step zero is to create a Console Application and add the libraries: NHibernate.dll, log4net.dll and NHibernate.Mapping.Attributes.dll as references.

Now, we are going to implement the class Order. That is: Create the class, add the fields / properties and the methods.

To manipulate the classes, NHibernate needs a mapping between these classes and the database tables. Here, we use the NHibernate.Mapping.Attributes to provide this mapping information.

NHibernate.Mapping.Attributes uses .NET Attributes to define the mapping.  Basically, for each element in your classes, you put the right attribute on it so that NHibernate will know how this element is mapped to its equivalent in the database. Each attribute has many properties used to specify how the mapping should work. Read NHibernate mapping reference documentation to understand their meaning.

Here is the implementation of the class Order:

	[NHibernate.Mapping.Attributes.Class(Table="SimpleOrder")]
	public class Order
	{
	}

	private int _id = 0;
	[NHibernate.Mapping.Attributes.Id(Name="Id")]
		[NHibernate.Mapping.Attributes.Generator(1, Class="native")]
	public virtual int Id
	{
		get { return _id; }
	}

	private System.DateTime _date = System.DateTime.Now;
	private string _product;
	private int _quantity;
	private int _totalPrice;

	[NHibernate.Mapping.Attributes.Property]
	public virtual System.DateTime Date
	{
		get { return _date; }
	}

	[NHibernate.Mapping.Attributes.Property(NotNull=true)]
	public virtual string Product
	{
		get { return _product; }
		set { _product = value; }
	}

	[NHibernate.Mapping.Attributes.Property]
	public virtual int Quantity
	{
		get { return _quantity; }
		set { _quantity = value; }
	}

	[NHibernate.Mapping.Attributes.Property]
	public virtual int TotalPrice
	{
		get { return _totalPrice; }
		set { _totalPrice = value; }
	}

	public Order()
	{
	}

	public Order(string product, int unitPrice, int quantity)
	{
		this.Product = product;
		this.Quantity = quantity;
		this.ComputeTotalPrice(unitPrice);
	}

	public void ComputeTotalPrice(int unitPrice)
	{
		this.TotalPrice = unitPrice * this.Quantity;
	}

	public virtual void ChangeTimeZone(int n)
	{
		this._date = this.Date.AddHours(n);
	}

This configuration is done in the constructor of Shop: public Shop(string database, string connectionString).

Before configuring NHibernate, there is a library you need to know: log4net.

log4net is a logging system.  Basically, it receives log messages, filters them as you want and sends them wherever you want (in a file, on the console, in a database, as e-mail, etc.)

Its configuration is in the file NHibernateEg.Tutorial1A.exe.config, in the section called <log4net>. You have to call one of the log4net.Config.XmlConfigurator.Configure() methods before using it; these methods read the configuration.

Finally, you put somewhere in your code:

[assembly: log4net.Config.XmlConfigurator(Watch=true)]

Watch=true tells to log4net to detect changes made on the configuration file at run-time (very useful to not have to restart your application...). For more information, go to log4net website.

NHibernate needs some information to know how to communicate with the database:

The <appSettings /> section (in NHibernateEg.Tutorial1A.exe.config) makes it possible to switch from one database to another without changing a single line of code. Doing this with plain ADO.NET is not straightforward.

Here is the code used to set this information:

	// Create the object that will hold the configuration settings
	// and fill it with the information to access to the Database
	NHibernate.Cfg.Configuration cfg = new NHibernate.Cfg.Configuration();
	cfg.SetProperty( NHibernate.Cfg.Environment.ConnectionProvider,
		"NHibernate.Connection.DriverConnectionProvider" );

	if("MSSQL" == database)
	{
		cfg.SetProperty(NHibernate.Cfg.Environment.Dialect, "NHibernate.Dialect.MsSql2000Dialect");
		cfg.SetProperty(NHibernate.Cfg.Environment.ConnectionDriver, "NHibernate.Driver.SqlClientDriver");
		cfg.SetProperty(NHibernate.Cfg.Environment.ConnectionString, connectionString);
	}
	else [...]

Here, you can read the value of Dialect and ConnectionDriver for a Microsoft SQL Server 2000 database. These values are set with the method SetProperty(). They can also be set with a XML file.

We extract the mapping information using NHibernate.Mapping.Attributes:

	System.IO.MemoryStream stream = new System.IO.MemoryStream(); // Where the information will be written in
	// Ask to NHibernate to use fields instead of properties
	NHibernate.Mapping.Attributes.HbmSerializer.Default.HbmDefaultAccess = "field.camelcase-underscore";(1)
	// Gather information from this assembly (can also be done class by class)
	NHibernate.Mapping.Attributes.HbmSerializer.Default.Serialize( stream,
		System.Reflection.Assembly.GetExecutingAssembly() );(2)
	stream.Position = 0;
	cfg.AddInputStream(stream);(3) // Send the Mapping information to NHibernate Configuration
	stream.Close();

Now, we use a wonderful tool: SchemaExport:

new NHibernate.Tool.hbm2ddl.SchemaExport(cfg).Create(true, true);

Here, we create an instance of SchemaExport and we directly call the method Create(). It uses all the provided information (in the configuration instance) to generate and run a script that will create the tables and relationships in the database to hold the mapped classes. Note that it will fail to drop a table if this table has a reference that doesn’t exist in the mapping; in this case, you must drop this table manually.

Finally, we create the SessionFactory: (explanation in the next section)

_sessionFactory = cfg.BuildSessionFactory();

Note thate the _sessionFactory is an instance of the class Shop that will be destroyed only when the Shop instance is destroyed.

Before digging into NHibernate operations, there are some concepts that need to be explained:

The notion of "Entity".  In these articles, an entity is simply a mapped class. It implies that NHibernate is aware of this class and can manipulate it.

The main interface used to manipulate entities is ISession (full name: NHibernate.ISession).

You need one ISessionFactory for each database (which is generally created at the initialization of the application as it is the case here). Its implementation is thread-safe and exception-proof, so that it can live as long as your application is running.

A session is created by an ISessionFactory by calling the method ISessionFactory.OpenSession().

You should use the session-per-request pattern; that is create one session for each user request. This is recommended because a session is not exception-proof (nor thread-safe). If an exception is thrown, you should rollback the transaction and close the session (don’t try to recover it).

The classic usage of a session (and its transaction) is:

	NHibernate.ISession session = null;
	NHibernate.ITransaction transaction = null;
	try
	{
		session = _sessionFactory.OpenSession();
		transaction = session.BeginTransaction();

		// CRUD operations here (with the session)

		transaction.Commit();
	}
	catch
	{
		if(transaction != null)
			transaction.Rollback();
		throw;
	}
	finally
	{
		if(session != null)
			session.Close();
	}

As you can read in this code, we create the session, then its transaction. We use the session to do some CRUD operations; finally, we commit the changes and close the session (rollback if any exception is thrown).

NHibernate transactions behave like ADO.NET transactions. The transaction is tightly coupled with the session. SQL commands are generated and ran only when calling transaction.Commit(). But it is possible to force that by calling session.Flush().

Note that creating the transaction is optional (mainly when you just want to run SELECT operations); in this case, you can write:

	using(NHibernate.ISession session = _sessionFactory.OpenSession())
	{
		// Retrieve data here (with the session)
	}

using() will automatically close the session.

An entity has a state which can change: The state you implicitly know is transient. When you create an instance of a class, this instance is transient.

Once you send this instance to a session (to save/update it...), this instance becomes persisted. At this level, the session has this instance in its cache.

If you delete this instance, it is obviously not destroyed from the memory; the session will delete its row in the database and will remove it from its cache (which means that it becomes transient again). Note that an entity can not be attached to two opened sessions at the same time.

Finally, when an instance is persisted and the session which persisted it is closed, this instance became detached. The difference with "transient" is that there might be some useful information that are hidden in this instance and can be used by another session.

Now, we will use the session to do some basic CRUD operations (that is Create, Retrieve, Update and Delete).

For each operation, a method will be shown and explained.

	public void GenerateRandomOrders(int n)
	{
		NHibernate.ISession session = null;
		NHibernate.ITransaction transaction = null;
	
		System.Console.Out.WriteLine("\nSaving " + n + " aleatory orders...");
		try
		{
			session = _sessionFactory.OpenSession();
			transaction = session.BeginTransaction();
	
			for(int i=0; i<n; i++)
			{
				Order o = new Order();
	
				o.Product = "P" + (i+1).ToString();
				o.Quantity = n - i;
				o.ComputeTotalPrice(i * 10 + n);
	
				session.Save(o);
			}
	
			// Commit modifications (Build and execute queries)
			transaction.Commit();
		}
		catch
		{
			if(transaction != null)
				transaction.Rollback(); // Error: we MUST roll back modifications
			throw; // Here, we throw the same exception so that it is handled (printed)
		}
		finally
		{
			if(session != null)
				session.Close();
		}
	}

	public void WriteAllOrders()
	{
		using(NHibernate.ISession session = _sessionFactory.OpenSession())
		{
			System.Collections.IList result = session.Find("select o.Id, o.Date, o.Product from Order o");
	
			System.Console.Out.WriteLine("\n" + result.Count + " orders found!");
			foreach(System.Collections.IList l in result)
				System.Console.Out.WriteLine("  Order N°"
					+ l[0] + ",  Date=" + ((System.DateTime)l[1]).ToString("u")
					+ ",  Product=" + l[2]);
		} // finally { session.Close(); }	is done by using()
	}

	public Order LoadOrder(int id)
	{
		System.Console.Out.WriteLine("\nLoading order N° " + id + "...");
		using(NHibernate.ISession session = _sessionFactory.OpenSession())
			return session.Load(typeof(Order), id) as Order;
		// finally { session.Close(); }	is done by using()
	}

	public void Save(Order o)
	{
		NHibernate.ISession session = null;
		NHibernate.ITransaction transaction = null;

		// That's how the Session decide to save or to update; set NHMA.Id(UnsavedValue=x) to replace 0
		System.Console.Out.Write("\n"  +  (o.Id == 0  ?  "Save"  :  "Update"));
		System.Console.Out.WriteLine(" the order N° " + o.Id + "...");
		try
		{
			session = _sessionFactory.OpenSession();
			transaction = session.BeginTransaction();

			// NHibernate Session will automatically find out if it has to build an INSERT or an UPDATE
			session.SaveOrUpdate(o);

			// Commit modifications (=> Build and execute queries)
			transaction.Commit();
		}
		catch
		{
			if(transaction != null)
				transaction.Rollback(); // Error => we MUST roll back modifications
			throw; // Here, we throw the same exception so that it is handled (printed)
		}
		finally
		{
			if(session != null)
				session.Close();
		}
	}

	public void ChangeTimeZone(int n)
	{
		NHibernate.ISession session = null;
		NHibernate.ITransaction transaction = null;

		System.Console.Out.WriteLine("\nChange the time zone of all orders: n=" + n + "...");
		try
		{
			session = _sessionFactory.OpenSession();
			transaction = session.BeginTransaction();

			System.Collections.IList commandes = session.CreateCriteria(typeof(Order)).List();
			// same as: session.Find("from Order");
			foreach(Order o in commandes)
				o.ChangeTimeZone(n);
			// It is useless to call Update(), the Session will automatically
			// detect modified entities (as long as it loaded them)
			System.Console.Out.WriteLine(commandes.Count + " updated orders!");

			// Commit modifications (=> Build and execute queries)
			transaction.Commit();
		}
		catch
		{
			if(transaction != null)
				transaction.Rollback(); // Error => we MUST roll back modifications
			throw; // Here, we throw the same exception so that it is handled (printed)
		}
		finally
		{
			if(session != null)
				session.Close();
		}
	}

session.CreateCriteria(typeof(Order)).List()

session.Find("from Order")

session.Find("select o from Order o")

	public void Delete(int id)
	{
		NHibernate.ISession session = null;
		NHibernate.ITransaction transaction = null;

		System.Console.Out.WriteLine("\nDeleting the order N° " + id + "...");
		try
		{
			session = _sessionFactory.OpenSession();
			transaction = session.BeginTransaction();

			session.Delete("from Order o where o.Id = :Id", id, NHibernate.NHibernateUtil.Int32);

			// Commit modifications (=> Build and execute queries)
			transaction.Commit();
		}
		catch
		{
			if(transaction != null)
				transaction.Rollback(); // Error => we MUST roll back modifications
			throw; // Here, we throw the same exception so that it is handled (printed)
		}
		finally
		{
			if(session != null)
				session.Close();
		}
	}

session.Delete("from Order o where o.Id = " + id);

In this tutorial, we designed a simple shop, we implemented its order class, we configured NHibernate and implemented the Shop's methods (doing CRUD operations).

The most obvious advantage of using an ORM (for beginners) is the simplicity when doing CRUD operations. When you are familiar with the API, you can load, save, update and delete entities without any knowledge of the underlining database; you don’t even need to know SQL. But this knowledge is still important if you want get the best performance.

Another more important advantage is that your entities don’t even know that they are ever persisted; which can be useful in complex applications. Persistence becomes an external service which is not intrusive here (almost).

Finally, you can design your application with OOP in mind and then create a database that can keep your entities.

But NHibernate is also impressive when dealing with legacy database. You can take a classic relational database and map it to your object-oriented entities.

You have to understand that if DataSet is not the perfect answer to every problem, ORM is neither perfect in every situation. Reporting and batch processing are situations where DataSet and DataReader might perform better. And it is probably less brainstorming to use them in straightforward applications.

Now, I suggest you to try to do a Console Application similar to this one without looking at the tutorial/code too often. You may also try new things. After that, you will have a better understanding and memorize more information.

A tool that you should really try is NHibernate Query Analyzer. With it, you can edit NHibernate XML configuration files and mapping (.hbm.xml) files. You can also easily run HQL queries after setting up the configuration. To see it in action, download the flash videos available on its web site.

You can find more sample and articles in the NHibernate Documentation.

And if you want to discuss about this tutorial, use this NHibernate topic. Note that you should only use it for topics directly linked to this tutorial; if you have some problems with your own tests, you should create a new topic (read Chapter 4, More information and support).