Symptom 1:
Very poor performance. I’m talking 10+ seconds per page load, with no more than 5 queries being executed by NHibernate.

Symptom 2:
Empty log files. None of our log files had any data in on the live server, but they did on our other systems.

I decided to investigate the second symptom first, as it may be causing the first (ends up it was).

Firstly, I noticed that our logging was set to DEBUG. Must’ve been a leftover from when we first deployed NHibernate, very sloppy, I know. So I reset that to WARN, but it had no effect.

When files aren’t being written to, you should always check the directory permissions. Low and behold, it was a permissions problem. Our test server had different users allowed to write to the Logs directory than our production server. I granted the same users access, NETWORK SERVICE and IUSR_MACHINENAME in our case.

After I recycled the IIS worker processes, we were flying again. We’re back to having < 1sec page loads.

This is pure speculation, but what I believe was happening is this: Logging was set to DEBUG, so it was logging a lot. With each log call, the logger was failing to get write access to the files and throwing an exception, that exception would probably have propagated a bit too. The combination of the sheer amount of data being written to the log, and an exception per log call, were responsible for the severe slowdown.

So in short: Always make sure NHibernate has write access to its own log directory!

I’ve adopted a project from Jeremy Miller that I think has the potential to be a really useful tool. It’s called Fluent NHibernate, and it’s primarily a fluent API for mapping classes with NHibernate.

We’re all well aware how awesome NHibernate is, but I think we all also have a bit of a dislike for the amount of XML you need to write to get your classes mapped; not only that, but also how the mappings are distinctly separate from the rest of your application. They’re often neglected and untested. One of the core tenets of the project is that we need a more succinct, readable, and testable way of writing your mappings.

The API

Take the following simple hbm file:

<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"
    namespace="Eg" assembly="Eg">

    <class name="Customer" table="Customers">
        <id name="ID">
            <generator class="identity" />
        </id>

        <property name="Name" />
        <property name="Credit" />

        <bag name="Products" table="Products">
            <key column="CustomerID"/>
            <one-to-many class="Eg.Product, Eg"/>
        </bag>

        <component name="Address" class="Eg.Address, Eg">
            <property name="AddressLine1" />
            <property name="AddressLine2" />
            <property name="CityName" />
            <property name="CountryName" />
        </component>
    </class>
</hibernate-mapping>

Then compare it to the same mapping, created using the fluent API:

public CustomerMap : ClassMap<Customer>
{
  public CustomerMap()
  {
    Id(x => x.ID);
    Map(x => x.Name);
    Map(x => x.Credit);
    HasMany<Product>(x => x.Products)
      .AsBag();
    Component<Address>(x => x.Address, m =>
    {
        m.Map(x => x.AddressLine1);
        m.Map(x => x.AddressLine2);
        m.Map(x => x.CityName);
        m.Map(x => x.CountryName);
    });
  }
}

Firstly, you’ll note that there is a marginal reduction in lines of code, but that’s not what we’re particularly striving for. Instead we’re intent on reducing the verbosity and noise of the code. This manifests itself in a convention over configuration design for the API, where we choose the most common setups and use those as the default. For example with the id element in the hbm file, you’re required to specify what the generator type is; however, in our fluent API we check the type of your identity property and decide what generator we should use. Int’s and longs default to identity, while GUIDs use the guid.comb generator. You can change these explicitly, but when you are using the default, it greatly reduces the verbosity of your mapping.

Testability

Another one of our goals is to make your mappings more robust. I imagine most people have had the problem where you’ve renamed a property and not updated the mapping file; due to there being no compile time validation, the only way to catch these mistakes are at run time (hopefully you had tests to cover that!). With the way our API is designed, you use the actual properties on your classes to create the mapping, so there’s nothing to forget. If you rename a property, your IDE will either rename the property in the mapping, or fail at compilation.

We also want to help you verify that your mappings are set up properly, not just syntactically valid. So to make your integration tests a bit easier, we’re providing an API for testing your mappings.

[Test]
public void VerifyCustomerSaves()
{
    new PersistenceSpecification<Customer>()
        .CheckProperty(x => x.Name, "James Gregory")
        .CheckProperty(x => x.Age, 22)
        .VerifyTheMappings();
}

