In the first part of this series, we saw the basics of what Fluent NHibernate is about. In this second part, we're going to look into relationships and some of the mappings that FNH produces for us, as well as overriding certain mappings.

Relationships

Let's say we have a new requirement that requires all customers to have multiple documents associated with them.

In terms of a relational database world, if we were to have two tables, one representing customers, and the other documents, the result would be:

There would be a foreign key in Document pointing to the customer Id of the Customer.

In an OO world, we don't (or shouldn't) care about how information is persisted. In other words, when designing our classes, all we care about is having a list of documents that is related to a customer:

   1: public class Document 

   2: {

   3:     public virtual int Id { get; private set; }

   4:     public virtual string Code { get; set; }

   5:     public virtual DateTime Date { get; set; }

   6:     public virtual string Author { get; set; }

   7:     public virtual string Contents { get; set; }

   8:  

   9: }

  10:  

  11: public class Customer 

  12:    {

  13:        public virtual int Id { get; private set; }

  14:        public virtual string NameFirst { get; set; }

  15:        public virtual string NameLast { get; set; }

  16:        public virtual string Telephone { get; set; }

  17:        public virtual string Email { get; set; }

  18:  

  19:        public virtual ISet<Document> Documents { get; set; }

  20:  

  21:        public Customer()

  22:        {

  23:            Documents = new HashedSet<Document>();

  24:        }

  25:    }

Our Customer class contains a collection of Documents (line 19). Why is this an ISet as opposed to an IList or ICollection? A set represents an unordered collection of objects that does not allow duplicates*. Having this class layout, let's put it through Fluent NHibernate to see what it spits out.

[* The .NET framework does not come with a type Set. However, all distributions of NHibernate come with the Iesi.Collections assembly, since it's used internally. So you don't have much to worry about.]

Project Layout

Before continuing, let's take a look at our project layout:

We have three projects:

1. Example.Domain which is our application per say. This is where our entities reside.

2. Example.Repository is where our NHibernate repository will eventually be. It is also where our Mapping configuration is located.

3. Example.FluentHelpers is a series of classes that will help with generating the database structure, etc.

The reason that our Mapping file is kept in the repository is two-fold:

1. FluentHelpers can be re-used and is project independent. It knows nothing of specific entities or mappings.

2. Domain should have no reference to the persistence mechanism and as such should not know whether we use NHibernate or any other type of ORM.

