Last time we introduced setting up the configuration file. This time we will look at the basics of mapping.

Mapping Entities

How you map your entities depends upon your preferred approach.

Attributes or mapping files

You can use either attributes on classes, or an xml based mapping file to map between a class and a table. Attributes are less verbose than xml files because you only need to say how to map to the Db, not what object you are mapping. Some people also prefer them because they dislike managing xml files. At the same time the issue with attributes files is that they do not enforce a clean seperation of concerns. The domain should not know how it is persisted.

Data First or Domain First

If you are 'data-first' or you have a legacy schema to support then you may want to generate your entity classes from the domain model. There are a number of templates and tools that could help you.

If you are domain first then you build your domain and then generate the data schema from it. You can use the SchemaExport class to create an initial cut of the schema by calling its Execute method. You can also use Export to create an update schema. This model works well with ideas like Test-Driven Development and Incremental Re-architecture as it allows you to keep rebuilding your schema

NHibernate mapping - the basics

Let's talk about xml based mapping, it's the oldest and the cleanest, and the other methods are pretty easy to figure out once you have that one resolved.

We'll use a simple model so we can focus on introducing mapping, instead of delving into its depths.

If you are going to be working on mapping then you should copy the schemas so that Visual Studio can provide you with intellisense:

Copy nhibernate-configuration.xsd, nhibernate-mapping.xsd, and nhibernate-generic.xsd to the Visual Studio schemas directory.  By default, the schemas directory is C:\Program Files\Microsoft Visual Studio 9\Xml\Schemas.

We have a customer

    public class Customer

    {

        public Company company { get; set; }

        public DateTime? DateOfBirth { get; set; }

        public string FirstName {get;set;}

        public int Id { get; set; }

        public string Surname {get;set;}

        public int Version { get; set; }

    }

And a company

    public class Company

    {

        private ISet<Customer> customers = new HashedSet<Customer>();

        public int Id { get; set; }

        public string Name { get; set; }

        public IList<Customer> customers

        {

            get { return customers; }

            set

            {

                customers = value;

            }

        }

    }

Note that we use ISet for the collection type. Most ORM tools require us to do something similar to support lazy loading: use an interface instead of a concrete type so that the framework can swap in a proxied collection which in turn asks the ORM to load the data on demand.

Also note that we are mapping a nullable type. NHibernate supports nullable types, particularly useful in the case of DateTime which otherwise generates a date that SQL Server will not accept.

We can create a mapping file to map these tables to a Db. The convention is to have one mapping file per entity, named after the entity and with the extension *.hbm.xml. Remember to make sure that you make your *.hbm.xml file an embedded resource. We usually associate the resource with the class in the same assembly.

The mapping file

We need to tell NHibernate that it is an xml mapping file:

<?xml version="1.0"?>

and then we need to configure NHibernate itself

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="NHibernateDemo" namespace="NHibernateDemo.Domain" default-lazy="false">

</hibernate-mapping>

Note that we need to check that we are using the create version of the schema for the version of NHibernate we are building to. In this case we are building to version 2.2 of the schema and working against the trunk of NHibernate.

Note that we have turned off lazy loading by default. NHibernate 2.0 turns on lazy-loading by default, which would means that your classes need to have virtual methods and properties so that they can be replaced by a proxy. For now we switch this off. We can still set it for a relation or class explicitly.

The assembly and namespace attributes are a convenience to save us re-typing them every time.

Mapping a class

Next we map the class

<class name="Customer" table="Customer">

</class>

We mainly need to map a class to a table, if we don't have a table yet this is where we name it. We can also define some options at this level. We can set cascade and lazy-load options for the class and optimize how update statements are generated. For now we can leave these to focus on how we map, tweaking them later. It is worth pointing out that NHibernate is optimized for using a version field to support optimistic locking.

In order to lazy load a class (as opposed to an association) then we need to make the methods and properties of the class virtual (so that NHibernate can generate a proxy to wrap our class, that asks for the concrete class to be loaded when we need it).

Mapping the Entity's Identity Column

All entities must have a unique identifier, that is consistent throughout their lifetime, which the Db represents as a primary key. We denote an id mapping by using the <id/> element. We set the name of the id property on the class. Again there is a range of mapping options, for example setting the default value for new, unsaved entities, so that we, and NHibernate, can easily recognize unsaved entities.

We need to use the <generator/> element within the <id/> element to indicate how we create new id numbers when we persist. For databases which support identity columns (DB2, MySQL, Sybase, MS SQL), you may use identity key generation. For databases that support sequences (DB2, Oracle, PostgreSQL, Interbase, McKoi, SAP DB) you may use sequence style key generation.

Mapping the entity version

NHibernate recommends using a <version/> element for optimistic concurrency support (as opposed to field-by-field comparison or a timestamp).

  <class name="Customer" table="Customer">

  <id name="Id" type="Int32" unsaved-value="0">

      <generator class="identity"/>

    </id>

    <version name="Version">

    </version>

 </class>

 Mapping a property

We map a property to a field by using the <property> element. We can just supply the property name, though once again there are options, for example to exclude fields that we never update (i.e. read-only) or to assign a calculated value.

  <class name="Customer" table="Customer">

    <id name="Id" type="Int32" unsaved-value="0">

      <generator class="identity"/>

    </id>

    <version name="Version"/>

    <property name="DateOfBirth"/>

    <property name="FirstName"/>

    <property name="Surname"/>

 </class>

Next time we'll look at mapping relationships using NHibernate.