NHibernate for Entity Framework Developers: Part 1 – Fluent NHibernate

What is the Goal of This Post?

A Note For Those Who Never Worked with Any ORM Before

Your First NHibernate Project

1. Right-click the project and select Add Reference...
2. Click the Browse... button and navigate to the folder where NHibernate binaries are extracted.
3. Open Required_Bins folder and select NHibernate.dll. Click OK to add this reference to your project.
4. Right-click again on the the project and select Add Reference... and navigate to the folder where NHibernate binaries are extracted.
5. This time open Required_For_LazyLoading folder and then Castle folder.
6. Add a reference to NHibernate.ByteCode.Castle.dll.

Creating a Domain Model

public class User
{
    public User()
    {
        Items = new List<Item>();
    }
 
    public virtual int UserId { get; private set; }
    public virtual string Name { get; set; }
    public virtual string Username { get; set; }
 
    public virtual Address Address { get; set; }
    public virtual IList<Item> Items { get; set; }
 
    public virtual void AddItem(Item item)
    {
        item.Seller = this;
        Items.Add(item);
    }
}
 
public class Address
{
    public virtual string Steet { get; set; }
    public virtual string City { get; set; }
    public virtual string ZipCode { get; set; }
}
 
public class Item
{
    public Item()
    {
        Categories = new List<Category>();
    }
 
    public virtual int ItemId { get; private set; }
    public virtual string Name { get; set; }
    public virtual double Price { get; set; }
 
    public virtual User Seller { get; set; }
    public virtual IList<Category> Categories { get; set; }
}
 
public class Category
{
    public Category()
    {
        Items = new List<Item>();
    }
 
    public virtual int CategoryId { get; private set; }
    public virtual string Name { get; set; }
 
    public virtual IList<Item> Items { get; set; }
 
    public virtual void AddItem(Item item)
    {
        item.Categories.Add(this);
        Items.Add(item);
    }
}

How Mappings are Specified in NHibernate?

• Mapping using XML
The ability of mapping classes with XML is what NHibernate inherits from Hibernate, where usually each persistent class has an XML mapping file ends with the .hbm.xml extension and is embedded in the same assembly as the mapped class file. This is analogous to an EF's Edmx file but unlike Edmx files, these HBM mapping documents are lightweight, human readable, easily hand-editable and can be easily manipulated by version-control systems. Although Visual Studio comes with a designer support for Edmx files, but the problem is that this support is somewhat limited and you sometimes have to drill down to the underlying XML file to define your desired mapping or behavior, examples like creating a TPC mapping or defining QueryViews. I personally didn't find editing the raw XMLs in Edmx files (and dealing with an Edmx file in general) a fun practice and I think this is a common feeling throughout the community as we see more and more developers are leaning toward Code First development to keep their projects away from an Edmx file.
• Attribute-oriented Mapping
Alternatively, you can use CLR attributes defined in the NHibernate.Mapping.Attributes library to provide all the information NHibernate needs to map your classes. This is comparable to the new attributes that the latest release of EF (EF 4.1) provides in System.ComponentModel.DataAnnotations namespace which you can use to map your classes when doing EF Code First development except that EF annotations are not complete and you often have to resort to fluent API to do the mappings (Examples like creating a TPC mapping, customizing a TPH mapping, specifying cascade deletes on associations or customizing the mapping for a many-to-many association.).
• Fluent Mapping
Fluent mapping is based on a Fluent Interface that allows you to map your entities completely in code, with all the compile-time safety and refactorability that it brings. Just like the fluent API in EF Code First, Fluent NHibernate project provides an alternative to NHibernate's standard XML mapping files. As a result, rather than writing XML documents, you write mappings in strongly typed C# (or VB) code. It's even has a concept called Auto Mapping which is a mechanism for automatically mapping all your entities based on a set of conventions. This is very similar to the EF Code First as they both follow the convention over configuration principle. In this post we use Fluent NHibernate to map our persistent classes since this allows for easy refactoring, improved readability and more concise and elegant code. More importantly, if you used Code First fluent API before, you'll find this approach very familiar.

Mapping Entities and Components

class UserMap : ClassMap<User>
{
    public UserMap()
    {
        Id(u => u.UserId);           
        Component(u => u.Address);
    }
}

Associations in Entity Framework and NHibernate

Associations in NHibernate are Directional

public class ItemMap : ClassMap<Item>
{
    public ItemMap()
    {
        Id(i => i.ItemId);
        Map(i => i.Name);
        Map(i => i.Price);
 
        References(i => i.Seller)
            .Column("UserId")
            .Not.Nullable();                
    }
}

Making the Association Bidirectional

public class UserMap : ClassMap<User>
{
    public UserMap()
    {
        Id(u => u.UserId);
        Map(u => u.FullName).Length(50);
        Map(u => u.UserName).Not.Nullable().Unique();
 
        Component(u => u.Address);
 
        HasMany(u => u.Items)
            .Cascade.All()
            .Inverse()
            .KeyColumn("UserId");
    }
}

Mapping a Many-to-Many Association

public class CategoryMap : ClassMap<Category>
{
    public CategoryMap()
    {
        Id(c => c.CategoryId);            
        Map(c => c.Name);
                        
        HasManyToMany(c => c.Items)
            .Cascade.All()
            .Table("ItemCategory");
    }
}

public class ItemMap : ClassMap<Item>
{
    public ItemMap()
    {
        Id(i => i.ItemId);
        Map(p => p.Name);
        Map(i => i.Price);
                        
        References(i => i.Seller)
            .Column("UserId")
            .Not.Nullable();
            
        HasManyToMany(i => i.Categories)
            .Cascade.All()
            .Inverse()
            .Table("ItemCategory");
    }
}

NHibernate Configuration and Schema Generation

ISessionFactory factory = Fluently.Configure()
        .Database(MsSqlConfiguration.MsSql2008
                .ConnectionString(c => 
                        c.FromConnectionStringWithKey("SQLExpress")))
        .Mappings(m => m.FluentMappings.AddFromAssemblyOf<Program>())
        .ExposeConfiguration(config => 
        {
            SchemaExport schemaExport = new SchemaExport(config);
            schemaExport.Drop(true, true);
            schemaExport.Create(true, true);
        })
        .BuildSessionFactory();

SQL Schema

Source Code

Summary