Our FluentMapper class is just a wrapper around Fluent Nhibernate and NHibernates tools namespace, with three methods: SaveMappings, CreateDatabase and UpdateDatabase. The SaveMappings exports the mappings Fluent NHibernate creates for us to a specific folder (remember, each class has it's own mapping). The implementation is very straight forward:

   1: public void SaveMappings(string path)

   2: {

   3:     _persistenceModel.WriteMappingsTo(path);    

   4: }

As for our mapping configuration, NHMapping, this is where we'll eventually add specific configurations overriding Fluent NHibernate's default settings. But for now it's just that one line of code. The reason is returns an AutoPersistenceModel is because this is what we pass into our FluentMapper to actually do the work.

   1: public static AutoPersistenceModel GetMapping()

   2: {

   3:     return AutoPersistenceModel.MapEntitiesFromAssemblyOf<Customer>();

   4: }

Generating Mapping Files

Once we put all this code together, we can see the mapping Fluent NHibernate generates for us. To make things easier, I've included a MSBuild task (FluentTask) that does this, along with creating/recreating databases if required (works great as part of an integration test). Here's a sample MSBuild project file to generate the mappings for us:

   1: <?xml version="1.0" encoding="utf-8" ?>

   2: <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

   3:   <UsingTask AssemblyFile="Example.FluentHelpers.dll" TaskName="FluentTask" />

   4:   <Target Name="Default">

   5:     <FluentTask

   6:       PersistenceModel="Example.Repository.dll, Example.Repository.NHMappings, GetMapping" 

   7:       ConnectionString="Data Source=.\SQLEXPRESS;Initial Catalog=FluentExample;Integrated Security=SSPI"

   8:       MappingOutputFolder="C:\Temp"/>

   9:   </Target>

  10: </Project>

For illustrative purposes (i.e. this is NOT needed if you're using Fluent NHibernate), let's see the generated output for our classes:

Customer.hbm

   1: <?xml version="1.0" encoding="utf-8"?>

   2: <hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="Example.Domain, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" namespace="Example.Domain">

   3:   <class name="Customer" table="`Customer`" xmlns="urn:nhibernate-mapping-2.2">

   4:     <id name="Id" type="Int32" column="Id">

   5:       <generator class="identity" />

   6:     </id>

   7:     <property name="NameFirst" type="String">

   8:       <column name="NameFirst" />

   9:     </property>

  10:     <property name="Telephone" type="String">

  11:       <column name="Telephone" />

  12:     </property>

  13:     <property name="Email" type="String">

  14:       <column name="Email" />

  15:     </property>

  16:     <property name="NameLast" type="String">

  17:       <column name="NameLast" />

  18:     </property>

  19:     <set name="Documents">

  20:       <key column="Customer_id" />

  21:       <one-to-many class="Example.Domain.Document, Example.Domain, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

  22:     </set>

  23:   </class>

  24: </hibernate-mapping>

Document.hbm

   1: <?xml version="1.0" encoding="utf-8"?>

   2: <hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="Example.Domain, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" namespace="Example.Domain">

   3:   <class name="Document" table="`Document`" xmlns="urn:nhibernate-mapping-2.2">

   4:     <id name="Id" type="Int32" column="Id">

   5:       <generator class="identity" />

   6:     </id>

   7:     <property name="Author" type="String">

   8:       <column name="Author" />

   9:     </property>

  10:     <property name="Date" type="DateTime">

  11:       <column name="Date" />

  12:     </property>

  13:     <property name="Contents" type="String">

  14:       <column name="Contents" />

  15:     </property>

  16:     <property name="Code" type="String">

  17:       <column name="Code" />

  18:     </property>

  19:   </class>

  20: </hibernate-mapping>

The interesting part is line 19 - 22 of the Customer.hbm. What this is saying is that there is a relationship of one to many from Customer to Document, indicating the class corresponding to Document. It also indicates that the foreign key in the Document table is Customer_id. To create the database, we can add the attribute DatabaseOperation="Create" to our MSBuild task and it will create the database for us:

Overriding specific mappings

As you may have noticed, all of the string types are automatically mapped to nvarchar(255). This is what NHibernate does by default if a length attribute isn't specified in the property mapping. Considering our Contents property for Document requires a larger amount of data to be stored, we need to override this. For these cases, Fluent NHibernate allows you to override a specific mapping of an entity by using the ForTypesThatDeriveFrom method:

   1: public static AutoPersistenceModel GetMapping()

   2: {

   3:      return AutoPersistenceModel.MapEntitiesFromAssemblyOf<Customer>()

   4:          .ForTypesThatDeriveFrom<Document>

   5:            ( m => m.Map(p => p.Contents).WithLengthOf(3000));

   6: }

In this particular case, we're telling Fluent Nhibernate, that when mapping Document (and it's descendants), the property Contents should be mapped with a length of 3000 characters. Any other property not specified will still be mapped using the defaults. Making this change, we'll end up with a database column of type nvarchar(3000), with everything else, exactly the same. 

Summary

In this second part, we defined a relationship between two entities and Fluent NHibernate figured out the rest for us. As we continue with this series, we'll see that as our entity model becomes more complex there are situations where we have to "help" Fluent NHibernate a little bit with the mappings. 

Credits

I'd like to thank James Gregory, not only for the wonderful work he's doing with Fluent NHibernate, but also for reviewing these entries to make sure I haven't said something stupid and give the wrong information to my readers.

A couple of days ago, there was a post by Howard Dierking covering the topic of Fluent NHibernate. What caught my attention was one of the comments:

I find this a little weird... isn't it so that in general, nhibernate supporters loath the 'domain model following the database tables' approach, while to get automapping, you practically have to? ;)

About the PI issue: there's no such thing as persistance ignorance: whatever persistence logic you're using, it bleeds into your own code one way or the other, be it a base class, be it requirements how to define properties/members, be it how to deal with 2-sided relationships etc.

 

I want to focus the following series of posts on showing what Fluent-NHibernate (NHibernate) is truly about, and let you be the judge of whether the previous comment is correct or not. My stand on it is that it's not.

So without further ado, let's start by the basics.

[Note: Due to time limitations and also to keep posts short, I will try and focus on small sections on each post]

NHibernate 101 in one paragraph

For those new to NHibernate, it is an ORM framework (Object Relation Mapper). ORM's try and eliminate the impedance mismatch that exists between Object Orientated programming and Relational Databases. This allows developers to work with objects and not have to worry about how these objects are persisted to disk in a relational database (i.e. tables, joins, etc.). Other examples of ORM's include LLibGenPro, Linq to Sql, and of course Entity Framework (although some people claim that EF is MORE than a ORM, but each to their ow).

Mapping in NHibernate

One of the main problems with any ORM is that there is considerable amount of time spent mapping objects to their corresponding tables in a database. Imagine the following class:

   1: public class Customer 

   2: {

   3:     public virtual int Id { get; private set; }

   4:     public virtual string NameFirst { get; set; }

   5:     public virtual string NameLatst { get; set; }

   6:     public virtual string Telephone { get; set; }

   7:     public virtual string Email { get; set; }

   8: }

This needs to be stored in the database somehow, and to do so, the framework (in our case NHibernate), needs to know how to match objects to tables and properties to columns. To solve this, NHibernate uses the concept of mapping files (hbm), which are non other than XML files with specific tags:

   1: <?xml version="1.0" encoding="utf-8" ?>  

   2:  <hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"  

   3:    namespace="Examples.Domain" assembly="Examples.Domain">  

   4:  

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

   6:      <id name="Id">  

   7:       <generator class="identity" />  

   8:      </id>  

   9:      <property name="NameFirst"/>  

  10:      <property name="NameLast"/>  

  11:      <property name="Telephone"/>  

  12:     <property name="Email"/>  

  13:  </class>  

  14:</hibernate-mapping>  

The configuration is pretty self-explanatory. You define the name of the class, the corresponding table name you want in the database, and then start to define a series of properties. NHibernate follows a series of conventions, so for example if a column attribute is not specified in the property element, the corresponding column name in the database table will be the same as that of the property. The same thing happens with the type of the property, again, NHibernate internally maps CLR types to database types.

One of the problems with this type of mapping is that you don't get type-safety. If you make a mistake in writing out a column name you won't know of the issue until runtime. The other problem occurs when you are trying to refactor your code. If you don't have special add-ons such as Resharper (and if you don't, what are you waiting for?), refactoring XML files is pretty much a no-no in Visual Studio. Imagine the scenario: you rename NameFirst to FirstName and forget to do it in your mapping file. Your application will still compile, but come runtime, kaboom!