Behind the scenes the PersistenceSpecification creates an instance of your entity, then populates it with the values you specify through the CheckProperty method. This entity is then saved to the database, then reloaded through a separate connection. The returned entity is then compared to the one originally saved, and any differences fail the test. It’s a fairly standard integration test, except we’ve taken the time to write all the wiring up that needs to be done, so you don’t have to.

The Framework

We’re working towards our first official release, which will have a fairly solid implementation of the API. Once that’s out in the wild, we’re going to focus on our Framework.

Our framework is a layer that sits on-top of the API to provide an even better experience. We’re looking to integrate with your favorite container, which will reduce the code you need to write to integrate NHibernate into your system. Then we’re going to tackle extensible conventions, which will allow you to specify your own implied conventions for your application. For example, if you’re always going to call your identifier “ID”, then why should you have to specify it every time? You shouldn’t!

Development is progressing at a nice pace, and I expect we’ll be able to get our first release out within the next few weeks. The testing API hasn’t been kept quite as up to date as the main API, but we’re working on that too. It’s open-source, so suggestions and patches are welcome.

What this means is that you have full control over the data that is shown in the currently displayed page. Traditionally you’d retrieve the whole recordset then page it locally, but with the DeleGrid you can utilise your database/ORMs paging features.

To quote myself from when I first introduced the DeleGrid:

[The DeleGrid] came about because I wanted a nice way of implementing paging using NHibernate without having the grid know about it. I really didn’t want NHibernate to leave my data layer, so I needed a nice way of the grid calling my DAL with the paging parameters.

What’s new?

The biggest change in version 1.1 is the introduction of filtering. The filter isn’t generated in some black-box fashion, instead it’s defined by the programmer. It’s built up from the columns in the grid, which define their own filtering behavior.

The filter acts upon any columns in the grid that implement the IFilterableField interface. Implementing this interface in your own fields is easy, so you’re quickly able to create custom filtering behavior for your grid. An example would be a date column, that has a date-picker as a filter control.

I’ve chosen not to implement the wealth of appearance customisations that are available in the normal templated controls. This is down to two reasons, firstly I don’t agree with it, appearance should be controlled soley through CSS. Secondly, there are so many, I couldn’t be bothered. So you’re only able to attach CSS classes to the buttons and cells, and specify the image urls for the buttons.

An example implementation

The grid now has a companion project, it’s own data library. This separation is to keep you from having to reference System.Web in your data-layer. To use the DeleGrid in your project you’ll need to reference JAGregory.Controls.DeleGrid.dll and the JAGregory.Controls.Data.dll in your web project, then reference JAGregory.Controls.Data.dll in your data layer, if they’re separate projects.

So to begin with, add the reference to JAGregory.Controls.DeleGrid.dll and JAGregory.Controls.Data.dll into your web project. This will allow you to use the DeleGrid in your page. Once you’ve done that, you’ll need to reference the control in your page, you can either do this using a Register tag in your page, or in the web.config as so:

<pages>
  <controls>
    <add tagPrefix="jag" namespace="JAGregory.Controls"
      assembly="JAGregory.Controls.DeleGrid" />
  </controls>
</pages>

With that in place, you can now put the DeleGrid into your page:

<jag:DeleGrid ID="grid" Runat="server" AllowFiltering="true"
  AutoGenerateColumns="false">
    <FilterStyle ToggleOnImageUrl="img/find.png" ToggleOffImageUrl="img/find.png"
      ExecuteImageUrl="img/go.png" />
    <Columns>
        <jag:FilterableTextField HeaderText="Name" DataField="Name" />
        <jag:FilterableBooleanField HeaderText="Active" DataField="Active" />
    </Columns>
</jag:DeleGrid>

n.b. In this example I’m using a Customer object to bind against it, which simply has the Name and Active properties.

For this grid we’ve set AllowFiltering to true, which enables the filter, then we’ve set AutoGenerateColumns to false so we can add our own custom columns. The two columns both implement the aforementioned IFilterableField interface, which allows them to define their own filtering behavior.

I’ve also set the image urls so the buttons will be visible.

Now that the page is set up, we need to get down to the binding. In your code-behind:

protected override void OnInit(EventArgs e)
{
    base.OnInit(e);

    // attach the events for requesting the data and totals
    grid.TotalRecordCountRequest += grid_TotalRecordCountRequest;
    grid.PageDataRequest += grid_PageDataRequest;
}

protected override void OnLoad(EventArgs e)
{
    base.OnLoad(e);

    if (!IsPostBack)
        grid.DataBind();
}

What’ve just done is attach the TotalRecordCountRequest and PageDataRequest handlers to the grid, which respectively fetch the total record count for the full grid, and fetch the current page of data from the database; the implementations are below.

private IEnumerable grid_PageDataRequest(object sender, PageDataRequestEventArgs e)
{
    CustomerRepository repos = new CustomerRepository();

    // get the requested page of data from the database
    return repos.FindAllPaged(e.Range, e.Sort, e.Filters);
}

private int grid_TotalRecordCountRequest(object sender, DataRequestEventArgs e)
{
    CustomerRepository repos = new CustomerRepository();

    // get the total records
    return repos.GetAllCount(e.Filters);
}

I’m using a repository pattern to handle data-access. In the PageDataRequest handler we’re taking the range, sort, and filter info that the grid passed us and sending it off to the repository to get the data. Similarily the TotalRecordCountRequest handler does a similar thing but without the range or sort info.

That’s it really for using the DeleGrid, you just need to take the filter info and handle it using your specific ORM.

Repository implementation

Ok I’ll throw you a bone, here’s the repository implementation to show how easy it is using NHibernate:

public class CustomerRepository
{
    /// <summary>
    /// Creates a NHibernate ICriteria based on the filters.
    /// </summary>
    /// <param name="filters">Filters to apply.</param>
    /// <returns>ICriteria</returns>
    private ICriteria CreateFilteredCriteria(FilterCriterionCollection filters)
    {
        ICriteria criteria = SessionManager.CurrentSession
            .CreateCriteria(typeof(Customer));

        // criterion handling - write this yourself depending on how your
        // db filters (and what filter types you're supporting)
        foreach (FilterCriterion filter in filters)
        {
            if (filter.Type == typeof(string))
                criteria.Add(Expression.Like(filter.FieldName, "%" + filter.Value + "%"));
            else if (filter.Type == typeof(bool))
                criteria.Add(Expression.Eq(filter.FieldName, filter.Value));
        }

        return criteria;
    }

    /// <summary>
    /// Gets the total record count from the database using the filters.
    /// </summary>
    /// <param name="filters">Filters to apply before getting the count.</param>
    /// <returns>Total number of records in the filtered list</returns>
    public int GetAllCount(FilterCriterionCollection filters)
    {
        return CreateFilteredCriteria(filters)
            .SetProjection(Projections.Count("ID"))
            .UniqueResult<int>();
    }

    /// <summary>
    /// Gets one page of data from the database.
    /// </summary>
    /// <param name="range">Select range (start ID and number of records).</param>
    /// <param name="sort">Sorting to apply.</param>
    /// <param name="filters">Filters to apply.</param>
    /// <returns>List for one page of data.</returns>
    public IList<Customer> FindAllPaged(SelectRange range, SortInfo sort, FilterCriterionCollection filters)
    {
        // create the criteria using the filters, then set the range
        ICriteria criteria = CreateFilteredCriteria(filters)
            .SetFirstResult(range.Start)
            .SetMaxResults(range.Size);

        // only add the sort if one is specified
        if (!string.IsNullOrEmpty(sort.Field))
        {
            if (sort.Direction == Direction.Asc)
                criteria.AddOrder(Order.Asc(sort.Field));
            else
                criteria.AddOrder(Order.Desc(sort.Field));
        }

        return criteria.List<Customer>();
    }
}

The CreateFilteredCriteria method is doing most of the leg work. It takes creates an NHibernate criteria, then adds any filter criterions to it. It iterates the filters collection, checking their type and adding the appropriate NHibernate criterion. Simple!

The example project

I’ve attached a sample project that uses the grid to display a collection of customers that are paged and filtered. The example uses a SQLite database with NHibernate for data-access, I’ve done this to keep the extraneous code to a minimum.

