NHibernate 4.x Cookbook - Second Edition

Instead of using the graphical package manager, you can use the Package Manager Console. It provides a faster way to install or update NuGet packages. To open the Package Manager Console simply click Tools | NuGet Package Manager | Package Manager Console. In the opened window you can simply write the following:

Install-Package NHibernate -Project Eg.Core

This will produce the same effect as the main recipe.

The connection string we've defined points to the NHCookbook database running under the local Microsoft SQL Server.

Next, we define a few properties that tell NHibernate how to behave.

The dialect property specifies a dialect class that NHibernate uses to build SQL syntax specific to a Relational Database Management System (RDBMS). We're using the Microsoft SQL 2012 dialect. Additionally, most dialects set intelligent defaults for other NHibernate properties, such as connection.driver_class.

The connection.connection_string_name property references our connection string by name.

By default, NHibernate will send a single SQL statement and wait for a response from the database. When we set the adonet.batch_size property to 100, NHibernate will group up to 100 SQL INSERT, UPDATE, and DELETE statements in a single ADO.NET command and send the whole batch at once. In effect, the work of 100 round trips to the database is combined in one. Because a roundtrip to the database is, at best, an out-of-process call, and at worst, a trip through the network or even the Internet, this can improve performance significantly. Batching is currently supported when targeting Microsoft SQL Server, Oracle, or MySQL.

We change Copy to Output directory to ensure that our hibernate.cfg.xml file is copied to the build output directory.

By default, NHibernate looks for its configuration in the hibernate.cfg.xml file. However, the Configure method has three extra overloads, which can be used to provide configuration data from other sources, such as:

NHibernate architecture

There are several key components to an NHibernate application, as shown in this diagram:

On startup, an NHibernate application builds a Configuration object. In this recipe, we build the configuration from settings in the hibernate.cfg.xml file. The Configuration object is responsible for loading mappings, investigating the object model for additional information, building the mapping metadata, and finally building a session factory. Building the session factory is a rather resource intensive operation, and is normally only done once, when the application starts up.

A session represents a Unit of Work in the application. Martin Fowler defines a Unit of Work as something that "maintains a list of objects affected by a business transaction and coordinates the writing out of changes and the resolution of concurrency problems". An NHibernate session tracks changes to entities and writes those changes back to the database all at once. In NHibernate, this process of waiting to write to the database is called transactional write-behind. In addition, the session is the entry point to much of the NHibernate API. More information about the Unit of Work pattern is available at http://martinfowler.com/eaaCatalog/unitOfWork.html and in Fowler's book, Patterns of Enterprise Application Architecture. A session factory is responsible for creating sessions.

The session acts as an intermediary between our application and several key NHibernate components. A typical application will not interact with these components directly, but understanding them is critical to understanding NHibernate. Unlike a session factory, building a session is very cheap.

A dialect is used to build correct SQL syntax for a specific RDBMS. For example, in some versions of Microsoft SQL Server, we begin a select statement with SELECT TOP 20 to specify a maximum result set size. Only 20 rows will be returned. Similarly, to perform this operation in SQLite, we append LIMIT 20 to the end of the select statement. Each dialect provides the necessary SQL syntax string fragments and other information to build correct SQL strings for the chosen RDBMS.

A driver is responsible for building a Batcher, creating IDbConnection and IDbCommand objects, and preparing those commands.

A connection provider is simply responsible for opening and closing database connections.

A batcher manages the batch of commands to be sent to the database and the resulting data readers. Currently, only the SqlClientDriver, OracleDataDriver, and MySqlDataDriver support batching. The drivers that don't support batching provide a NonBatchingBatcher to manage IDbCommands and IDataReaders and simulate the existence of a single logical batch of commands.

This recipe works in the same way as the previous recipe. However, in this recipe, we have moved the hibernate-configuration element from the hibernate.cfg.xml file to App.config. The connection.connection_string_name property references our connection string named db. We can name the connection string anything we like, as long as this property matches the connection string's name.

An ASP.NET application's Web.config uses the common .NET framework configuration platform and has the same structure as App.config. You can therefore use the same technique to configure NHibernate in a web application.

In this recipe, we create an NHibernate configuration using methods in the NHibernate.Cfg namespace. These methods offer full type safety and improved discoverability over code configurations in the previous version of NHibernate.

We specify dialect, connection.connection_string_name, and adonet.batch_size with the DatabaseIntegration method. Finally, we build a session factory using the BuildSessionFactory method.

Notice that we are still referencing the db connection string defined in our App.config file. If we wanted to eliminate the App.config file entirely, we could hardcode the connection string with this code:

db.ConnectionString = @"Connection string here...";

This, however, is completely inflexible, and will require a full recompile and redeployment for even a minor configuration change.

Our fluent configuration can be broken down into three parts. First, we configure these properties:

