Fluent NHibernate

Auto Mapping Conventions

Fri, 10 Apr 2009 04:19:42 Z

Auto mappings are generated based on a set of conventions, assumptions about your environment, that mean you can map your entire domain with a miniscule amount of code. Sometimes however, the conventions we supply are not to your liking, perhaps you're a control freak and want 100% control, or more likely you're working against an existing database that has it's own set of standards. You'd still like to use the auto mapper, but can't because it maps your entities all wrong.

Luckily for you we've thought about that, you can customise the conventions that the auto mapper uses. To see more about conventions in general, read the Conventions page.

We'll continue with our store example from before (in Auto Mapping), which comprised of a Product and a Shelf.

public class Product  
{  
  public int Id { get; private set; }  
  public virtual string Name { get; set; }  
  public virtual decimal Price { get; set; }  
}  

public class Shelf  
{  
  public virtual int Id { get; private set; }  
  public virtual IList<Product> Products { get; private set; }  

  public Shelf()
  {
    Products = new List<Product>();
  }
}

Using the standard auto mapping conventions, this assumes a database schema like so:

table Product (
  Id int identity primary key,
  Name varchar(100),
  Price decimal,
  Shelf_id int foreign key
)

table Shelf (
  Id int identity primary key
)

Nothing too complicated there. The auto mapper has correctly assumed that our Ids are identity's and are primary keys, it's also assumed their names, the name of our foreign key to the Shelf table (ShelfId), and the length of our Name column.

Lets assume for the sake of this post that you're not happy with that schema. You're one of those people that prefers to name their primary key after the table it's in, so our Product identity should be called ProductId; also, you like your foreign key's to be explicitly named _FK, and your strings are always a bit longer than 100.

Remember this fellow?

AutoPersistenceModel.MapEntitiesFromAssemblyOf<Product>()  
  .Where(t => t.Namespace == "Storefront.Entities");

Lets update it to include some convention overrides. We'll start with the Id name. The conventions we're about to implement are better explained in the Conventions wiki.

AutoPersistenceModel.MapEntitiesFromAssemblyOf<Product>()
  .Where(t => t.Namespace == "Storefront.Entities")
  .ConventionDiscovery.Add<PrimaryKeyConvention>();

We've added a convention to the convention discovery mechanism, now let's implement it.

public class PrimaryKeyConvention
  : IIdConvention
{
  public bool Accept(IIdentityPart id)
  {
    return true;
  }

  public void Apply(IIdentityPart id)
  {
    id.ColumnName(id.Property.ReflectedType.Name + "Id");
  }
}

Our PrimaryKeyConvention gets applied to all Ids, and sets their column name based on the ReflectedType of the Id property. This is a fancy way of saying get the name of the class the Id property is in. Our primary key's will now be generated as TypeNameId; which means our schema now looks like this:

table Product (
  ProductId int identity primary key,
  Name varchar(100),
  Price decimal,
  Shelf_id int foreign key
)

table Shelf (
  ShelfId int identity primary key
)

As you can see, our primary key's now have our desired naming convention. Lets do the other two together, as they're so simple; we'll override the foreign key naming, and change the default length for strings.

.ConventionDiscovery.Setup(c =>
  c.Add<PrimaryKeyConvention>();
  c.Add<ForeignKeyConvention>();
  c.Add<DefaultStringLengthConvention>();
});

public class ForeignKeyConvention
  : IHasManyConvention
{
  public bool Apply(IOneToManyPart part)
  {
    return true;
  }

  public void Accept(IOneToManyPart part)
  {
    part.WithKeyColumn(part.ParentType.Name + "_FK");
  }
}

public class DefaultStringLengthConvention
  : IPropertyConvention
{
  public bool Apply(IProperty property)
  {
    return true;
  }

  public void Accept(IProperty property)
  {
    property.WithLengthOf(250);
  }
}

That's all there is to it, when combined with the other conventions you can customise the mappings quite heavily while only adding a few lines to your auto mapping.

This is our final schema:

table Product (
  ProductId int identity primary key,
  Name varchar(250),
  Price decimal,
  Shelf_FK int foreign key
)

table Shelf (
  ShelfId int identity primary key
)

To see more about conventions, read the Conventions and Converting To New Style Conventions pages.

What next? Auto Mapping Type Conventions

Standard Mapping

Thu, 09 Apr 2009 23:12:04 Z

Fluent Mapping
Introduction
ClassMap<T>
Ids
Properties
Relationships
Components
Conventions
Private Properties

Fluent NHibernate has two mapping styles: Auto Mapping and Standard Mapping (aka non-auto mapping, or just fluent mapping). This page is about the latter.

The GettingStarted: First Project example uses fluent mapping for its mappings, so you should refer to that if you've not done any work mappings before; if you're looking for some more complex examples then this is the place.

You can read about the ClassMap<T>, mapping properties, mapping relationships and more from the right hand menu.

For a growing collection of common mapping situations, have a look at Mapping Patterns.

Getting Started: First Project

Mon, 30 Mar 2009 22:38:10 Z

Getting Started
Introduction
Install
First Project

All the source can be found in the main Fluent NHibernate solution, in the Example.FirstProject project.

You need to have Fluent NHibernate already downloaded and compiled to follow this guide, if you haven't done that yet then please refer to GettingStarted: Install.

For this example we're going to be mapping a simple domain for a retail company. The company has a couple of stores, each with products in (some products are in both stores, some are exclusive), and each with employees. In database terms, that's a Store, Employee, and Product table, with a many-to-many table between Store and Product.

First, create a console application and reference the FluentNHibernate.dll you built earlier, and whichever version of NHibernate.dll you built against (if you're unsure, just use the one that's output with FluentNHibernate.dll); also, because for this example we're going to be using a SQLite database, you'll need the System.Data.SQLite library which is distributed with Fluent NHibernate.

You can see the project structure that I used to the left. The Entities folder is for your actual domain objects, while the Mappings folder is where we're going to put your fluent mapping classes.

For the rest of this guide I'm going to assume you've used the same structure.

The entities

Now that we've got our project setup, lets start by creating our entities. We've got three tables we need to map (we're ignoring the many-to-many join table right now), so that's one entity per table. Create the following classes in your Entities folder.

Entities/Employee.cs

public class Employee
{
  public virtual int Id { get; private set; }
  public virtual string FirstName { get; set; }
  public virtual string LastName { get; set; }
  public virtual Store Store { get; set; }
}

Our Employee entity has an Id, the person's name (split over FirstName and LastName), and finally a reference to the Store that they work in.

There's two things that may stand out to you if you're unfamiliar with NHibernate. Firstly, the Id property has a private setter, this is because it's only NHibernate that should be setting the value of that Id. Secondly, all the properties are marked virtual; this is because NHibernate creates "proxies" of your entities at run time to allow for lazy loading, and for it to do that it needs to be able to override the properties.

Entities/Product.cs

public class Product
{
  public virtual int Id { get; private set; }
  public virtual string Name { get; set; }
  public virtual double Price { get; set; }
  public virtual IList<Store> StoresStockedIn { get; private set; }

  public Product()
  {
    StoresStockedIn = new List<Store>();
  }
}

Product has an Id, it's Name, Price, and a collection of Stores that stock it.

Entities/Store.cs

public class Store
{
  public virtual int Id { get; private set; }
  public virtual string Name { get; set; }
  public virtual IList<Product> Products { get; set; }
  public virtual IList<Employee> Staff { get; set; }

  public Store()
  {
    Products = new List<Product>();
    Staff = new List<Employee>();
  }

  public virtual void AddProduct(Product product)
  {
    product.StoresStockedIn.Add(this);
    Products.Add(product);
  }

  public virtual void AddEmployee(Employee employee)
  {
    employee.Store = this;
    Staff.Add(employee);
  }
}

Finally, we've got our Store entity. This has an Id and a Name, along with a collection of Products that are stocked in it, as well as a collection of Employees (in the Staff list) that work there. This entity has a little bit of logic in it to make our code simpler, that's the AddProduct and AddEmployee methods; these methods are used to add items into the collections, and setup the other side of the relationships.

If you're an NHibernate veteran then you'll recognise this; however, if it's all new to you then let me explain: in a relationship where both sides are mapped, NHibernate needs you to set both sides before it will save correctly. So as to not have this extra code everywhere, it's been reduced to these extra methods in Store.

The mappings

Now that we've got our entities created, it's time to map them using Fluent NHibernate. We'll start with the simplest class, which is Employee. All the following mappings should be created inside the Mappings folder.

To map an entity, you have to create a dedicated mapping class (typically this follows the naming convention of EntityNameMap), so we'll create an EmployeeMap class; these mapping classes have to derive from ClassMap<T> where T is your entity.

Mappings/EmployeeMap.cs

public class EmployeeMap : ClassMap<Employee>
{

}

The mappings themselves are done inside the constructor for EmployeeMap, so we need to add a constructor and write the mappings.

public class EmployeeMap : ClassMap<Employee>
{
  public EmployeeMap()
  {
    Id(x => x.Id);
  }
}

To start with we've mapped the Id column, and told Fluent NHibernate that it's actually an identifier. The x in this example is an instance of Employee that Fluent NHibernate uses to retrieve the property details from, so all you're really doing here is telling it which property you want your Id to be. Fluent NHibernate will see that your Id property has a type of int, and it'll automatically decide that it should be mapped as an auto-incrementing identity in the database - handy!

For NHibernate users, that means it automatically creates the generator element as identity.

Lets map the rest of Employee.

public class EmployeeMap : ClassMap<Employee>
{
  public EmployeeMap()
  {
    Id(x => x.Id);
    Map(x => x.FirstName);
    Map(x => x.LastName);
    References(x => x.Store);
  }
}

There are a couple of new methods we've used there, Map and References; Map creates a mapping for a simple property, while References creates a many-to-one relationship between two entities. In this case we've mapped FirstName and LastName as simple properties, and created a many-to-one to Store (many Employees to one Store) through the Store property.

NHibernate users: Map is equivalent to the property element and References to many-to-one.

Lets carry on by mapping the Store.

Mappings/StoreMap.cs

public class StoreMap : ClassMap<Store>
{
  public StoreMap()
  {
    Id(x => x.Id);
    Map(x => x.Name);
    HasMany(x => x.Staff)
      .Inverse()
      .Cascade.All();
    HasManyToMany(x => x.Products)
     .Cascade.All()
     .WithTableName("StoreProduct");
  }
}

Again, there's a couple of new calls here. If you remember back to Employee, we created a many-to-one relationship with Store, well now that we're mapping Store we can create the other side of that relationship. So HasMany is creating a one-to-many relationship with Employee (one Store to many Employees), which is the other side of the Employee.Store relationship. The other new method is HasManyToMany, which creates a many-to-many relationship with Product.

You've also just got your first taste of the fluent interface Fluent NHibernate provides. The HasMany method has a second call directly from it's return type (Inverse()), and HasManyToMany has Cascade.All() and WithTableName; this is called method chaining, and it's used to create a more natural language in your configuration.

Inverse on HasMany is an NHibernate term, and it means that the other end of the relationship is responsible for saving.
Cascade.All on HasManyToMany tells NHibernate to cascade events down to the entities in the collection (so when you save the Store, all the Products are saved too).
WithTableName sets the many-to-many join table name.

The WithTableName call is currently only required if you're doing a bidirectional many-to-many, because Fluent NHibernate currently can't guess what the name should be; for all other associations it isn't required.

For NHibernaters: HasMany maps to a bag by default, and has a one-to-many element inside; HasManyToMany is the same, but with a many-to-many element.

Finally, lets map the Product.

Mappings/ProductMap.cs

public class ProductMap : ClassMap<Product>
{
  public ProductMap()
  {
    Id(x => x.Id);
    Map(x => x.Name);
    Map(x => x.Price);
    HasManyToMany(x => x.StoresStockedIn)
      .Cascade.All()
      .Inverse()
      .WithTableName("StoreProduct");
  }
}

That's the Product mapped; in this case we've used only methods that we've already encountered. The HasManyToMany is setting up the other side of the bidirectional many-to-many relationship with Store.

The application

In this section we'll initialise some data and output it to the console.

Program.cs

static void Main()
{
  var sessionFactory = CreateSessionFactory();

  using (var session = sessionFactory.OpenSession())
  {
    using (var transaction = session.BeginTransaction())
    {
      // create a couple of Stores each with some Products and Employees
      var barginBasin = new Store { Name = "Bargin Basin" };
      var superMart = new Store { Name = "SuperMart" };

      var potatoes = new Product { Name = "Potatoes", Price = 3.60 };
      var fish = new Product { Name = "Fish", Price = 4.49 };
      var milk = new Product { Name = "Milk", Price = 0.79 };
      var bread = new Product { Name = "Bread", Price = 1.29 };
      var cheese = new Product { Name = "Cheese", Price = 2.10 };
      var waffles = new Product { Name = "Waffles", Price = 2.41 };

      var daisy = new Employee { FirstName = "Daisy", LastName = "Harrison" };
      var jack = new Employee { FirstName = "Jack", LastName = "Torrance" };
      var sue = new Employee { FirstName = "Sue", LastName = "Walkters" };
      var bill = new Employee { FirstName = "Bill", LastName = "Taft" };
      var joan = new Employee { FirstName = "Joan", LastName = "Pope" };

      // add products to the stores, there's some crossover in the products in each
      // store, because the store-product relationship is many-to-many
      AddProductsToStore(barginBasin, potatoes, fish, milk, bread, cheese);
      AddProductsToStore(superMart, bread, cheese, waffles);

      // add employees to the stores, this relationship is a one-to-many, so one
      // employee can only work at one store at a time
      AddEmployeesToStore(barginBasin, daisy, jack, sue);
      AddEmployeesToStore(superMart, bill, joan);

      // save both stores, this saves everything else via cascading
      session.SaveOrUpdate(barginBasin);
      session.SaveOrUpdate(superMart);

      transaction.Commit();
    }

    // retreive all stores and display them
    using (session.BeginTransaction())
    {
      var stores = session.CreateCriteria(typeof(Store))
        .List<Store>();

      foreach (var store in stores)
      {
        WriteStorePretty(store);
      }
    }

    Console.ReadKey();
  }
}

public static void AddProductToStore(Store store, params Product[] products)
{
  foreach (var product in products)
  {
    store.AddProduct(product);
  }
}

public static void AddEmployeeToStore(Store store, params Employee[] employees)
{
  foreach (var employee in employees)
  {
    store.AddEmployee(employee);
  }
}

For brevity i've left out the definition of WritePrettyStore which simply calls Console.Write for the various relationships on a Store (but you can see it in the full code).

This is the Main method from your Program.cs. It's a bit lengthy, but what we're doing is creating a couple of Store instances, then adds some Employees and Products to them, then saves; finally, it re-queries them from the database and writes them out to the console.

You won't be able to run this yet, because there's one thing left to do. We need to implement the CreateSessionFactory method; that's where our configuration goes to tie NHibernate and Fluent NHibernate together.

The configuration

Lets implement the CreateSessionFactory method.

private static ISessionFactory CreateSessionFactory()
{

}

That's the method signature sorted, you'll note it's returning an NHibernate ISessionFactory. Now we're going to use the Fluent NHibernate Fluently.Configure API to configure our application. You can see more examples on this in the Fluent Configuration wiki page.

private static ISessionFactory CreateSessionFactory()
{
  return Fluently.Configure()
    .BuildSessionFactory();
}

That's not quite right yet, we're creating a SessionFactory, but we haven't configured anyting yet; so lets configure our database.

private static ISessionFactory CreateSessionFactory()
{
  return Fluently.Configure()
    .Database(
      SQLiteConfiguration.Standard
        .UsingFile("firstProject.db")
    )
    .BuildSessionFactory();
}

There we go, we've specified that we're using a file-based SQLite database. You can learn more about the database configuration API in the Database Configuration wiki page.

Just one more thing to go, we need to supply NHibernate with the mappings we've created. To do that, we add a call to Mappings in our configuration.

private static ISessionFactory CreateSessionFactory()
{
  return Fluently.Configure()
    .Database(
      SQLiteConfiguration.Standard
        .UsingFile("firstProject.db")
    )
    .Mappings(m =>
      m.FluentMappings.AddFromAssemblyOf<Program>())
    .BuildSessionFactory();
}

That's it, that's your application configured!

You should now be able to run the application and see the results of your query output to the console window.

Bargin Basin
  Products:
    Potatoes
    Fish
    Milk
    Bread
    Cheese
  Staff:
    Daisy Harrison
    Jack Torrance
    Sue Walkters

SuperMart
  Products:
    Bread
    Cheese
    Waffles
  Staff:
    Bill Taft
    Joan Pope

There you go, that's your first Fluent NHibernate project created and running!

The schema

If you haven't manually created the schema for this application, then it will fail on the first time you run it. There's something you can do about that, but it needs to be done directly against the NHibernate Configuration object; we can do that using the ExposeConfiguration method. Combine that call with a method to generate the schema, then you're able to create your schema at runtime.

private static ISessionFactory CreateSessionFactory()
{
  return Fluently.Configure()
    .Database(
      SQLiteConfiguration.Standard
        .UsingFile("firstProject.db")
    )
    .Mappings(m =>
      m.FluentMappings.AddFromAssemblyOf<Program>())
    .ExposeConfiguration(BuildSchema)
    .BuildSessionFactory();
}

private static void BuildSchema(Configuration config)
{
  // delete the existing db on each run
  if (File.Exists(DbFile))
    File.Delete(DbFile);

  // this NHibernate tool takes a configuration (with mapping info in)
  // and exports a database schema from it
  new SchemaExport(config)
    .Create(false, true);
}

You can read more about this in the Fluent Configuration wiki page.

What next? GettingStarted: Existing Application

Rake Script

Sun, 29 Mar 2009 06:16:02 Z

Fluent NHibernate is distributed with a Ruby Rake script, which can be used to build without having to open Visual Studio; more importantly, it also provides a simple mechanism for switching versions of NHibernate (see Supported NHiberate Versions for more details on our versioning policy).

Building with rake

Before you can run the rake script, you need to make sure you have all the necessary gems installed; the easiest way to do that is to run the InstallGems.bat distributed with Fluent NHibernate.

Once you've got all the gems installed, you can either run Build.bat which just runs rake, or you can run rake directly: rake. Either of those will use MSBuild to build the solution, and then will run the unit tests before copying the built files to the build directory.

When the build is complete, you can reference the Fluent NHibernate binaries from the build directory.

Switching versions

The rake script has the capability to switch which version of NHibernate it builds against. Currently we have support for 2.0.1GA and a slightly out of date version of trunk (useful, I know).

To build against a different version, you need to specify which version when calling rake.

For 2.0.1GA you can either just call rake, because it's the default, or to build it explicitly you can use:

rake default

For the 2.1 trunk of NHibernate, you can use:

rake nhib21

Updating trunk

The trunk of NHibernate is always going to be ahead of Fluent NHibernate, and we cannot keep it up to date; so the easiest way for you to do it yourself is to replace the contents of tools/NHibernate/nhib2.1 in your Fluent NHibernate directory. If you then run the above command for 2.1, it'll use your latest copy.

There's a big but when using trunk, we don't officially support it; there probably will be some breaking changes in trunk at some point that we won't be able to accommodate for.

Standard Mapping Ids

Fri, 27 Mar 2009 09:59:30 Z

Fluent Mapping
Introduction
ClassMap<T>
Ids
Properties
Relationships
Components
Conventions
Private Properties

If you haven't setup a Fluent NHibernate project before, you should checkout the GettingStarted: Introduction guide.

As mentioned in ClassMap, all mappings are done from inside the constructor of a ClassMap<T> derived class; so baring that in mind, all examples are going to exclude the surrounding class.

Simple Ids

This is pretty much the standard Id that most people use. Mapped as a identity or autoincrement in the database, and with a type of int.

// schema
Id int identity(1, 1) primary key

// model
public int Id { get; private set; }

// mapping
Id(x => x.Id);

This mapping sees that the Id property is an int and makes the assumption that it's an auto-incrementing primary key.

Similarly, if your Id is a Guid, then Fluent NHibernate uses the NHibernate guid.comb generator, and a string defaults to assigned.

Overriding the column name

You may want to use a different name for the property in your model than what's in your database, here's how to map it:

// schema
some_ugly_id int identity(1, 1) primary key

// model
public int Id { get; private set; }

// mapping
Id(x => x.Id)
  .ColumnName("some_ugly_id");

Specifying the generator

You may need to explicitly change what Fluent NHibernate uses as the identity generator; this could be if your Id is an int but you don't want it to be an auto-incrementing identity.

Id(x => x.Id)
  .GeneratedBy.Sequence("uuid_sequence");

You can use the GeneratedBy property to specify various different generators for the Id.

Currently GeneratedBy supports: Identity, Increment, specifying a Sequence, HiLo and SeqHiLo, UuidHex and UuidString, Guid and GuidComb, Assigned, specifying a Foreign identifier, and Native.

An Exception will be thrown if you try to use a generator with a type that isn't compatible, for example if you use guid with an int property.

Specifying unsaved values

If your domain stipulates that you must have a special unsaved value, then you can map it like so:

Id(x => x.Id)
  .WithUnsavedValue(-1);

Specifying access strategies

If your entity uses a backing field for a property, or some other non-standard design, then you can map it using the Access property.

// schema
Id int identity(1, 1) primary key

// model
private int _id;

public int Id
{
  get { return _id; }
}

// mapping
Id(x => x.Id)
  .Access.AsCamelCaseField();

The Access property can be used to set various combinations of Field and Property, with various casings and prefixes.

For example, for the same mapping but with the field called _id you could use the Prefix.Underscore overload: Access.AsCamelCaseField(Prefix.Underscore).

Home Page

Tue, 24 Mar 2009 09:28:07 Z

Navigation
Main Site
Issues
Mailing List
Downloads

Getting Started guide

Fluent Mapping
Auto Mapping

You've reached the official Wiki for Fluent NHibernate. You can use the right-hand menu to start browsing around.

Fluent NHibernate offers an alternative to NHibernate's standard XML mapping files. Rather than writing XML documents (.hbm.xml files), Fluent NHibernate lets you write mappings in strongly typed C# code. This allows for easy refactoring, improved readability and more concise code.

Some good starting places:

Getting started guide
Fluent mapping
Auto Mapping - where mappings are inferred from the design of your entities
Conventions
Full application configuration with our Fluent Configuration API
Database Configuration - fluently configure your database in code

Just go wiki-walking!

Any questions should be directed to the mailing list.

Auto Mapping Inheritance

Sun, 22 Mar 2009 18:27:56 Z

Auto Mapping
Introduction
Components
Conventions
Type Conventions
Altering Entities
Handling Inheritance
Overriding Mappings
Configuration Alterations

There are two main things that you'd want to do with inherited classes, either ignore the base class all together, or map them using an inheritance strategy. I'm going to start with the former, then move on to the latter.

Ignoring base-types

This scenario is where you may have a base class in your domain that you use to simplify your entities, you've moved common properties into it so you don't have to recreate them on every entity; typically this would be the Id and perhaps some audit information. So lets start with a model that has a base class we'd like to ignore.

namespace Entities
{
  public abstract class Entity
  {
    public virtual int Id { get; set; }
  }

  public class Person : Entity
  {
    public virtual string FirstName { get; set; }
    public virtual string LastName { get; set; }
  }

  public class Animal : Entity
  {
    public virtual string Species { get; set; }
  }
}

Relatively simple model here, we've got an Entity base class that defines the Id, then the Person and Animal entities. We have no desire to have Entity mapped by NHibernate, so we need a way to tell the auto mapper to ignore it.

For those individuals from traditional XML mapping land, this is what we're going to be recreating:

<class name="Person">
  <id name="Id" type="Int32">
    <generator class="identity" />
  </id>

  <property name="FirstName" />
  <property name="LastName" />
</class>

<class name="Animal">
  <id name="Id" type="Int32">
    <generator class="identity" />
  </id>

  <property name="Species" />
</class>

We need to initialise the NHibernate configuration, and supply it with any auto mappings we're going to create. To do that we'll combine the auto mapper with our Fluent Configuration.

Fluently.Configure()
  .Database(SQLiteConfiguration.Standard.InMemory)
  .Mappings(m =>
    m.AutoMappings.Add(
      AutoPersistenceModel  
        .MapEntitiesFromAssemblyOf<Entity>()  
        .Where(t => t.Namespace == "Entities")
    ))
  .BuildSessionFactory();

The key part is inside the AutoMappings.Add call, which is where we're telling the automapper to map anything in the Entities namespace from the assembly that contains our Entity base-class.

If we were to run this now, we wouldn't get the mapping we desire. Fluent NHibernate would see Entity as an actual entity and map it with Animal and Person as subclasses; this is not what we desire, so we need to modify our auto mapping configuration to reflect that.

After MapEntitiesFromAssemblyOf<Entity>() we need to alter the conventions that the auto mapper is using so it can identify our base-class.

Fluently.Configure()
  .Database(SQLiteConfiguration.Standard.InMemory)
  .Mappings(m =>
    m.AutoMappings.Add(
      AutoPersistenceModel  
        .MapEntitiesFromAssemblyOf<Entity>()  
        .WithSetup(s =>
        {
          s.IsBaseType =
            type => type == typeof(Entity);
        })
        .Where(t => t.Namespace == "Entities")
    ))
  .BuildSessionFactory();

We've added the WithSetup call in which we replace the IsBaseType convention with our own. This convention is used to identify whether a type is simply a base-type for abstraction purposes, or a legitimate storage requirement. In our case we've set it to return true if the type is an Entity.

With this change, we now get our desired mapping. Entity is ignored as far is Fluent NHibernate is concerned, and all the properties (Id in our case) are treated as if they were on the specific subclasses.

Base-type as an inheritance strategy

What we're going to do is create a simple model that we'll map as a [table-per-subclass][2] inheritance strategy, which is the equivalent of the NHibernate joined-subclass mapping.

namespace Entities
{
  public class Person
  {
    public virtual int Id { get; set; }
    public virtual string FirstName { get; set; }
    public virtual string LastName { get; set; }
  }

  public class Employee : Person
  {
    public virtual DateTime StartDate { get; set; }
  }

  public class Guest : Person
  {
    public virtual int GuestPassId { get; set; }
  }
}

Relatively simple model here, we've got an Person class that defines the Id and name properties, then the Employee and Guest subclass entities.

The XML equivalent is as follows:

<class name="Person">
  <id name="Id" type="Int32">
    <generator class="identity" />
  </id>

  <property name="FirstName" />
  <property name="LastName" />

  <joined-subclass name="Employee">
    <key column="PersonId" />
    <property name="StartDate" />
  </joined-subclass>

  <joined-subclass name="Guest">
    <key column="PersonId" />
    <property name="GuestPassId" />
  </joined-subclass>
</class>

Again we configure NHibernate using the Fluent Configuration:

Fluently.Configure()
  .Database(SQLiteConfiguration.Standard.InMemory)
  .Mappings(m =>
    m.AutoMappings.Add(
      AutoPersistenceModel  
        .MapEntitiesFromAssemblyOf<Entity>()  
        .Where(t => t.Namespace == "Entities")
    ))
  .BuildSessionFactory();

This is the same configuration that I used in the first example, except that if you recall the reason we had to change the last example was because it was mapping it as a joined-subclass - that's right, we don't need to do anything now! Our mapping is complete, Fluent NHibernate automatically assumes that any inherited classes (that haven't had their base-type excluded by the IsBaseType convention) should be mapped as joined-subclasses.

That's how to deal with base-classes with Fluent NHibernate's auto mapping

Auto Mapping Components

Thu, 19 Mar 2009 20:35:32 Z

Auto Mapping
Introduction
Components
Conventions
Type Conventions
Altering Entities
Handling Inheritance
Overriding Mappings
Configuration Alterations

The Fluent NHibernate AutoMapper is capable of automatically recognising simple components; currently only properties are supported, no relationships inside the components. With that in mind, I'll walk through how to automap your components.

Lets imagine this database structure:

table Person (
  Id int primary key,
  Name varchar(200),
  Address_Number int,
  Address_Street varchar(100),
  Address_PostCode varchar(8)
)

We want to map that to the following model:

public class Person
{
  public virtual int Id { get; private set; }
  public virtual string Name { get; set; }
  public virtual Address Address { get; set; }
}

public class Address
{
  public int Number { get; set; }
  public string Street { get; set; }
  public string PostCode { get; set; }
}

With this design, Address is actually a component, which isn't a full entity, more of a way of providing a clean model to a normalised database structure. I'll get started by setting up the auto-mapper with the Fluent Configuration and Database Configuration APIs.

var sessionFactory = Fluently.Configure()
  .Database(MsSqlConfiguration.MsSql2005
    .ConnectionString(c => c
      .Is(ApplicationConnectionString)))
  .Mappings(m =>
    m.AutoMappings.Add(
      AutoPersistenceModel.MapEntitiesFromAssemblyOf<Person>()
        .Where(type => type.Namespace.EndsWith("Domain"))
  ))
  .BuildSessionFactory();

We've now got the auto mappings integrated with NHibernate, so we need to instruct the auto mapper how to identify components; after the Where call, we can add a call to WithSetup to help the auto mapper identify our components.

.WithSetup(s =>
{
  s.IsComponentType =
    type => type == typeof(Address);
})

The IsComponentType convention is what Fluent NHibernate uses to determine whether a type is one that will be mapped as a component, rather than a full entity.

There are two things you need to know about this convention:

You can only set this convention once, so you'll need to find a way that allows you to identify multiple components; there are several options to this, including using the namespace (like Where does), or checking a suffix on the type name (anything that ends in "Component", for example).
This is not an exclusive call, so you need to segregate your component types from your standard entity types (so they'll be excluded by the Where call), otherwise they'll be auto-mapped as full entities as well as components - not good.

With that, the Address should now be automatically mapped as a component; the auto mapper will pick up the three properties and map them as properties on the component.

There's one more thing, for illustrative purposes I've deliberately gone against Fluent NHibernate's inbuilt convention for naming columns. By default any columns mapped in a convention will be prefixed with their type name, so Address.Street would be mapped against a column called AddressStreet; this is my personal preference, but not what our database contains! We can control how our columns are named by altering the GetComponentColumnPrefix convention, like so:

.WithSetup(s =>
{
  s.IsComponentType =
    type => type == typeof(Address);
  s.GetComponentColumnPrefix =
    type => type.Name + "_";
})

The convention now specifies that columns should be named TypeName_PropertyName, so Address.Street is now correctly mapped against Address_Street.

Standard Mapping Relationships

Tue, 17 Mar 2009 21:30:39 Z

Fluent Mapping
Introduction
ClassMap<T>
Ids
Properties
Relationships
Components
Conventions
Private Properties

If you haven't setup a Fluent NHibernate project before, you should checkout the GettingStarted: Introduction guide.

As mentioned in ClassMap, all mappings are done from inside the constructor of a ClassMap<T> derived class; so baring that in mind, all examples are going to exclude the surrounding class.

There are three relationships you can use to map between your entities, reference (many-to-one), has many (one-to-many), and has many to many (many-to-many); I'll start by discussing the exclusive features for each, then show the features that are common to both.

References / many-to-one

The References method is used to create a many-to-one relationship between two entities; that's where the current entity has a single property that is an instance of the other entity.

Simple reference

Here's a typical example of a References usage.

// schema
table Account ( // our entity
  CustomerId int foreign key (Customer) references (Id)
)
table Customer (
  Id int identity(1,1) primary key
)

// model
public class Account
{
  public Customer Customer { get; set; }
}

// mapping
public AccountMap()
{
  References(x => x.Customer);
}

This creates a relationship between the two tables. In NHibernate hbm mapping, it's equivalent to <many-to-one name="Customer" />.

Specifying a foreign key

If you're generating your schema from your mappings (see Schema Generation), you may want to name your foreign key, you can do that using the WithForeginKey method.

References(x => x.Customer)
  .WithForeignKey();

This creates a foreign key based on the naming of your entities; if this example were an Account that has a Customer, the foreign key would be called FK_Account_Customer. If you would prefer to specify your own key, you can use the WithForeignKey(string) overload.

Specifying the column name

If your foreign key Id has a different column name than what you're using for a property, then you can use the TheColumnNameIs method.

// schema
table Account ( // our entity
  Customer_RefId int foregin key (Customer) references (Id)
)
table Customer (
  Id int identity(1,1) primary key
)

// model
public Customer Customer { get; set; }

// mapping
References(x => x.Customer)
  .ColumnName("Customer_RefId");

If you need to specify multiple columns to use as a key, useful if the entity you're referencing has a composite-id, then you can use the WithColumns method.

References(x => x.Customer)
  .WithColumns("CustomerName", "CustomerReference");

Changing the referenced column

If you need to link to the entity you're referencing by something other than it's primary key, then you can use the PropertyRef method.

References(x => x.Customer)
  .PropertyRef(x => x.CustomerReference);

Handling null references

If it's allowed in your domain for a foreign key to be null, you may want to stipulate what behavior NHibernate should use on encountering a null; you can do this with theNotFound property.

References(x => x.Customer)
  .NotFound.Ignore();

The default behavior is Exception.

HasMany / one-to-many

The HasMany method is used to create a one-to-many relationship between two entities; that's where the current entity has a collection of instances of the other entity.

Simple HasMany

Here's a typical example of a HasMany usage.

// schema
table Account ( // our entity
  Id int identity(1, 1) primary key
)
table Customer (
  AccountId int foreign key (Account) references (Id)
)

// model
public class Account
{
  public IList<Customer> Customers { get; private set; }

  public Account()
  {
    Customers = new List<Customer>();
  }
}

// mapping
public AccountMap()
{
  HasMany(x => x.Customers);
}

This creates a relationship between the two tables. In NHibernate hbm mapping, it's equivalent to:

<bag name="Customers">
  <key column="AccountId" />
  <one-to-many class="Account" />
</bag>

Specifying the foreign key name

If you need to specify multiple columns to use as a key, useful if the entity you're referencing has a composite-id, then you can use the WithKeyColumns method.

HasMany(x => x.Customers)
  . WithKeyColumns("CustomerName", "CustomerReference");

Similarly, if you just want to specify one column name you can use WithKeyColumn.

HasManyToMany / many-to-many

The HasManyToMany method is used to create a many-to-many relationship between two entities; that's where there's a reference between two tables, with an intermediary table.

Simple HasManyToMany

Here's a typical example of a HasManyToMany usage.

// schema
table Account ( // our entity
  Id int identity(1, 1) primary key
)
table AccountToCustomer (
  Account_id int foreign key (Account) references (Id)
  Customer_id int foreign key (Customer) references (Id)
)
table Customer (
  Id int identity(1, 1) primary key
)

// model
public class Account
{
  public IList<Customer> Customers { get; private set; }

  public Account()
  {
    Customers = new List<Customer>();
  }
}

// mapping
public AccountMap()
{
  HasManyToMany(x => x.Customers);
}

This creates a relationship between the two tables. In NHibernate hbm mapping, it's equivalent to:

<bag name="Customers">
  <key column="Customer_id" />
  <many-to-many class="Account" column="Account_id" />
</bag>

Setting the table name

If your design has a different intermediary table name, you can use the WithTableName method to set it.

HasManyToMany(x => x.Customers)
  .WithTableName("CustomerAddresses");

Specifying the foreign key names

If you need to override the foreign key names that are used in the intermediary table, you can use WithParentKeyColumn and WithChildKeyColumn.

table AccountToCustomer (
  Account_RefId int foreign key (Account) references (Id)
  Customer_RefId int foreign key (Customer) references (Id)
)

HasMany(x => x.Customers)
  .WithParentKeyColumn("Account_RefId")
  .WithChildKeyColumn("Customer_RefId");

You can use either of these methods, or both together.

Common settings for relationships

These settings are common to either all the relationships, or just the HasMany and HasManyToMany; I'll specify which relationships they're for.

Specifying access strategies

For all relationships

If your entity uses a backing field for a property, or some other non-standard design, then you can map it using the Access property.

// model
public class Account
{
  private IList<Customer> customers = new List<Customer>();

  public IList<Customer> Customers
  {
    get { return customers; }
  }
}

// mapping
HasMany(x => x.Customers)
  .Access.AsCamelCaseField();

The Access property can be used to set various combinations of Field and Property, with various casings and prefixes.

For example, for the same mapping but with the field called _customers you could use the Prefix.Underscore overload: Access.AsCamelCaseField(Prefix.Underscore).

Setting the fetch method

For all relationships

If you need to specify how joined entities are fetched, then you can use the Fetch property.

HasMany(x => x.Customers)
  .Fetch.Join();

The options are Join and Select.

Inverse

For all relationships

HasMany(x => x.Customers)
  .Inverse();

This sets the inverse attribute.

Cascade

For all relationships

HasMany(x => x.Customers)
  .Cascade.All();

This sets the cascade attribute; the options are All, None, SaveUpdate, Delete, and AllDeleteOrphan (for HasMany and HasManyToMany only).

Setting the collection type

For HasMany and HasManyToMany only

You can override the type of collection that is used for relationships, you can read more about this in Standard Mapping Collection Types.

The default is to use bag, but you can override it with the explicit methods.

HasMany(x => x.Customers)
  .AsSet();

Conventions Shortcuts

Mon, 16 Mar 2009 14:40:28 Z

There are some shortcuts available for Conventions that can be used inline (much like the old convention style); they're to be used for very simple situations where some people might think defining new types is overkill.

Creating implementations of the interface convention types is always the recommended approach, but if you think otherwise these are available.

Builders

There is a ConventionBuilder class that you can use to define simple conventions. The general rule-of-thumb is if your convention has any logic, or spans multiple lines, then don't use the builders. That being said, they can be useful for simple scenarios.

The ConventionBuilder defines several static properties, one representing each convention interface. Through each property you can access two methods, Always and When. These can be used to create simple conventions that are either always applied, or only applied in particular circumstances.

Always

These inline conventions are applied to every mapping instance of their type, they're handy for catch-all situations.

ConventionBuilder.Class.Always(x => x.WithTable(x.EntityType.Name.ToLower()))
ConventionBuilder.Id.Always(x => x.ColumnName("ID"))

When

These conventions are only applied when the first parameter evaluates to true.

ConventionBuilder.Class.When(
  x => x.TableName == null, // when this is true
  x => x.WithTable(x.EntityType.Name + "Table") // do this
)

Even shorter shortcuts

There are some situations that are so obvious that they just cried out for an even simpler shortcut.

Table.Is(x => x.EntityType.Name + "Table")
PrimaryKey.Name.Is(x => "ID")
DefaultLazy.AlwaysTrue()
DynamicInsert.AlwaysTrue()
DynamicUpdate.AlwaysTrue()
OptimisticLock.Is(x => x.Dirty())
Cache.Is(x => x.AsReadOnly())

Usage

To use these conventions you just need to call Add on the Fluent Configuration ConventionDiscovery property.

Fluently.Configure()
  .Database(/* database config */)
  .Mappings(m =>
  {
    m.FluentMappings
      .AddFromAssemblyOf<Entity>()
      .ConventionDiscovery.Add(PrimaryKey.Name.Is(x => "ID"));
  })

The Add method accepts a params array, so you can specify multiple conventions together.

.ConventionDiscovery.Add(
  PrimaryKey.Name.Is(x => "ID"),
  DefaultLazy.AlwaysTrue()
)

Converting To New Style Conventions

Fri, 13 Mar 2009 20:06:09 Z

So your existing conventions have broke with the introduction of the new convention style. I realise you're probably annoyed that your build is broken, but take a breath and make sure you've read Conventions and Conventions Interfaces. Once you've done that, if you still don't know what to do to fix your application, this might help.

Replacing existing conventions

Below are all the original conventions (or near enough) with their equivalent in the new-style. The logic change can be summarised as: old conventions were applied to everything, always; new style conventions are applied conditionally.

I'll show some examples of updating your conventions after the table.

Old Style	New Style
`ITypeConvention`	Implement an `IClassConvention`
`IPropertyConvention`	Same but different method names
`Conventions.GetTableName`	Implement an `IClassConvention` or Convention Shortcuts
`Conventions.GetPrimaryKeyName` and `Conventions.GetPrimaryKeyNameFromType`	Implement an `IIdConvention` or Convention Shortcuts
`Conventions.GetForeignKeyName`	Implement an `IHasManyConvention` or other related relationship convention
`Conventions.GetReadOnlyCollectionBackingFieldName`	Implement an `IHasManyConvention` or other related relationship convention
`Conventions.IdConvention`	Implement an `IIdConvention`
`Conventions.OneToManyConvention`	Implement an `IHasManyConvention`
`Conventions.ManyToOneConvention`	Implement an `IReferenceConvention`
`Conventions.OneToOneConvention`	Implement an `IHasOneConvention`
`Conventions.GetManyToManyTableName`	Implement an `IHasManyToManyConvention`
`Conventions.JoinConvention`	Implement an `IJoinConvention`
`Conventions.DefaultCache`	Implement an `IClassConvention` or Convention Shortcuts
`Conventions.GetVersionColumnName`	Implement an `IVersionConvention`
`Conventions.DefaultLazyLoad`	Implement an `IClassConvention` or Convention Shortcuts
`Conventions.DynamicUpdate`	Implement an `IClassConvention` or Convention Shortcuts
`Conventions.DynamicInsert`	Implement an `IClassConvention` or Convention Shortcuts
`Conventions.GetComponentColumnPrefix`	Implement an `IComponentConvention`

Examples: Converting old conventions

It goes without saying that implementing interfaces is going to be more verbose than using in-line lambdas, so prepare yourself because these conversions are going to end up being longer; however, the added separation makes for a much less coupled design. Learn to love it.

You should read up on the conventions in general and what interfaces are available.

Primary Key naming

You used to write the following to override the primary key naming to be TableNameId:

.WithConvention(c =>
  c.GetPrimaryKeyName = type => type.Name + "Id");

Now you'd implement an `IIdConvention` which allows you to alter the actual Id mapping itself.

public class PrimaryKeyNamingConvention
  : IIdConvention
{
  public bool Accept(IIdentityPart id)
  {
    return true; // work on ALL ids
  }

  public void Apply(IIdentityPart id)
  {
    id.ColumnName(id.EntityType.Name + "Id");
  }
}

That's your new convention, which you'd situate with all your other conventions, then use either of the following snippets to hook them in:

.ConventionDiscovery.AddFromAssemblyOf<PrimaryKeyNamingConvention>();
.ConventionDiscovery.Add<PrimaryKeyNamingConvention>();

Many-to-many table naming

You used to write the following to override the table name used for many-to-many relationships:

.WithConvention(c =>
  c.GetManyToManyTableName = (child, parent) => child.Name + "To" + parent.Name);

Now you'd implement an `IHasManyToManyConvention` which allows you to alter the actual many-to-many mapping itself.

public class ManyToManyTableNameConvention
  : IHasManyToManyConvention
{
  public bool Accept(IManyToManyPart relationship)
  {
    return true; // work on ALL ids
  }

  public void Apply(IManyToManyPart relationship)
  {
    relationship.WithTableName(relationship.ChildType.Name + "To" + relationship.EntityType.Name);
  }
}

That's your new convention, which you'd situate with all your other conventions, then use either of the following snippets to hook them in:

.ConventionDiscovery.AddFromAssemblyOf< ManyToManyTableNameConvention>();
.ConventionDiscovery.Add< ManyToManyTableNameConvention>();

A note on auto-mapping

If you're using automapping, the conventions used to be mixed up together. Now anything that can be thought of configuring the automapper's discovery capabilities (for example IsBaseType) is now available only under the WithSetup method (which in-part replaces WithConvention), everything else is a standard convention and is handled through the ConventionDiscovery property like the regular conventions.

// old
.WithConvention(c =>
  c.IsBaseType = type => type == typeof(BaseEntity));

// new
.WithSetup(s =>
  s.IsBaseType = type => type == typeof(BaseEntity))

Attribute based conventions

If you were using the ForAttribute<T> method, then you can inherit from the AttributePropertyConvention abstract class.

public class MyAttributeConvention
  : AttributePropertyConvention<MyCustomAttribute>
{
  public override void Apply(MyCustomAttribute attribute, IProperty property)
  {
    // your alterations
  }
}

Standard Mapping Conventions

Wed, 11 Mar 2009 20:45:10 Z

As with the Auto Mapping, you can specify conventions to be used when your entities are pushed into NHibernate. I'll use the Fluent Configuration API to illustrate how to set these conventions.

Fluent.Configuration()
  .Database(SQLiteConfiguration.Standard.InMemory)
  .Mappings(m =>
    m.FluentMappings
      .AddFromAssemblyOf<Entity>>()
      .ConventionDiscovery.AddFromAssemblyOf<MyConvention>())
  .BuildSessionFactory();

You can read more on conventions in general on the Conventions page.

Fluent Configuration

Wed, 11 Mar 2009 20:42:39 Z

Fluent NHibernate provides an API for completely configuring NHibernate for use with your application, all within code. The API is broken down into five main methods, three of which are required.

Fluently.Configure()
  .Database(/* your database settings */)
  .Mappings(/* your mappings */)
  .ExposeConfiguration(/* alter Configuration */) // optional
  .BuildSessionFactory();

You can combine these methods in various ways to setup your application.

Fluently.Configure starts the configuration process
Database is where you specify your database configuration using the Database Configuration api
Mappings is where you supply which mappings you're using
ExposeConfiguration is optional, but allows you to alter the raw Configuration object
BuildSessionFactory is the final call, and it creates the NHibernate SessionFactory instance from your configuration.

The API is fairly small, and relatively discoverable, so it's easy to configure it in a way that will work with your application; however, here are some common usages:

Exclusively fluent

If you're in the situation where your application is exclusively using fluent mappings, then this is the configuration for you.

var sessionFactory = Fluently.Configure()
  .Database(SQLiteConfiguration.Standard.InMemory)
  .Mappings(m =>
    m.FluentMappings
      .AddFromAssemblyOf<YourEntity>())
  .BuildSessionFactory();

This setup uses the SQLite database configuration, but you can substitute that with your own; it then adds any fluent mappings from the assebly that contains YourEntity.

Automappings

If you're using only auto mappings, then this config is for you.

var sessionFactory = Fluently.Configure()
  .Database(SQLiteConfiguration.Standard.InMemory)
  .Mappings(m =>
    m.AutoMappings.Add(
      // your automapping setup here
      AutoPersistenceModel.MapEntitiesFromAssemblyOf<YourEntity>()
        .Where(type => type.Namspace.EndsWith("Entities"))))
  .BuildSessionFactory();

Replace the code inside AutoMappings.Add with your auto mapping configuration.

Mixed fluent mappings and auto mappings

If you're using a combination of standard fluent mappings and auto mappings, then this example should show you how to get started.

var sessionFactory = Fluently.Configure()
  .Database(SQLiteConfiguration.Standard.InMemory)
  .Mappings(m =>
  {
    m.FluentMappings
      .AddFromAssemblyOf<YourEntity>();

    m.AutoMappings.Add(
      // your automapping setup here
      AutoPersistenceModel.MapEntitiesFromAssemblyOf<YourEntity>()
        .Where(type => type.Namspace.EndsWith("Entities")));
  })
  .BuildSessionFactory();

You can see that this is a combination of the two previous examples, the Mappings method can accept multiple kinds of mappings.

HBM mappings

You've not yet got around to using Fluent NHibernate fully, but you are configuring your database with it; this configuration will let you configure your database and add your traditional hbm mappings.

var sessionFactory = Fluently.Configure()
  .Database(SQLiteConfiguration.Standard.InMemory)
  .Mappings(m =>
    m.HbmMappings
      .AddFromAssemblyOf<YourEntity>())
  .BuildSessionFactory();

The HbmMappings property allows you to add HBM XML mappings in a few different ways, this example adds everything from an assembly which defines YourEntity; however, you can add from an assembly instance, or just add single types.

Mixed HBM and fluent mappings

You're migrating your entities to Fluent NHibernate but haven't quite got them all across yet - this is for you.

var sessionFactory = Fluently.Configure()
  .Database(SQLiteConfiguration.Standard.InMemory)
  .Mappings(m =>
  {
    m.HbmMappings
      .AddFromAssemblyOf<YourEntity>();

    m.FluentMappings
      .AddFromAssemblyOf<YourEntity>();
  })
  .BuildSessionFactory();

The whole shebang: fluent, auto, and hbm mappings

You're a crazy fool and map a bit of everything, then this is how you'd configure it.

var sessionFactory = Fluently.Configure()
  .Database(SQLiteConfiguration.Standard.InMemory)
  .Mappings(m =>
  {
    m.HbmMappings
      .AddFromAssemblyOf<YourEntity>();

    m.FluentMappings
      .AddFromAssemblyOf<YourEntity>();

    m.AutoMappings.Add(
      // your automapping setup here
      AutoPersistenceModel.MapEntitiesFromAssemblyOf<YourEntity>()
        .Where(type => type.Namspace.EndsWith("Entities")));
  })
  .BuildSessionFactory();

A couple of extras, for free!

Here's a few quick tricks people might appreciate.

Exporting hbm.xml mappings

In the Mappings call, you can do the following:

.Mappings(m =>
{
  m.FluentMappings
    .AddFromAssemblyOf<YourEntity>()
    .ExportTo(@"C:\your\export\path");

  m.AutoMappings
    .Add(...)
    .ExportTo(@"C:\your\export\path");
})

That will export all of your fluent and automapped mappings in hbm.xml format to whatever location you specify.

Altering non-automapped conventions

If you want to override conventions that are used by your non-automapped classes, then you can use the ConventionDiscovery property on FluentMappings. This property exposes several methods which can be used to add conventions.

.Mappings(m =>
  m.FluentMappings
    .AddFromAssemblyOf<YourEntity>()
    .ConventionDiscovery.AddFromAssemblyOf<MyConvention>()

Some alternatives:

.ConventionDiscovery.Add<MyConvention>()
.ConventionDiscovery.Add(new MyConvention())
.ConventionDiscovery.AddFromAssemblyOf<MyConvention>()
.ConventionDiscovery.Setup(x =>
{
  x.Add<MyConvention>();
  x.AddFromAssemblyOf<AnotherConvention>();
});

Validation

If you forget to setup your database, or don't add any mappings, instead of pulling out your hair over obscure NHibernate exceptions, the BuildSessionFactory method will throw a more helpful exception to try to point you in the right direction. It'll tell you whether you've forgot to add any entities, or not setup your database.

Auto Mapping Altering Entities

Wed, 11 Mar 2009 20:33:10 Z

Auto Mapping
Introduction
Components
Conventions
Type Conventions
Altering Entities
Handling Inheritance
Overriding Mappings
Configuration Alterations

Continuing with the same schema we used in Auto Mapping Type Conventions, we now want to alter our has many relationship from Shelf to Product so that it has a cascade set on it. We don't want this to affect all one-to-many's in our domain, so we need to do this alteration only on the Shelf entity rather than with a convention.

So how exactly do you supply alterations only for a specific entity? Easy! with ForTypesThatDeriveFrom<T>(ClassMap<T>).

.ForTypesThatDeriveFrom<Shelf>(map =>
{
  map.HasMany<Product>()
    .Cascade.All();
});

The ForTypesThatDeriveFrom method takes a generic parameter that's the entity you want to customise. The parameter is an expression that allows you to alter the underlying ClassMap<T> that is generated by the auto mapper. Anything you can do in the non-auto fluent mapping, you can do in this override. So for our case, we map a HasMany of Product, and specify it's cascade; this overrides the HasMany that will have been generated by the auto mapper.

That's it. We've overridden the auto mapping explicitly for a specific type, while not affecting the general conventions of the system. You can do this for as many types as you need in your domain; however, baring in mind readability, it may sometimes be more appropriate to map entities explicitly using the standard fluent mapping if you find yourself overriding a lot of conventions.

Auto Mapping Type Conventions

Wed, 11 Mar 2009 20:20:44 Z

Now lets look at how you can do some deeper customisations of the Auto Mapping tool.

We're going to use the same domain as before, but with a few extensions.

public class Product
{  
  public int Id { get; private set; }  
  public virtual string Name { get; set; }
  public virtual string Description { get; set; }
  public virtual decimal Price { get; set; }
  public virtual ReplenishmentDay ReplenishmentDay { get; set; }
}  

public class Shelf  
{  
  public virtual int Id { get; private set; }  
  public virtual IList<Product> Products { get; private set; }  
  public virtual string Description { get; set; }

  public Shelf()
  {
    Products = new List<Product>();
  }
}

public class ReplenishmentDay
{
  public static readonly ReplenishmentDay Monday = new ReplenishmentDay("mon");
  /* ... */
  public static readonly ReplenishmentDay Sunday = new ReplenishmentDay("sun");

  private string day;

  private ReplenishmentDay(string day)
  {
    this.day = day;
  }
}

We've extended our domain with a Description and a ReplenishmentDay for the Product; the replenishment day is represented by a type-safe enum (using the type-safe enum pattern). Also there's a Description against the Shelf too (not sure why you'd have a description of a shelf, but hey, that's customers for you). These changes are mapped against the following schema:

table Product (
  ProductId int identity primary key,
  Name varchar(250),
  Description varchar(2000),
  Price decimal,
  RepOn int, 
  Shelf_FK int foreign key
)

table Shelf (
  ShelfId int identity primary key,
  Description varchar(2000)
)

Now, if you've been following along you'll remember that we made all strings default to 250; and yet the new description columns are 2000 characters long. The customer has stipulated that all descriptions of anything in the domain will always be 2000 or less characters, so lets map that without affecting our other rule for strings.

.ConventionDiscovery.Setup(s =>
{
  s.Add<DescriptionTypeConvention>();
  s.Add<DefaultStringLengthConvention>();

  // other conventions
});

We're using the Fluent NHibernate's Conventions again, which allow you to override anything in the mappings before they're given to NHibernate. Baring in mind that our convention in this case is only for string properties that are called "Description", lets see how the DescriptionTypeConvention is declared.

public class DescriptionTypeConvention
  : IPropertyConvention
{
  public bool Accept(IProperty propertyMapping)
  {
    return propertyMapping.PropertyType == typeof(string) &&
      propertyMapping.Property.Name == "Description";
  }

  public void Apply(IProperty propertyMapping)
  {
    propertyMapping.WithLengthOf(2000);
  }
}

It's fairly expressive of what it does, but I'll cover it for completeness. The IPropertyConvention specifies two methods: bool Accept(IProperty) and void Apply(IProperty). Accept should be implemented to return true for properties that you want this convention to deal with; this can be handled in any way you want, you could check the name, or it's ancestry, but in our case we just check whether it's a string and if it has the correct name. Apply is where the bulk of the work happens; this method gets called for every property mapping that has a type that Accept returns true for. We've implemented Apply to alter the length of the property. Simple really. To learn more about conventions, see the Conventions page.

With a simple implementation like this, we're able to map every Description property (that's a string) so that it has a length of 2000, all with an addition of only one line to our auto mapping configuration.

IUserType support

The other alteration to our domain was the addition of the ReplenishmentDay. There were two interesting things to consider for this change. Firstly, it's stored in an int column, which obviously doesn't match our type; and secondly the column is called RepOn, which we mustn't change. We're going to utilise NHibernate's IUserType to handle this column.

For the sake of this example we're going to assume you've got an IUserType called ReplenishmentDayUserType, but as it's beyond the scope of this post I won't actually show the implementation as it can be quite lengthy. It's best to just assume that the IUserType reads an int from the database and can convert it to a ReplenishmentDay instance. There's a nice example of implementing IUserType on Jakob Andersen's blog.

So how do we tell Fluent NHibernate to use an IUserType instead of the specified type? Easy, with another [[Conventions|convention], this time we'll use an IUserTypeConvention, or more specifically we'll derive from the connivence base-class UserTypeConvention that Fluent NHibernate supplies.

.ConventionDiscovery.Setup(s =>
{
  s.Add<DescriptionTypeConvention>();
  s.Add<ReplenishmentDayTypeConvention>();
  s.Add<DefaultStringLength>();

  // other conventions
});

Here's how our new ReplenishmentDayTypeConvention looks:

public class ReplenishmentDayTypeConvention
  : UserTypeConvention<ReplenishmentDayUserType>
{
  public override void Apply(IProperty propertyMapping)
  {
    base.Apply(propertyMapping);

    propertyMapping.ColumnName("RepOn");
  }
}

The actual setting of the user type is handled by the base Apply implementation, and if we weren't also setting the column name then we wouldn't need to override that member at all.

So that's it, with those conventions we're able to keep our standard rule that all strings should be 250 characters or less, unless they're a Description, then they can be 2000 or less. Replenishment days use our type-safe enum, but are persisted to an int in the database, which also has a custom column name.

What next? Auto Mapping Altering Entities