Downloads

The DeleGrid is open-source under the new BSD License; read the license for what you’re allowed to do.

You can download the source here: Download Source.
You can download the latest binary here: Download Binary.
You can download the example project here: Download Example.

The source is also accessible from Subversion at: http://jagregory.googlecode.com/svn/trunk/DeleGrid/ (using user jagregory-read-only)

I encountered a problem while binding a complex object to a GridView, in that the BoundField doesn’t support specifying a nested value in it’s DataField property. So if you have a list of Customer’s, and want to display the TelephoneNumber property from inside the customer’s ContactDetails property, you’re out of luck.

<asp:BoundField DataField="ContactDetails.TelephoneNumber" />

The above would fall over with an exception along the lines of:
A field or property with the name 'ContactDetails.TelephoneNumber' was not found on the selected data source.

This is a mind-boggling flaw in the BoundField, with the main solution being to create a nested GridView, which is just overkill for most situations. This problem especially rears it’s ugly head if you’re using an ORM layer such as NHibernate or SubSonic.

So what have I done? I’ve just gone and created a solution to this problem.

Introducing the ObjectField, a GridView field that allows binding against hierarchical structured objects. In short, it takes a BoundField and splits it on full-stops (periods!) using each element to find an object.

<jag:ObjectField DataField="ContactDetails.TelephoneNumber" />

The above is now possible! Huzzah.

Extras

There’s one extra thing you should know about. The field has a couple of additional properties that can be useful.

The first is AllowNulls which defaults to true, this will make the field return silently when a null is encountered anywhere along the object hierarchy; this can be useful if you know that there might be a null somewhere along the lines.

The second property is NullValue, which is displayed by the field when AllowNulls is true and a null is encountered. Setting this value allows you to give a user-friendly message if a value is null.

Downloads

The ObjectField is open-source under the new BSD License; read the license for what you’re allowed to do.

The version of the ObjectField that this post refers to is now out of date. Please go to the ObjectField 1.1 post for the latest version.

Picture a simple page, with a DeleGrid control, being bound using NHiberate. Baring in mind how the DeleGrid works, two queries were being executed, one to return the first page of data and another to get the total row-count for the grid. These queries were identical apart from the paging in one, and the projection in the other.

Upon execution of the second query, NHibernate was throwing a SqlTypeException for a SqlDateTime overflow. SqlDateTime overflow. Must be between 1/1/1753 12:00:00 AM and 12/31/9999 11:59:59 PM. This was pretty bizarre. Why on earth would the first query succeed (and bring back records, fully populated), but the same query again would die.

A good place to start for NHibernate debugging is always the logs, so I delved in. I discovered NHibernate was attempting to execute an update statement just before it tried the second query. It just kept getting stranger, why would a straightforward query cause an update?

I thought i’d investigate why the update statement was failing first, then I’d tackle the problem of why it was even updating at all. Looking at the query I identified the column that was causing the exception, it was (as expected) a DateTime column that was trying to be set to DateTime.MinValue. This exception is thrown because .Net and SQL Server have different ideas over what the minimum value for a DateTime should be.

Now, why would this column be being set at all? Well, it ends up that the column in the database was nullable, but the property in the object wasn’t. So because DateTime is a value type and cannot be set to null, NHibernate was populating it with the closest value to null as it could manage.

That was the key, as soon as I had that realisation, it was obvious what the problem was.

NHibernate knew that the database had a nullable column, but it had to manage with the non-nullable field on the object. When it came to run the second query, it noticed that the property wasn’t null as the mapping file said it should be, so it determined the value must have changed. It then attempted to persist those changes before executing the query!

To break it down

1. Nullable column pulled into a non-nullable field forces NHibernate to create the smallest value it can.
2. NHibernate then checks for any changes, expecting a null on that field but finding a value.
3. Object now considered dirty because value has allegedly changed.
4. NHibernate performs an update before it pulls back the data agian.

So the fix was simply to make the DateTime in the object a DateTime?, a nullable DateTime. That got rid of the false update, and fixed my queries. Simple when you know what the problem is.

So the moral of the story is: Make sure everything is in sync – schema, mappings and POCOs.