In our Visual Studio solution, we already have a project named Domain that holds all our domain entities. Let's create another project of type Class Library named Persistence. We will add our XML mappings in this project. Follow the steps listed next to set yourself up for your XML mappings tour:

Every mapping must be named such that the name ends with .hbm.xml. Lot of developers follow a convention to name the files as <Entity name>.hbm.xml for simplicity and readability. For instance, XML mapping file for the Employee class would be named Employee.hbm.xml. But this is not a prerequisite and you are free to name your mapping files whatever you like, as long as they end with .hbm.xml.

One of the greatest powers of Visual Studio comes from its IntelliSense feature. As a long time user of Visual Studio (and ReSharper), I find it uncomfortable when IntelliSense does not work for some non-standard files. Fortunately for XML mappings, NH's authors have provided XSD files that will enable IntelliSense. Follow the steps listed next to enable IntelliSense for your XML mapping files. For these instructions, I am assuming that a file named Employee.hbm.xml is added to your project.

With that, your development environment should be ready for working with XML mappings. So let's start with mapping the Employee class.

To verify that mappings are correct and they map to the database table as per our expectations, we will create an instance of the Employee class and save it to an in-memory database. We will then retrieve the instance we just saved and confirm that all the attribute values we had saved are retrieved from the database. Add a new class to project Tests.Unit and call it InMemoryDatabaseForXmlMappings. Use the following code snipped to define the class:

using System;
using NHibernate;
using NHibernate.Cfg;
using NHibernate.Dialect;
using NHibernate.Driver;
using NHibernate.Tool.hbm2ddl;
using Environment = NHibernate.Cfg.Environment;

namespace Tests.Unit
{
  public class InMemoryDatabaseForXmlMappings : IDisposable
  {
    protected Configuration config;
    protected ISessionFactory sessionFactory;

    public InMemoryDatabaseForXmlMappings()
    {
      config = new Configuration()
      .SetProperty(Environment.ReleaseConnections, "on_close")
      .SetProperty(Environment.Dialect, typeof (SQLiteDialect).AssemblyQualifiedName)
      .SetProperty(Environment.ConnectionDriver, typeof (SQLite20Driver).AssemblyQualifiedName)
      .SetProperty(Environment.ConnectionString, "data source=:memory:")
      .AddFile("Mappings/Xml/Employee.hbm.xml");

      sessionFactory = config.BuildSessionFactory();

      Session = sessionFactory.OpenSession();

      new SchemaExport(config).Execute(true, true, false, Session.Connection, Console.Out);
    }

    public ISession Session { get; set; }

    public void Dispose()
    {
      Session.Dispose();
      SessionFactory.Dispose();
    }
  }
}

As you can see, there is a lot going on here. Let me give you a brief explanation of what the preceding code is doing. In the constructor of the class, we have created an instance of NH Configuration object and have set different configuration values. These properties tell NHibernate what kind of database we are going to use and where NHibernate can find this database. An important point to note is that we are using an in-memory version of SQLite database. We then add the Employee.hbm.xml file to configuration to let NHibernate know that this file contains the mappings for the Employee entity. Note that adding the mapping XML file directly to configuration file is one of the ways of configuring mappings. NHibernate supports several different ways which we will cover in more detail in the next chapter. We then create an instance of session object. If you remember from Chapter 1, Introduction to NHibernate, session object is what lets us connect to the database. The last line which uses the SchemaExport class, will use the mappings supplied to configuration and build database schema into the in-memory database. This database schema is built based on the mappings we would declare. I am sure this is information overload for you at this time but feel free to ignore all the details and just remember that this class lets us use an in-memory database for our tests. In the next chapter, we are going to take a look at NHibernate configuration in detail.

With the configuration sorted out, let's look at our first test. Since we are only going to map primitive properties on the Employee class, our first test is going to be about verifying that primitive properties of the Employee class are saved correctly in the database. Add a new folder named Mappings to the project Test.Unit. In this folder, add a new class named EmployeeMappingsTests. Add a method named MapsPrimitiveProperties to this class, as shown next:

