Introduction

Article series on NHibernate and Fluent NHibernate – Part 3

NHibernate's Answers — Wed, 02 Sep 2009 04:51:14 GMT

Today the third part of my series on NHibernate and Fluent NHibernate went live. It took a little bit longer due to work overload. You can read it here.

Summary

In part 3 of this article series about NHibernate and Fluent NHibernate I have discussed how to let Fluent NHibernate automatically map a domain model to a data model. We have realized that FNH provides a reasonable mapping out of the box by using default conventions. I have shown how one can implement user defined conventions which will influence how the mapping is defined on a very fine grained level. I have also shown that if we use a base class in our domain which implements common functionality we can instruct FNH to ignore this class and just map the “real” entities.

FNH with its auto mapping feature reduces the task of mapping a complex domain to an underlying data model to just a few keystrokes. And as is always true: less code results in less bugs and less maintenance overhead.

Article series on NHibernate and Fluent NHibernate – Part 2

NHibernate's Answers — Thu, 16 Apr 2009 12:30:10 GMT

Today the second part of my series on NHibernate and Fluent NHibernate went live. You can read it here.

Summary

In part 2 of the article series I have continued to implement the remaining part of the domain which I had introduced in the first part. I discuss the mapping of various forms of relations between different entities. For all mappings I have presented the code needed to verify the mappings.

In part 3 of the article series I’ll show how one can further refactor and improve the mapping of the domain model. I’ll then discuss the usage of conventions and finally show how one can use the auto-mapping capabilities of Fluent NHibernate to completely avoid the explicit mapping of entities.

Article series on NHibernate and Fluent NHibernate

NHibernate's Answers — Thu, 09 Apr 2009 00:04:51 GMT

Sorry for having been quiet such a long time. But I was really busy lately. I wrote several articles for journals and other non NHibernate related posts. But now the good news for all of you who like my tutorial like posts...

I have been invited to write a series of articles on NHibernate and Fluent NHibernate on http://dotnetslackers.com.

The first part of this series has just been published. I invite you to read it here.

In this series I start from grounds up and will explain to the readers how easy it has become to write an NHibernate based application since Fluent NHibernate is available. I’ll explain the explicit mapping with the fluent syntax as well as the auto-mapping that Fluent NH offers.

This is a total overhaul compared to my first introduction to NHibernate of last year which is still the most popular post of this blog... ;-)

Enjoy.

NHibernate and Castle Active Record (Part 1)

NHibernate's Answers — Sat, 26 Apr 2008 19:33:44 GMT

Introduction

The Castle ActiveRecord project is an implementation of the ActiveRecord pattern for .NET. The ActiveRecord pattern consists on instance properties representing a record in the database, instance methods acting on that specific record and static methods acting on all records.

Castle ActiveRecord is built on top of NHibernate, but its attribute-based mapping free the developer of writing XML for database-to-object mapping, which is needed when using NHibernate directly.

You can find the home page of the Castle project here.

How will we use it?

My intent is not to implement the ActiveRecord pattern but rather use ActiveRecord

as an alternative way to define the mapping between my domain objects and the relational database.
to simplify the initialization of NHibernate (I'm not so sure about this...)

In my previous posts (here and here) I have shown you how to define the mapping between domain objects and database tables by writing XML documents. Active Record allows me to decorate my domain objects with attributes which define the mapping instead of (hand-) coding XML documents.

Downloading and compiling the Castle Active Record Trunk

If you have never downloaded and compiled OSS software from a SVN repository before please refer to my previous post about preparing your system for NHibernate which you can find here.

I assume you have TortoiseSVN installed as your SVN client.

Make a new sub-folder called 'Castle' in your OSS folder (e.g. m:\dev\OSS\Castle). Right click on the folder an select 'SVN Checkout...'. Enter the URL 'http://svn.castleproject.org:8080/svn/castle/trunk/' in the Checkout dialog and press OK. The Castle stack will be downloaded. Depending on the bandwidth of your Internet connection this may take a while. The whole Castle stack contains more software than we need at the moment but let's just download all and ignore the parts we don't need. The whole download is around 21 MB.

When the download is finished you can compile the Castle stack. This is an automated process.

Unit Tests during the build process

During the build a lot of unit tests will be executed. For this we either need NUnit or MbUnit on our system. If you don't have it you can e.g. download NUnit from here. Download just the zip file containing the binaries for .NET 2.0 (at the time of this writing it's the file 'NUnit-2.4.7-net-2.0.zip'). Extract the binaries into a sub-folder of your OSS directory (e.g. m:\dev\OSS\nunit).

Building the Castle Stack

Open a command console and navigate to the directory where you have downloaded Castle (e.g. m\dev\OSS\Castle). Assuming that NAnt is also installed in the OSS directory enter the following command

..\NAnt\bin\nant.exe -D:nunit-console=<path to nunit-console.exe>

where at the place of <path to nunit-console.exe> you enter the path where you have unzipped/installed NUnit. In our case this is 'm:\dev\OSS\NUnit\bin\NUnit-Console.exe'.

Now the whole Castle stack is compiled and all tests are executed. This can take a while. On my machine it took about 2.5 minutes. The overall build may fail but still the assemblies are created (the reason of the overall failure might be that some of the Unit test fail. Remember that we are on the Trunk and this is under constant development. Sometimes some of the tests may thus fail.). The result on my machine was as follows