Next, from the fluent configuration, we build a standard NHibernate configuration. Finally, we build a session factory using the BuildSessionFactory method.

Complete the earlier Configuring NHibernate with App.config or Web.config recipe.

The log4net framework uses appenders, layouts, and loggers to format and control log messages from our application, including log messages from NHibernate.

Appenders define the destination for log messages. In this recipe, we've defined a trace appender, which writes our log messages to System.Diagnostics.Trace. When we debug our application, Visual Studio listens to the trace and copies each message to the debug output window.

Loggers are the source of log messages. The root element defines values for all loggers, which can be overridden using the logger element. In our configuration, we've declared that all messages should be written to the appender named trace.

In log4net, the log messages have priorities. In ascending order, they are DEBUG, INFO, WARN, ERROR, and FATAL. In our configuration, we can define a log level with one of these priorities, or with ALL or OFF. A level includes its priority and all the priorities above it. For example, a level of WARN will also log ERROR and FATAL messages. ALL is equivalent to DEBUG: all messages will be logged, and OFF suppresses all messages.

With our configuration, log4net will write messages from NHibernate with a priority of INFO, WARN, ERROR, and FATAL, and ALL messages from other sources.

We can use log4net in our own application. Here's a simple example of what some code might look like with log4net logging:

using System.IO;
using log4net;
namespace MyApp.Project.SomeNamespace
{

    public class Foo
    {
        private static ILog log = LogManager.GetLogger(typeof(Foo));

        public string DoSomething()
        {
            log.Debug("We're doing something.");
            try
            {
                return File.ReadAllText("cheese.txt");
            }
            catch (FileNotFoundException)
            {
                log.Error("Somebody moved my cheese.txt");
                throw;
            }
        }
    }
}

We've defined a simple class named Foo. In the DoSomething() method, we write the log message, "We're doing something.", with a priority of DEBUG. Then we return the contents of the file cheese.txt. If the file doesn't exist, we log an error and throw the exception.

Because we passed in typeof(Foo) when getting the logger, the Foo logger is named MyApp.Project.SomeNamespace.Foo, similar to the type. This is the typical naming convention when using log4net.

Suppose we were no longer concerned with debug level messages from Foo, but we still wanted to know about warnings and errors. We can then redefine the log level with this simple addition to our configuration, as shown in the following code:

<logger name="MyApp.Project.SomeNamespace.Foo">
  <level value="WARN" />
</logger>

Alternatively, we can set the log level for the entire namespace or even the entire project with this configuration, as follows:

<logger name="MyApp.Project">
  <level value="WARN" />
</logger>

<logger name="NHibernate.SQL">
   <level name="DEBUG" />
</logger>

<appSettings>
  <add key="nhibernate-logger" 
       value = 
"NHibernate.Logging.CommonLogging.CommonLoggingLoggerFactory, NHibernate.Logging.CommonLogging"/>
</appSettings>

Complete the Configuring NHibernate with App.config recipe at the beginning of this chapter.

The hbm2ddl (hibernate mapping to data definition language) tool uses the mapping metadata in the configuration object to build a SQL script of our database objects. It then connects to our database and runs this script. In order to demonstrate the functionality, we added a mapping for TestClass. How mappings are created and used will be further discussed in Chapter 2, Models and Mapping.

Alternatively, we can use the hbm2ddl.auto configuration property to build our database schema automatically whenever our application calls BuildSessionFactory. We can set the property to the following values:

While create-drop is immensely helpful during development, only validate is suggested for production environments, as the tiniest mistake can have huge consequences. Rather, you should script the database, as shown in the next recipe, and run the script explicitly to set up your production database.

Complete the Configuring NHibernate with App.config or Web.config recipe at the beginning of this chapter.

Using the mapping metadata from the configuration object and the current dialect, hbm2ddl builds a SQL script for your entities.

Complete the Configuring NHibernate with App.config or Web.config recipe at the beginning of this chapter.

Using the mapping metadata from the configuration object and the current dialect, hbm2ddl analyzes the existing structure of your database and generates a script to fulfill the differences. The SchemaUpdate only adds missing objects, and does not try to remove anything.

Download the latest release of NHibernate Schema Tool from http://nst.codeplex.com/.

To install NHibernate Schema Tool, follow these steps:

We haven't added any HBM mapping files to the Eg.Core project yet, so no tables will be created. In the next chapter, however, we will go into some depth on how these mappings are created.

NHibernate Schema Tool is a command-line wrapper for the hbm2ddl tool. This makes NST ideal for use in build scripts and continuous integration servers.

The /c argument specifies the configuration file. The /a argument specifies the assembly with our classes and mapping embedded resource files. The /o:Create option tells NHibernate to create our database objects. It also supports Update and Delete.

NST has several options, enabling a number of creative uses. NST supports these command-line options: