Posts Tagged ‘Fluent NHibernate’

3 Comments Fluent nHibernate: Classic mapping - 01/14/09

As I mentioned in my previous post, Fluent NHibernate offers two different ways to realize your mappings in C# code:

  • - adding a Map-class per entity and write out the mapping in C#
  • - use the Automapping feature in Fluent NHibernate and let the framework do all the work for you
  • In this post I’ll show you how you can write a basic mapping of an entity using a ClassMap.

A simple example

I’m starting out with a very simple example, with just one entity and a value object. I’ll be extending this tiny domain a bit, step by step (probably in another post).


In my DB, I just have one table, Person. It contains all the address-data, but in my domain, I want to map that data into a seperate object, a value object. If you were using NHibernate, you could do just that using the “component”-tag in ugly XML.

Using classic mapping, you create a new class, PersonMap, which should derive from the generic class, ClassMap.

Here’s the code:

public class PersonMap : ClassMap<Person>
	public PersonMap()
		Id(x => x.PersonId);
		Map(x => x.FirstName);
		Map(x => x.LastName);
		Map(x => x.PhoneNumber); 

		Component<Address>(x => x.Address, m =>
			m.Map(x => x.Street);
			m.Map(x => x.Number);
			m.Map(x => x.ZipCode);
			m.Map(x => x.City);
			m.Map(x => x.Country);

If you want to specify the length of the FirstName property as in your database, or constraint the property to never allow NULL, you can do this as follows:

 Map(x => x.FirstName)

I mentioned in my introduction post that FNH also gives you the ability to code by convention. It states that a developer should only specify the items that don’t fit within the default behaviour, thus to limit the configuration to a minimum. This makes your code easily maintanable since you don’t have configuration code in which you can get lost, you only have what you need.

Let me demonstrate that with an example. Check out how I mapped my Id property in the ClassMap. Notice I didn’t specify anything at all? Well, that’s because FNH assumes you’re using the identity generator. If you’re not, you can override this by specifying another generator type for your ID. Thus, you will only need to specify how you’ll be generating your ID’s if your not using identity.

Why? This avoids a lot of setup code when all your ID’s use this generator, don’t you think? Still, the flexibility remains. If you want to use another generator type, or explicitly state you are using the identity generator, you can still do so.

New way of testing

First of all, just a note. When I’m playing around with something new, just as now I’m playing around with FNH, I almost never write an application that actually does something. I’m just adding unittests to check if what i’m doing works.

FNH introduces a new way of testing your mappings. Remember how we used to create integration tests that add data to the database, retrieve it afterwards to check if it was successfully inserted? Remember how it was frustrating to notice in those tests that you messed up your NH mapping?

Actually, this was my way of testing if I did my mappings right. If any CRUD-operation failed, it was almost abvious I messed up my mapping somewhere. We have a test “CanAddPerson” which is also responsible to check if your mappings our correct. That’s not good, but there wasn’t another way…

Well, now you can separate the testing of your mappings, and your actual integration tests.

Here’s how you test your mappings:

public void CheckPersonMappingIsValid()
	new PersistenceSpecification<Person>(new SessionSource(new TestModel()))
		.CheckProperty(x => x.FirstName, "Laila")
		.CheckProperty(x => x.LastName, "Bougria")
		.CheckProperty(x => x.PhoneNumber, "0498123456")
		.CheckProperty(x => x.Address, new Address("My street", "34", "BE-2000", "Antwerp", "Belgium"))

And here’s the integration test which only has the responsibility to check whether we can add Person’s to the datastore or not.

public void CanAddPerson()
	Person personToAdd = new Person()
								 Address = new Address("street", "15A", "BE-2100", "city", "country"),
								 FirstName = "Laila",
								 LastName = "Bougria",
								 PhoneNumber = "0497123456"


	// use session to try to load the person
	var fromDb = Session.Get<Person>(personToAdd.PersonId);

	// Test that the person was successfully inserted
	Assert.AreNotSame(personToAdd, fromDb);
	Assert.AreEqual(personToAdd.Address, fromDb.Address);
	Assert.AreEqual(personToAdd.FirstName, fromDb.FirstName);
	Assert.AreEqual(personToAdd.LastName, fromDb.LastName);
	Assert.AreEqual(personToAdd.PhoneNumber, fromDb.PhoneNumber);

I ran the tests, and they both pass, so that’s great!

A note about value objects and fluent nHibernate

In my Person example, I’m mapping the address-data with a value object. In the model you’ll see it implements IEquatable.
Of course it does, you’ll think, it’s a value object! I just want to warn you, that if you think “I’ll implement the interface later…” and you run the mapping test, it wil fail. The VerifyMappings method will be comparing the Address instance and will expect true if all the properties match. If you didn’t implement the interface yet, your test will fail.

5 Comments Fluent nHibernate - 01/14/09

I know of many developers that dislike nHibernate just because of the configuration it needs. Come on, it’s not that bad! It’s just a block to add in your config file and a mapping per entity you’ll be using…

Well, it is true that it’s not a lot of fun to create and maintain these mapping files (who likes the ugly XML?).

Everyone of us has -at least- one time:

  • - forgot to mark the mapping file as embedded resource
  • - forgot to update the mapping when renaming a property

And the most annoying thing of all, is that you can only notice such errors at runtime… But we all just keep up with that because of the sweetness nHibernate brings afterwards!

Even the use of MyGeneration, to generate mapping files based on the database, isn’t a final solution for the mapping files issue. It’s not rare that the database changes physically during development, which would mean you need to regenerate the mapping files each time. At that point, generating the database from the mapping files looks like a great option, but then the manual writing of mapping files comes into the picture again.

Conclusion: It can be a pain to set up nHibernate’s configuration.


Enter fluent nHibernate.

Imagine using a fluent API instead of ugly XML to write your mappings? Wouldn’t that be great?

Well, thanks to Jeremy Miller and James Gregory and of course all other contributors, you now can find the project on Google Code!

Fluent NHibernate solves several problems:

  • - Changes won’t make our mappings break, just Ctrl+R+R! (that is if you’re using Resharper, but I’m just assuming you do :-) )
  • - No XML is required to write the mappings, only C#
  • - We can actually test the mappings on their own
  • - FH allows us to code by convention

Fluent NHibernate solves the mapping problem in two different ways:

  • - use a Map-class to manually write the mapping of your entities (=> a Map class per entity)
  • - using the Automapping feature of fluent NHibernate

I will demonstrate both ways in upcoming posts. Otherwise I’ll create a post here that’s too long to read.

I’m sure the “i-don’t-use-nhibernate-because-of-the-mappings”-guys, won’t have any reasons to object anymore after I show you how this is done!

Comment Fluent interfaces - 01/3/09

I’ll be talking about fluent nHibernate in the near feature. Fluent nHibernate is a great new open source framework, that will allow us to create our mappings in code (means no XML!) using a fluent API.

More about fluent nHibernate later. The goal of this post is to bring some more light into the dark when talking about fluent interfaces as fluent nHibernate uses this style.

It’s been a while since this term is around, just notice the date this article was written… But to be honest, I didn’t actually know the term until I ran into fluent nHibernate myself!

Fluent interfaces… Come again?

Fluent interfaces are not a very common style, but it sure is very nice to work with.

Imagine baking a pizza (that’s what I’m eating right now :p ):

Pizza myFluentPizza = Pizza.Create()

instead of how we do it now:

Pizza pizza = new Pizza();
pizza.Size  = PizzaSize.Medium;
pizza.BorderFilling = PizzaFilling.Cheese;
Topping tunaTopping = new Topping("Tuna");
Topping onionsTopping = new Topping("Onions");
Topping mozarellaTopping = new Topping("Mozarella");

Just notice the complexity of the code we write normally to achieve this. It makes you create all the toppings yourself, while when using the fluent interface, the Pizza worries about creating the topping, you just worry (if that’s even worrying at all) adding it to your pizza, thus wiring it up.

There’s a lot less noise in the code, just with a very quick look you immediately know what kind of pizza you’re baking here.

How did you…?

Well actually, I’m sure you’ll think “d’oh” when you see it, it’s quite simple:

public class Pizza
   public PizzaSize Size { get; private set; }
   public PizzaFilling Filling { get; private set; }
   public IList<Topping> Toppings { get; private set; }

   public static Pizza Create()
      Pizza pizza = new Pizza { Toppings = new List<Topping>() };
      return pizza;

   public Pizza OfSize(PizzaSize size)
      Size = size;
      return this;

   public Pizza WithBorderFilling(PizzaFilling filling)
      Filling = filling;
      return this;

   public Pizza WithTopping(string topping)
      Toppings.Add(new Topping(topping));
      return this;

   public Pizza Bake()
      // bake the pizza somehow
      return this;

I’ll spare you the enums and the Topping class, since it just contains a constructor accepting a string parameter…

Notice the only method that’s not returning the Pizza instance is the Bake method. I did this so you can’t directly call the other methods anymore. Once a pizza is baked, it’s a bit useless to add more toppings or adjust the border filling, don’t you think? Baking the pizza, is in this case the end of the chain.

Simpler than you thought, isn’t it?

Method chaining

I mentioned that the Bake() method above, was the end of the chain for this example. End of what chain? Well, when implementing a fluent interface, you’ll notice you’re using a lot of method chaining.

First let me give you an example of method chaining we can find in the .NET framework to clarify what it actually is:

StringBuilder builder = new StringBuilder();
builder.Append("Did you ")
       .Append("like my ")

string test = "Hello, I'm here to clarify method chaining";
test.Substring(1, 7)

Don’t tell me you’ve never used this syntax before? It makes your code very straightforward and easy to read.

How this works is very simple:
Just make your method return the object you’re calling the method on, and there you go! It also gives a different implementation if you’re using it on your properties (no automatic setters anymore!), but it’s very straightforward.


Fluent interfaces introduce a new style of coding, one that’s more readable and to-the-point. It does acquire some more coding, but in some cases, offering a fluent interface just is more important than spending more time on development.

Expect some posts about fluent nHibernate in the near future!