After building the Castle stack you should find a new sub-folder 'build' in the Castle folder.

Using Active Record

External dependencies of the Solution

For an introduction on how to setup a new solution please refer to this post. You can now copy all the necessary external assemblies on which the solution depends into the SharedLibs folder in your solution tree. You should copy all files (including NHibernate) from the build folder of Castle which was created during the build process described above. For this solution you need at least the following files

The sql*.dll are in the folder since we are using SQL Server Compact edition as a database. If you have read the previous posts about using NHibernate (e.g. here and here) the only new files are Castle.ActiveRecord.dll and Castle.Components.Validator.dll.

The Domain Model and the Mapping

To have a good comparison let's take the same domain model as in this post. Below is the class diagram of the domain.

Now instead of writing a domain class and then a XML mapping document we now only write the domain class and decorate it and its members with attributes. During initialization ActiveRecord will automatically generate the XML mapping documents for us which NHibernate requires for the object-relational mapping.

When using attributes the Order class will look like this

using System;

using Castle.ActiveRecord;

using Iesi.Collections.Generic;

using NHibernateAndActiveRecord.Domain;

namespace NHibernateAndActiveRecord.Domain

    [ActiveRecord(Table = "Orders")]

    public class Order

        public Order()

            OrderLines = new HashedSet<OrderLine>();

        [PrimaryKey(Generator = PrimaryKeyType.Guid)]

        public virtual Guid Id { get; set; }

        [BelongsTo(NotNull = true)]

        public virtual Customer Customer { get; set; }

        [Property]

        public virtual string OrderNumber { get; set; }

        [Property]

        public virtual DateTime OrderDate { get; set; }

        [HasMany(Table = "OrderLine",

                 ColumnKey = "OrderId",

                 Cascade = ManyRelationCascadeEnum.AllDeleteOrphan)]

        public virtual ISet<OrderLine> OrderLines { get; set; }

compared to a typical XML mapping document this is much more wrist friendly, isn't it. Some people also argue that attributes help to document the code, since I can immediately see e.g. which is the primary key and which property values should never be null, etc. I do not have to consult another file but can just look at the domain class to have the "full" picture. On the other hand the attributes also "clutter" my nice code and I partially violate the SoC pattern since mapping is not part of the domain in a DDD world.

Now let's look at the OrderLine class

using System;

using Castle.ActiveRecord;

namespace NHibernateAndActiveRecord.Domain

    [ActiveRecord]

    public class OrderLine

        [PrimaryKey(Generator = PrimaryKeyType.Guid)]

        public virtual Guid Id { get; set; }

        [Property(NotNull = true)]

        public virtual int Amount { get; set; }

        [Property(NotNull = true, Length = 50)]

        public virtual string ProductName { get; set; }

Here I have defined that Amount and ProductName cannot be null (this will be used for the generation of the database schema - there will be not null constraints on the corresponding table column). I also have defined that the maximal length of the ProductName cannot exceed 50 characters (also used for schema generation).

Finally the Customer class

using System;

using Castle.ActiveRecord;

namespace NHibernateAndActiveRecord.Domain

    [ActiveRecord]

    public class Customer

        [PrimaryKey(Generator = PrimaryKeyType.Guid)]

        public virtual Guid Id { get; set; }

        [Property(NotNull = true, Length = 50)]

        public virtual string CompanyName { get; set; }

That's it. Our domain and mapping is complete. We can now write our tests similar to the once we used in this post.

Unit Tests

Add an xml document to your test project and call it ActiveRecord.cfg.xml (similar to what you do when you ONLY use NHibernate). Add the following content to the file

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

<activerecord>

  <config>

    <add key="connection.provider"

         value="NHibernate.Connection.DriverConnectionProvider" />

    <add key="dialect"

         value="NHibernate.Dialect.MsSqlCeDialect" />

    <add key="connection.driver_class"

         value="NHibernate.Driver.SqlServerCeDriver" />

    <add key="connection.connection_string"

         value="Data Source=SampleDb.sdf" />

    <add key="show_sql"

         value="true" />

  </config>

</activerecord>

Set the Copy to Output Directory to Copy always.

Note: we are using SQL server compact edition in this case (the second, third and fourth entry in the XML are specific for this database).

Add an new item of type LocalDatabase to the test project and call it SampleDb.sdf.

Still in the test project add a reference to the System.Data.SqlServerCe.dll in the SharedLibs folder. This assembly contains the ado.net driver for SQL server compact edition.

Open the properties page of the test project and add the following command in the "Pre-build event command line" text box

copy $(ProjectDir)..\..\SharedLibs\sqlce*.dll $(ProjectDir)$(OutDir)

This command copies all the SQL server CE files from the SharedLibs folder to the target folder of the test project. Note: this is important, otherwise the test will not run. Also note that this is only needed if you use SQL server CE.

The first unit test we write will test whether we can successfully create the database schema or not. This is always a good test if your new to ActiveRecord. Add a new class CreateSchema_Fixture.cs to the test project and add the code below

using Castle.ActiveRecord;

using Castle.ActiveRecord.Framework.Config;

using NHibernateAndActiveRecord.Domain;

using NUnit.Framework;

namespace NibernateAndActiveRecord.Tests

    [TestFixture]

    public class CreateSchema_Fixture

        [Test]

        public void Can_initialize_and_create_schema()

            var configurationSource = new XmlConfigurationSource("ActiveRecord.cfg.xml");

            ActiveRecordStarter.Initialize(typeof(Customer).Assembly, configurationSource);

            ActiveRecordStarter.CreateSchema();