using System;
using Domain;
using NHibernate;
using NUnit.Framework;

namespace Tests.Unit.Mappings.Xml
{
  [TestFixture]
  public class EmployeeMappingsTests
  {
    private InMemoryDatabaseForXmlMappings database;
    private ISession session;

    [TestFixtureSetUp]
    public void Setup()
    {
      database = new InMemoryDatabaseForXmlMappings();
      session = database.Session;
    }

    [Test]
    public void MapsPrimitiveProperties()
    {
      object id = 0;
      using (var transaction = session.BeginTransaction())
      {
        id = session.Save(new Employee
          {
            EmployeeNumber = "5987123",
            Firstname = "Hillary",
            Lastname = "Gamble",
            EmailAddress = "[email protected]",
            DateOfBirth = new DateTime(1980, 4, 23),
            DateOfJoining = new DateTime(2010, 7, 12),
            IsAdmin = true,
            Password = "Password"
          });
          transaction.Commit();
      }

      session.Clear();

      using (var transaction = session.BeginTransaction())
      {
        var employee = session.Get<Employee>(id);
        Assert.That(employee.EmployeeNumber, Is.EqualTo("5987123"));
        Assert.That(employee.Firstname, Is.EqualTo("Hillary"));
        Assert.That(employee.Lastname, Is.EqualTo("Gamble"));
        Assert.That(employee.EmailAddress, Is.EqualTo("[email protected]"));
        Assert.That(employee.DateOfBirth.Year, Is.EqualTo(1980));
        Assert.That(employee.DateOfBirth.Month, Is.EqualTo(4));
        Assert.That(employee.DateOfBirth.Day, Is.EqualTo(23));
        Assert.That(employee.DateOfJoining.Year, Is.EqualTo(2010));
        Assert.That(employee.DateOfJoining.Month, Is.EqualTo(7));
        Assert.That(employee.DateOfJoining.Day, Is.EqualTo(12));
        Assert.That(employee.IsAdmin, Is.True);
        Assert.That(employee.Password, Is.EqualTo("Password"));
        transaction.Commit();
      }
    }
  }
}

We have a method named Setup in which we create an instance of InMemoryDatabaseForXmlMappings and get hold of the session object. We use this session to store the instance of the Employee object that we have created. Ignore the call to method BeginTransaction for now. After saving the employee instance, session is cleared in order to remove any traces of employee instance from previous database operation. We then use the same session object to load the employee record that we just saved and verify that properties on the loaded instance have same values as we had set previously.

If you run this test now, it would fail for obvious reasons. We have not added any mappings yet. Let's go ahead and start writing mappings for the properties we are testing above.

In the previous section, we have seen that XML mappings are written in a file with an extension .hbm.xml. In case of the Employee class, this would be Employee.hbm.xml. Following is how primitive properties of the Employee class would be mapped:

<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="Domain" namespace="Domain">
  <class name="Employee">
    <id name="Id" generator="hilo" />
    <property name="EmployeeNumber" />
    <property name="Firstname" />
    <property name="Lastname" />
    <property name="EmailAddress" />
    <property name="DateOfBirth" />
    <property name="DateOfJoining" />
    <property name="IsAdmin" />
    <property name="Password" />
  </class>
</hibernate-mapping>

Let's try to understand the purpose of different XML elements in the preceding code:

If we run our test now, it should pass happily.

What we have seen above is the absolute minimum that NHibernate needs declared in order to make mappings work. But there are more attributes available for each of the elements we discussed previously. These attributes let us control mappings to a great level of detail. NHibernate assumes safe defaults when these attributes are not declared. Let's take a look at some of the important and most useful optional attributes of each of these elements.

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"
  schema="EB"
  default-cascade="delete-all-orphan"
  assembly="Domain"
  namespace="Domain"
  default-access="property"
  default-lazy="true">

<class name="Employee"
  table="employees"
  mutable="true"
  schema="EB"
  lazy="true">

<property
  name="EmployeeNumber"
  column="employment_number"
  type="System.String"
  length="10"
  not-null="true"
  unique="true"
  lazy="false"
  mutable="true"/>