Fluent-NHibernate 

This is where Fluent-NHibernate enters the picture. This project was initially built to allow for developers to map their entities to tables in code, i.e. using C#.

   1: 1. public class Customer : ClassMap<Customer>  

   2: 2. {  

   3: 3.   public Customer()  

   4: 4.   {  

   5: 5.     Id(x => x.Id);  

   6: 9.     Map(x => x.NameFirst);  

   7: 9.     Map(x => x.NameLast);  

   8: 9.     Map(x => x.Telephone);  

   9: 9.     Map(x => x.Email);  

  10: 2.   }  

  11: 3. }  

Already this provides benefits. By allowing this, you get away from the magic strings in the mapping files, allowing not only for compile-time checking but also refactoring.

However, one thing still remains, mapping. You still have to map your classes. Now, during both the mapping using XML as well as C#, have you noticed one thing? A series of assumptions are made. We said previously that you don't need to specific column names or types, etc. These are conventions. NHibernate assumes a series of conventions. Following the 80/20 rule, assuming that 80% of the time these conventions suit our applications, there's a remaining 20% that would  need some sort of adjustment.

Auto Persistence Model

Say Hello to the Auto Persistence Model in Fluent-NHibernate. By latching on to the concept of convention over configuration, the Auto Persistence facilities in Fluent-Nhibernate do the mapping for you. This makes a series of decisions and maps your classes to their corresponding database tables and columns. Yet at the same time it  allows you to tweak these conventions. This then gives us 100% coverage. For 80% of the time, the APM is fine, and for those special cases we adjust the conventions to our needs. Here is the same mapping using the Auto Persistence Model in Fluent-NHibernate:

   1: AutoPersistenceModel.MapEntitiesFromAssemblyOf<Customer>().Configure(config);