In the first line of the test we provide ActiveRecord with the necessary configuration info. In the second line we tell ActiveRecord to initialize itself (and NHibernate) with the given configuration info as well as the assembly in which the domain classes are implemented (and which also contains the mapping info since we use attributes). Then in the third line we create the schema. If there is already a schema in the db this will be deleted first.

If you have done every thing right, then the test should succeed.

Now we can continue to test our domain model. Let's first implement a base fixture class to free us from repeating code again and again. I suggest a class as follows

using Castle.ActiveRecord;

using Castle.ActiveRecord.Framework.Config;

using NHibernateAndActiveRecord.Domain;

using NUnit.Framework;

namespace NibernateAndActiveRecord.Tests

    [TestFixture]

    public class TestFixtureBase

        [TestFixtureSetUp]

        public void TestFixtureSetUp()

            var configurationSource = new XmlConfigurationSource("ActiveRecord.cfg.xml");

            ActiveRecordStarter.Initialize(typeof(Customer).Assembly, configurationSource);

        [SetUp]

        public void SetupContext()

            ActiveRecordStarter.CreateSchema();

            Before_each_test();

        [TearDown]

        public void TearDownContext()

            After_each_test();

        protected virtual void Before_each_test()

{ }

        protected virtual void After_each_test()

{ }

This class is equivalent to the class presented in this post on NHibernate. Once for each test session I configure ActiveRecord (and implicitly NHibernate). Before each single test I recreate the database schema to avoid any side effects leaking from one test to another. I also provide virtual methods which can be overridden in the child classes to execute specific code before or after each test.

Summary

I have introduced Castle ActiveRecord as an alternative way to use NHibernate. It's a layer on top of NHibernate and simplifies in many cases the usage of NHibernate. I have shown you how you can get the latest code from the source repository and compile it. I have then setup a simple domain model and defined a test fixture base class.

I'll continue to implement the tests in part 2 of this series. So keep ready...

Enjoy

How to setup a new solution

NHibernate's Answers — Sun, 06 Apr 2008 20:18:49 GMT

Introduction

In this post I'll present a possible setup for a .NET solution which respects (as much as possible) the following aspects, patterns and software engineering practices

Continuous Integration (CI)
Deploy often (--> see Agile development)
Domain Driven Design (DDD)
Test Driven Development (TDD)
Separation of Concern (SoC)

In most of the samples presented in this blog I'll adhere to this kind of solution setup (e.g. here and here)!