AutoPersistenceModel has a static method MapEntitiesFromAssemblyOf where you pass in a specific type. Since my current example only has one type, namely Customer, I'm passing this one in. It takes this assembly and loads all the types it contains and create the NHibernate mappings for you. It places these mappings into a NHibernate Configuration class (the config parameter).

So far, the code for the simple example project is limited to the Customer class and the single isolated line of code that generates the mapping using Fluent-NHibernate's Auto Persistence Model. However, on it's own it's pretty useless. We need to somehow tie it to a database (that doesn't exist yet) so that we can actually make use of it. To do so, we create a Mapper class that generates the mappings and returns the NHibernate configuration:

   1: public static class Mapper 

   2:    {

   3:  

   4:        public static Configuration GenerateMapping(string connectionString)

   5:        {

   6:            var config = MsSqlConfiguration.MsSql2005

   7:                .ConnectionString(c => c.Is(connectionString))

   8:                .ConfigureProperties(new Configuration());

   9:  

  10:            AutoPersistenceModel.MapEntitiesFromAssemblyOf<Customer>().Configure(config);

  11:  

  12:            return config;

  13:  

  14:        }

  15:  

  16:    }

What this class is doing, is create a NHibernate configuration that is based on Microsoft SQL Server (2005 and up) and configures a series of default properties. The only parameter it requires is the connection string. It generates the the mapping files and returns the configuration to us. Next step is to make use of this configuration. Remember, right now we have the mappings, but we don't actually have any underlying database. We don't know anything about how the structure is or should be.

Creating the database

In the NHibernate framework, there is a namespace called hbm2ddl which as it's name indicates, can create DDL from mapping files. That is precisely what we need. To use it, it's as simple as passing in a NHibernate configuration to the SchemaExport class:

   1: using NHibernate.Tool.hbm2ddl;

   2:  

   3: namespace Example.DBGenerator {

   4:  

   5:     

   6:     class Program 

   7:     {

   8:         static void Main(string[] args) 

   9:         {

  10:             var config = Mapper.GenerateMapping(args[0]);

  11:  

  12:             new SchemaExport(config).SetOutputFile(args[1]).Create(/* Output to console */ false, /* Execute script against database */ true);

  13:         }

  14:     }

  15: }

Ignoring the fact that there is absolutely no error checking in this application whatsoever, all we are doing is taking the our configuration generated by the mapper and passing it to our SchemaExport class, which is calling the Create method to create the SQL, dump it into a file and at the same time, generate it for us in SQL Server. Running this executable with the following command line:

"Data Source=.\SQLEXPRESS;Initial Catalog=FluentExample;Integrated Security=true" Output.sql

we get:

Summary

In this first post, I wanted to show you how you can easily create a domain model and have the corresponding database created for you automatically, without having to worry about any types of mappings, let alone database structures. However, I've only touched the tip of the iceberg. In the next series of posts, we'll drill down into everything Fluent-NHibernate has to offer us.

Coming back to the original comment, what do you think? Did I start with my domain object or my database? This is what true persistence ignorance is about!