The solution should have as few external dependencies as possible. All external libraries (of course we don't count the .NET framework here) on which the solution is dependent should be (if possible) part of the solution tree. Then you can always (if you have your solution tree under source control -- and you definitely should!) check out the complete solution tree on any machine (e.g. on the build server or on a new developer machine) and just build the solution and run the unit tests without any further manual intervention needed.

Each project of the solution has a corresponding test project where you implement all your unit tests (and/or integration tests, acceptance tests, stress tests, etc.) for the respective project. So, if you have a project in the solution called Domain you should automatically have a additional project in the solution which you might call Domain.Tests.

Separation of Concern (SoC) suggests us to split the whole solution into several projects. I often have at least 3 types of projects. In a typical WinForms based application these might be

Domain - contains the domain model with it's domain entities, services, factories and repository interfaces
DataLayer - contains the NHibernate XML mapping files and the implementation of the repositories
Application (or PresentationLayer) - contains the application or presentation logic, the application shell, the views, presenters and/or application controllers

Of course each of those projects has a corresponding Tests project.

Depending on the complexity of the solution there might be even more projects.

Normally I have a Dev folder on one of my (local) hard disks. The Dev folder has at least two sub-folders OSS and Projects. In the OSS folder I have a copy of the source or binaries of all open source software I use in my projects. As you can see below I have downloaded Castle, NAnt, NHibernate, NUnit and the Rhino Tools.

The green check marks on Castle, NHibernate and Rhino Tools show that these folders are under source control (SVN in this case) and that I have the most recent version of the source.

In the sub-folder Projects I put all the solutions we develop for our customers.

Sample Solution Structure

Now let's have a look at the structure of a sample solution. Let's assume that it's a WinForms based application and call the solution DemoSolution.

In the Projects folder I create a sub-folder with the same name as the solution, in this case DemoSolution. In this solution folder I create at least the two sub-folders SharedLibs and src.

The folder SharedLibs contains all the external assemblies my solution depends on (e.g. NHibernate, Castle, 3rd party WinForm Controls, etc.). The content of the SharedLibs folder varies depending on the needs of the solution. In the sample solution I have presented here we have the following files in this folder

Important: Each project of the solution which references one or several of those external libraries points to this SharedLibs folder! That is: never reference an assembly from the GAC (except the .NET libraries of course).

The folder src on the other hand contains our own source code for the solution. The Visual Studio solution file *.sln I put directly in the src folder. Normally the VS solution has the same name as the solution folder (in this case DemoSolution.sln). For each project of the VS solution I have one sub-folder. In this case we have 6 projects in the solution, three of them containing the code which makes up our application and the other 3 projects containing the code of the corresponding (unit-) tests.

Summary

I have presented you a possible structure for a solution you develop. This structure tries to satisfy various requirements implied by commonly used patterns and software engineering practices.

Your first NHibernate based application

NHibernate's Answers — Tue, 01 Apr 2008 12:29:46 GMT

In a previous article I showed how to setup a developer machine to start using NHibernate as an ORM tool during the development of an application. I advocated a domain driven design (DDD) approach and a test driven development (TDD) style. This is the second article in a series of introductory chapters.

Define the Domain

Lets start by defining a very simple domain. For the moment it consists of one entity called Product. The product has 3 properties Name, Category and Discontinued.

Add a folder Domain to the FirstSample project of your solution. Add a new class Product.cs to this folder. The code is very simple and uses automatic properties (a feature of the new C# 3.0 compiler)

namespace FirstSolution.Domain

    public class Product

        public string Name { get; set; }

        public string Category { get; set; }

        public bool Discontinued { get; set; }

Now we want to be able to persist instances of this entity in a (relational) database. We have chosen NHibernate for this task. An instance of an entity in the domain corresponds to a row in a table in the database. So we have to define a mapping between the entity and the corresponding table in the database. This mapping can be done either by defining a mapping file (an xml-document) or by decorating the entity with attributes. I'll start with the mapping file.

Define the Mapping

Create a folder Mappings in the FirstSample project. Add a new xml-document to this folder and call it Person.hbm.xml. Please note the "hbm" part of the file name. This is a convention used by NHibernate to automatically recognize the file as a mapping file. Define "Embedded Resource" as Build Action for this xml file.

In the Windows Explorer locate the nhibernate-mapping.xsd in the src folder of NHibernate and copy it to your SharedLibs folder. We can now use this xml schema definition file when defining our mapping files. VS will then provide intellisense and validation when editing an xml mapping document.

Back in VS add the schema to the Product.hbm.xml file

Let's start now. Each mapping file has to define a <hibernate-mapping> root node

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

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

                   assembly="FirstSolution"

                   namespace="FirstSolution.Domain">

  <!-- more mapping info here -->

</hibernate-mapping>

In a mapping file when referencing a domain class you always have to provide the fully qualified name of the class (e.g. FirstSample.Domain.Product, FirstSample). To make the xml less verbose you can define the assembly name (in which the domain classes are implemented and the namespace of the domain classes in the two attributes assembly and namespace of the root node. It's similar to the using statement in C#.

Now we have to first define a primary key for the product entity. Technically we could take the property Name of the product since this property must be defined and has to be unique. But it is common to use a surrogate key instead. For thus we add a property to our entity and call it Id. We use Guid as the type of the Id but it can as well be an int or a long.

using System;

namespace FirstSolution.Domain

    public class Product

        public Guid Id { get; set; }

        public string Name { get; set; }

        public string Category { get; set; }

        public bool Discontinued { get; set; }

The complete mapping file

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

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

                   assembly="FirstSolution"

                   namespace="FirstSolution.Domain">

  <class name="Product">

    <id name="Id">

      <generator class="guid" />

    </id>

    <property name="Name" />

    <property name="Category" />

    <property name="Discontinued" />

  </class>

</hibernate-mapping>

NHibernate doesn't get in our way such as that it defines many reasonable defaults. So if you don't provide a column name for a property explicitly it will name the column according to the property. Or NHibernate can automatically infer the name of the table or the type of the column from the class definition. As a consequence my xml mapping file is not cluttered with redundant information. Please refer to the online documentation for more detailed explanation of the mapping. You can find it here.

Your solution explorer should look like this now (Domain.cd contains the class diagram of our simple domain)

Configure NHibernate

We now have to tell NHibernate which database product we want to use and provide it the connection details in form of a connection string. NHibernate supports many many database products!

Add a new xml file to the FirstSolution project and call it hibernate.cfg.xml. Set its property "Copy to Output" to "Copy always". Since we are using SQL Server Compact Edition in this first sample enter the following information into the xml file

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

<hibernate-configuration xmlns="urn:nhibernate-configuration-2.2">

  <session-factory>

    <property name="connection.provider">NHibernate.Connection.DriverConnectionProvider</property>

    <property name="dialect">NHibernate.Dialect.MsSqlCeDialect</property>

    <property name="connection.driver_class">NHibernate.Driver.SqlServerCeDriver</property>

    <property name="connection.connection_string">Data Source=FirstSample.sdf</property>

    <property name="show_sql">true</property>

  </session-factory>

</hibernate-configuration>

With this configuration file we tell NHibernate that we want to use MS SQL Server Compact Edition as our target database and that the name of the database shall be FirstSample.sdf (=connection string). We have also defined that we want to see the SQL NHibernate generates and sends to the datbase (highly recommended for debugging purposes during development). Double check that you have no typos in the code!

Add an empty database called FirstSample.sdf to the FirstSample project (choose Local Database as template)

Click Add and ignore the DataSet creation wizard (just hit Cancel).

Test the Setup

It's now time to test our setup. First verify that you have the following files in your SharedLibs folder

The last 8 files you can find in the "Microsoft SQL Server Compact Edition" directory in your Programs folder.

Note: the System.Data.SqlServerCe.dll is located in the sub-folder Desktop.

All other files can be found in the NHibernate folder

Add a reference to the FirstSample project in your test project. Additionally add references to NHibernate.dll, nunit.framework.dll and Systm.Data.SqlServerCe.dll (remember to reference the files located in the SharedLibs folder!). Pay attention to set the property "Copy Local" to true for the assembly System.Data.SqlServerCe.dll since by default it is set to false!

Add a class called GenerateSchema_Fixture to your test project. Your test project should now look like this

We further need the 7 files sqce*.dll in the output directory. We can do this by using a post-build event in VS. Enter the following command in the "Post-build event command line"

copy $(ProjectDir)..\..\SharedLibs\sqlce*.dll $(ProjectDir)$(OutDir)

Now add the following code to the GenerateSchema_Fixture file

using FirstSolution.Domain;

using NHibernate.Cfg;

using NHibernate.Tool.hbm2ddl;

using NUnit.Framework;

namespace FirstSolution.Tests

    [TestFixture]

    public class GenerateSchema_Fixture

        [Test]

        public void Can_generate_schema()

            var cfg = new Configuration();

            cfg.Configure();

            cfg.AddAssembly(typeof (Product).Assembly);

            new SchemaExport(cfg).Execute(false, true, false, false);

The first line of the test method creates a new instance of the NHibernate configuration class. This class is used to configure NHibernate. In the second line we tell NHibernate to configure itself. NHibernate will look out for configuration information since we do not provide any information here in the test method. So NHibernate will search for a file called hibernate.cfg.xml in the output directory. That's exactly what we want since we have defined our settings in this file.

In the third line of the code we tell NHibernate that it can find mapping information in the assembly which contains also the class Product. At the time being it will only find one such file (Product.hbm.xml) as an embedded resource.

The fourth line of code uses the SchemaExport helper class of NHibernate to auto-"magically" generate the schema in the database for us.

Note: with this test method we do NOT want to find out whether NHibernate does its job correctly (you can be sure it does) but rater whether we have setup our system correctly.

If you have TestDriven.Net installed you can now just right click inside the test method and choose "Run Test(s)" to execute the test.

If every thing is ok you should see the following result in the output window

If you have ReSharper installed you can just start the test by clicking the yellow-green circle on the left border and choose Run.

The result is as follows

In case of Problems

If your test fails double check that you find the following files in your target directory (that is: m:dev\projects\FirstSolution\src\FirstSolution.Tests\bin\debug)

Double check also if you have no typos in the NHibernate configuration file (hibernate.cfg.xml) or in the mapping file (Product.hbm.xml). Finally check whether you have set the "Build Action" of the mapping file (Product.hbm.xml) to "Embedded Resource". Only continue if the test succeeds.

Our first CRUD operations

Now obviously our system is ready to start. We have successfully implemented our Domain, defined the mapping files and configured NHibernate. Finally we have used NHibernate to automatically generate the database schema from our Domain (and our mapping files).

In the spirit of DDD (see e.g. Domain Driven Design by Eric Evans) we define a repository for all crud operations (create, read, update and delete). The repository interface is part of the domain where as the implementation is not! The implementation is infrastructure specific. We want to keep our domain persistence ignorant (PI).

Add a new interface to the domain folder of our FirstSolution project. Call it IProductRepository. Let's define the following interface

using System;

using System.Collections.Generic;

namespace FirstSolution.Domain

    public interface IProductRepository

        void Add(Product product);

        void Update(Product product);

        void Remove(Product product);

        Product GetById(Guid productId);

        Product GetByName(string name);

        ICollection<Product> GetByCategory(string category);

Add a class ProductRepository_Fixture to the test project of the solution and add the following code

    [TestFixture]

    public class ProductRepository_Fixture

        private ISessionFactory _sessionFactory;

        private Configuration _configuration;

        [TestFixtureSetUp]

        public void TestFixtureSetUp()

            _configuration = new Configuration();

            _configuration.Configure();

            _configuration.AddAssembly(typeof (Product).Assembly);

            _sessionFactory = _configuration.BuildSessionFactory();

In the fourth line of the method TestFixtureSetUp we create a session factory. This is an expensive process and should thus be executed only once. That's the reason why I put it into this method which is only executed once during a test cicle.

To keep our test methods side effect free we re-create our database schema before the execution of each test method. Thus we add the following method

        [SetUp]

        public void SetupContext()

            new SchemaExport(_configuration).Execute(false, true, false, false);

And now we can implement the test method to add a new product instance to the database. Start by adding a new folder called Repositories to your FirstSolution project. Add a class ProductRepository to this folder. Make the ProductRepository inherit from the interface IProductRepository.

using System;

using System.Collections.Generic;

using FirstSolution.Domain;

namespace FirstSolution.Repositories

    public class ProductRepository : IProductRepository

        public void Add(Product product)

            throw new NotImplementedException();

        public void Update(Product product)

            throw new NotImplementedException();

        public void Remove(Product product)

            throw new NotImplementedException();

        public Product GetById(Guid productId)

            throw new NotImplementedException();

        public Product GetByName(string name)

            throw new NotImplementedException();

        public ICollection<Product> GetByCategory(string category)

            throw new NotImplementedException();

Manipulating Data

Now go back to the ProductRepository_Fixture test class and implement the first test method

        [Test]

        public void Can_add_new_product()

            var product = new Product {Name = "Apple", Category = "Fruits"};

            IProductRepository repository = new ProductRepository();

            repository.Add(product);

The first run of the test method will fail since we have not yet implemented the Add method in the repository class. Let's do it. But wait, we have to define a little helper class first which provides us session objects on demand.

using FirstSolution.Domain;

using NHibernate;

using NHibernate.Cfg;

namespace FirstSolution.Repositories

    public class NHibernateHelper

        private static ISessionFactory _sessionFactory;

        private static ISessionFactory SessionFactory

get

                if(_sessionFactory == null)

                    var configuration = new Configuration();

                    configuration.Configure();

                    configuration.AddAssembly(typeof(Product).Assembly);

                    _sessionFactory = configuration.BuildSessionFactory();

                return _sessionFactory;

        public static ISession OpenSession()

            return SessionFactory.OpenSession();

This class creates a session factory only the first time a client needs a new session.

Now we can define the Add method in the ProductRepository as follows

        public void Add(Product product)

            using (ISession session = NHibernateHelper.OpenSession())

                using (ITransaction transaction = session.BeginTransaction())

                    session.Save(product);

                    transaction.Commit();

The second run of the test method will again fail with the following message

That's because NHibernate is by default configured to use lazy load for all entities. That is the recommended approach and I warmly recommend not to change it for a maximum of flexibility.

How can we solve this issue? It's easy we have to just make all our properties (and methods) of the domain object(s) virtual. Let's do this for our Product class

    public class Product

        public virtual Guid Id { get; set; }

        public virtual string Name { get; set; }

        public virtual string Category { get; set; }

        public virtual bool Discontinued { get; set; }

Now run the test again. It should succeed and we get the following output

Note the sql spit out by NHibernate.

Now we think that we have successfully inserted a new product into the database. But let's test it whether it is really so. Let's extend our test method

        [Test]

        public void Can_add_new_product()

            var product = new Product {Name = "Apple", Category = "Fruits"};

            IProductRepository repository = new ProductRepository();

            repository.Add(product);

            // use session to try to load the product

            using(ISession session = _sessionFactory.OpenSession())

                var fromDb = session.Get<Product>(product.Id);

                // Test that the product was successfully inserted

                Assert.IsNotNull(fromDb);

                Assert.AreNotSame(product, fromDb);

                Assert.AreEqual(product.Name, fromDb.Name);

                Assert.AreEqual(product.Category, fromDb.Category);

Run the test again. Hopefully it will succeed...

Now we are ready to implement also the other methods of the repository. For testing this we would rather have a repository (that is database table) already containing some products. Nothing easier than this. Just add a method CreateInitialData to the test class as follows

        private readonly Product[] _products = new[]

                     new Product {Name = "Melon", Category = "Fruits"},

                     new Product {Name = "Pear", Category = "Fruits"},

                     new Product {Name = "Milk", Category = "Beverages"},

                     new Product {Name = "Coca Cola", Category = "Beverages"},

                     new Product {Name = "Pepsi Cola", Category = "Beverages"},

};

        private void CreateInitialData()

            using(ISession session = _sessionFactory.OpenSession())

                using(ITransaction transaction = session.BeginTransaction())

                    foreach (var product in _products)

                        session.Save(product);

                    transaction.Commit();

Call this method from the SetupContext method (after the create schema call) and we are done. Now each time after the database schema is created the database is populated with some products.

Let's test the Update method of the repository with the following code

        [Test]

        public void Can_update_existing_product()

            var product = _products[0];

            product.Name = "Yellow Pear";

            IProductRepository repository = new ProductRepository();

            repository.Update(product);

            // use session to try to load the product

            using (ISession session = _sessionFactory.OpenSession())

                var fromDb = session.Get<Product>(product.Id);

                Assert.AreEqual(product.Name, fromDb.Name);

When running for the first time this code will fail since the Update method has not yet been implemented in the repository. Note: This is the expected behavior since in TDD the first time you run a test it should always fail!

Analogous to the Add method we implement the Update method of the repository. The only difference is that we call the update method of the NHibernate session object instead of the save method.

        public void Update(Product product)

            using (ISession session = NHibernateHelper.OpenSession())

            using (ITransaction transaction = session.BeginTransaction())

                session.Update(product);

                transaction.Commit();

Run the test again an watch it succeed.

The delete method is straight forward. When testing whether the record has really been deleted we just assert that the value returned by the session's get method is equal to null. Here is the test method

        [Test]

        public void Can_remove_existing_product()

            var product = _products[0];

            IProductRepository repository = new ProductRepository();

            repository.Remove(product);

            using (ISession session = _sessionFactory.OpenSession())

                var fromDb = session.Get<Product>(product.Id);

                Assert.IsNull(fromDb);

and here the implementation of the Remove method in the repository

        public void Remove(Product product)

            using (ISession session = NHibernateHelper.OpenSession())

                using (ITransaction transaction = session.BeginTransaction())

                    session.Delete(product);

                    transaction.Commit();

Querying the Database

We still have to implement the three methods which query the database for objects. Let's start with the most easy one, the GetById. First we write the test

        [Test]

        public void Can_get_existing_product_by_id()

            IProductRepository repository = new ProductRepository();

            var fromDb = repository.GetById(_products[1].Id);

            Assert.IsNotNull(fromDb);

            Assert.AreNotSame(_products[1], fromDb);

            Assert.AreEqual(_products[1].Name, fromDb.Name);

and then the code to fulfill the test

        public Product GetById(Guid productId)

            using (ISession session = NHibernateHelper.OpenSession())

                return session.Get<Product>(productId);

Now that was easy. For the following two methods we use a new method of the session object. Let's start with the GetByName method. As usual we write the test first

        [Test]

        public void Can_get_existing_product_by_name()

            IProductRepository repository = new ProductRepository();

            var fromDb = repository.GetByName(_products[1].Name);

            Assert.IsNotNull(fromDb);

            Assert.AreNotSame(_products[1], fromDb);

            Assert.AreEqual(_products[1].Id, fromDb.Id);

The implementation of the GetByName method can be done by using two different approaches. The first is using HQL (Hibernate Query Language) and the second one HCQ (Hibernate Criteria Query). Let's start with HQL. HQL is a object oriented query language similar (but not equal to) SQL.

        public Product GetByName(string name)

            using (ISession session = NHibernateHelper.OpenSession())

                Product product = session

                    .CreateQuery("from Product p where p.Name=:name")

                    .SetString("name", name)

                    .UniqueResult<Product>();

                return product;

In the above sample I have introduced a commonly used technique when using NHibernate. It's called fluent interfaces. As a result the code is less verbose and easier to understand. You can see that a HQL query is a string which can have embedded (named) parameters. Parameters are prefixed by a ':'. NHibernate defines many helper methods (like SetString used in the example) to assign values of various types to those parameters. Finally by using UniqueResult I tell NHibernate that I expect only one record to return. If more than one record is returned by the HQL query then an exception is raised. To get more information about HQL please read the online documentation.

The second version uses a criteria query to search the requested product.

        public Product GetByName(string name)

            using (ISession session = NHibernateHelper.OpenSession())

                Product product = session

                    .CreateCriteria(typeof(Product))

                    .Add(Restrictions.Eq("Name", name))

                    .UniqueResult<Product>();

                return product;

Many users of NHibernate think that this approach is more object oriented. On the other hand a complex query written with criteria syntax can quickly become difficult to understand.

The last method to implement is GetByCategory. This method returns a list of products. The test can be implemented as follows

        [Test]

        public void Can_get_existing_products_by_category()

            IProductRepository repository = new ProductRepository();

            var fromDb = repository.GetByCategory("Fruits");

            Assert.AreEqual(2, fromDb.Count);

            Assert.IsTrue(IsInCollection(_products[0], fromDb));

            Assert.IsTrue(IsInCollection(_products[1], fromDb));

        private bool IsInCollection(Product product, ICollection<Product> fromDb)

            foreach (var item in fromDb)

                if (product.Id == item.Id)

                    return true;

            return false;

and the method itself might contain the following code

        public ICollection<Product> GetByCategory(string category)

            using (ISession session = NHibernateHelper.OpenSession())

                var products = session

                    .CreateCriteria(typeof(Product))

                    .Add(Restrictions.Eq("Category", category))

                    .List<Product>();

                return products;

Summary

In this article I have shown you how to implement a basic sample domain, define the mapping to a database and how to configure NHibernate to be able to persist domain objects in the database. I have shown you how to typically write and test CRUD methods for your domain objects. I have taken MS SQL Compact Edition as sample database but any other supported database can be used (you only have to change the hibernate.cfg.xml file accordingly). Ee have no dependencies on external frameworks or tools other than the database and NHibernate itself (.NET of course never counts here).

Prepare your system for NHibernate

NHibernate's Answers — Mon, 31 Mar 2008 21:08:25 GMT

In this post (and a subsequent one) I'll introduce two ways how to prepare a developer machine to use NHibernate as a ORM (Object Relational Modeling) tool.

The first approach describes the minimal setup needed to use NHibernate when developing an application. The second approach on the other hand describes an infrastructure which is not only based on NHibernate but also on another very useful framework called Rhino Tools. This framework simplifies the usage of NHibernate very much but is by no means required. I personally have successfully developed medium sized and large customer projects based on latter kind of setup.

In this article the focus is on TDD (Test Driven Development) and we want to approach the topic by adhering to DDD (Domain Driven Design). Although NHibernate can also be used to generate the domain model by starting from an existing database schema I'll concentrate on the opposite direction and start with a domain model first and let NHibernate generate the database schema from the model (and the mapping meta data).

How to start

First you have to download NHibernate. Since NHibernate is an open source project anybody has free access to the (most current) binaries and/or source code. The source code is stored in a SVN repository (Subversion Source Control System) and can be found here. The most current source code is called the "trunk".

The Operating System

I expect you are working on a machine with one of the following operating systems

Windows XP SP2,
Windows VISTA,
Windows Server 2003 or
Windows Server 2008.

Which version of Visual Studio

We use the brand new NHibernate 2.0 Alpha 1 version. This version of NHibernate can work either with .NET 2.0 or .NET 3.5. For the former version you should have at least Visual Studio 2005 Professional installed and for the latter you need at least VS 2008 Professional. Of course you can also work with the Express Edition but they have some serious limitations (e.g. you cannot use any Add-In with VS). Now if you have some money left I strongly recommend you install the ReSharper Add-In as your productivity tool. I promise you it'll boost your productivity by factors! This investment is worth every penny (When using VS 2008 try to also use the EAP release of ReSharper 4.0 which you can find here. At the time being release 755 seems to be rather stable!).

Download the NHibernate binaries

You can grab the latest NHibernate binaries here. At the time being this is the Alpha 1 release of the version2.0.0. Download the file "NHibernate-2.0.0.Alpha1-bin.zip". Extract the zip files to a folder where you will place all your Open Source Software (OSS). That is create a new folder, e.g. "m:\dev\OSS\NHibernate" and extract the binaries to this folder. The binaries are compiled against .NET 2.0. If you prefer to have binaries compiled agains .NET 3.5 you have to build NHibernate from the trunk as described in the next chapter. Otherwise you can skip the following chapter and move directly to the chapter "Prepare for TDD".

Build NHibernate from the Trunk

To download the source code you need a SVN client application installed on your developer machine. There exist various open source as well as commercial clients. One of the most known (open source) clients is TortoiseSVN and can be found here. TortoiseSVN integrates very nicely with Windows Explorer. Download and install it on your machine. Restart your machine after the installation.

Download the NHibernate Source Code

Create a (sub-)directory OSS (Open Source Software; e.g. m:\dev\OSS). Create a subdirectory NHibernate within the OSS directory.

Right click on the NHibernate directory and choose the context menu "SVN checkout...". In the dialog box enter the url to the trunk as shown below. Double check the checkout directory and then press OK.

The SVN client will immediately start to download the NHibernate source code as well as the documentation. Depending on the speed of your Internet connection this may take some time to finish. You should see some thing like this

When the download is completed we can now compile NHibernate (remember: we have downloaded the source code and not the binaries!). Don't fear, this is an automated process. But wait, for this to work we need NAnt, another open source tool.

Download and install NAnt

You can get the latest release of NAnt here. This time we download the binaries (and not the source code) since it is "only" a helper tool for now. At the time of this writing I recommend downloading the 0.86 Beta 1 release since this release is the first one that can compile .NET 3.5 projects.

Download and extract the NAnt binaries (nant-0.86-beta1-bin.zip) into a directory on your developer machine (e.g. m:\dev\OSS\NAnt).

Compile NHibernate

Now it's definitively time to compile NHibernate. Open a console and go to the root directory of the NHibernate source (e.g. m:\dev\OSS\NHibernate\nhibernate). There you should find amongst others a file called default.build. This file contains the instructions for NAnt how to compile NHibernate. You can either compile NHibernate for .NET 3.5 (it's the default) or for .NET 2.0. In the console enter the following commands for the 2 scenarios (assuming you have NAnt installed in the same OSS folder as NHibernate)

For .Net 3.5 (default)
..\..\nant\bin\nant.exe
For .NET 2.0
..\..\nant\bin\nant.exe "-t:net-2.0"

The source code should now be compiled and after some time you should see some thing like this

It's important that the second last line states "BUILD SUCCEEDED".

After compiling the source code you should find a new sub-folder "build" in your NHibernate folder which contains all the binaries. Depending on the chosen scenario you will find the binaries in either a sub-folder "net-3.5" or "net-2.0". Didn't I tell you that it's easy...!

Prepare for TDD

Are we ready now? Nope! Since we're proud fellows of the ALT.NET way we don't want just start coding. No, we do TDD. Doing so we need a test framework. There exist several well known frameworks (e.g. NUnit, MbUnit, XUnit, etc.). In our examples we either use NUnit or MbUnit. Let's start with NUnit since NHibernate uses it too for its own test (you can download it from here). Note: we don't have to download it, since we can use the binaries provided with NHibernate (the only files we actually need are nunit.framework.dll and nuni.core.dll).

Team development and Continuous Integration

Although this article doesn't explain these two topics you still should be prepared to develop in a team and to use continuous integration. Why do I mention this? Well, we should do some further configuration of our environment to be prepared for this situations. Since it's easy to do - why not do it NOW...

A solution at best should have no external dependencies (ok, .NET we don't count here). If it has, then these dependencies should become a part of the solution (setup). What does this mean for us? Well our projects will have external dependencies, NHibernate is one of them. Another one is NUnit and still another one the database we'll use. A possible solution for this scenario is to not rely on assemblies registered in the GAC or any other "common" or "programs" folders of the system. Instead create a directory called e.g. SharedLibs which will be part of your solution and copy all external assemblies into this folder. The solution then only references external assemblies from this folder (an exception are all the .NET assemblies). If you use a source control system (and you should!) then put this folder under version control too!

Our first project

Create a folder FirstSample (e.g. m:\dev\projects\FirstSolution). Create a sub-folder SharedLibs. Copy the following assemblies into this folder (from the NHibernate bin folder which was created during compilation of NHibernate)

nunit.framework.dll
nuni.core.dll
nhibernate.dll
iesi.collections.dll
Castle.DynamicProxy2.dll
Castle.Core.dll
log4net.dll

Create a sub-folder src (e.g. m:\dev\projects\FirstSolution\src).

Run VS 2008 and create a new solution. Choose C# Class Library as Template and call it FirstSolution. Choose "m:\dev\projects\FirstSolution\src" as location and uncheck "Create directory for solution". Click OK now.

Immediately add an additional class library project to the solution and call it FirstSolution.Tests. This project will contain all our test classes (remember we're doing TDD). You should then have a structure similar to this one:

Summary

In this article I have shown how to prepare a developer machine for using the very latest version of NHibernate as an ORM tool in an application that is developed by using TDD and DDD. First we installed the prerequisites then we either downloaded the NHibernate binaries or we download and compiled the source code of NHibernate and finally we prepared a first .NET solution to start with.

In the next article I'll discuss how implement this very first NHibernate based solution.