Øyvind Valland's Babel Lutefisk .net

MicroSpec

2014-01-23T20:31:00.000+00:00

In the last two or three years I have been doing a lot of BDD, and I have really enjoyed it. Introducing BDD in a project for my latest client has been particularly rewarding. This company has previously relied heavily on manual regression testing and the majority of its QA staff were not trained sufficiently in development to be able to write their own automated tests. As mentioned this lead to a heavy reliance on manual testing but it also lead to something else: the unit and integration tests that were written by developers were largely ignored by the QAs because they did not understand them. "Not understanding" meant more than that they couldn't read the test source code and work out what the tests did. The tests were inconsistently named and poorly organised, and the QAs felt that they could not assess whether the appropriate test coverage had been achieved (real coverage, not a percentage of lines covered). This lead to unit and integration tests not being run as part of builds.

I've oversimplified this scenario - there are many reasons other than the QAs' inability to write and understand automated tests that led to this situation. However, the point is that that was the state of affairs - and things needed to be done. The reliance on manual regression testing meant releases were incredibly infrequent, and a full regression test cycle could easily take six weeks. If that's not madness, I don't know what is.

The company had brought in a new head of QA to sort out this mess, and his directive was fairly simple. Automate all tests that can be automated without excessive cost, write all tests as specifications (preferably with a Gherkin-style language and/or SpecFlow), and prefer BDD over TDD for new development work. Following this directive many existing manual regression tests were created as UI automation tests using SpecFlow and Selenium, existing integration and unit tests were cleaned up and made part of the build, and the company as a whole (well, more or less) attempted to embrace the BDD style of specifying test cases.

However, there was still the problem of new unit and integration tests. Developers across the organisation were used to writing their tests with NUnit and Moq. A typical, contrived, test could look something like:

[Test]
[ExpectedException(typeof(InvalidOperationException))]
public void ExceptionIfOrderIsNotDispatched()
{
  var order = new Order(){
                           Id= 12345;
                           //... other initialisation
                         };
  var refundAmount = 12.50;
  _orderService = new Mock();
  _orderService.Setup(x => x.Retrieve(order.Id)).Returns(order);

  var billingService = new BillingService(_orderService.Object);

  //throws because we haven't dispatched the order yet
  billingService.Refund(order.Id, refundAmount);
}

This test is simple and if you're a developer you can probably read it just fine. But if you're not a developer this is can be hard to understand. What are we testing, exactly? There is a comment in the test that says the order hasn't been dispatched and that's why an exception will be thrown - but what if the comment wasn't there? Even if you are a developer and you come across this test you're likely to have to go digging to really understand what the test is all about. Whether or not you think this style of writing tests is problematic is a matter of taste and preference, but what we realised in our project was that the non-developer QA who wanted to assess whether the right level of test coverage had been achieved would often be completely at a loss as to what had been tested.

In order to address this particular problem we decided that we should write all our unit and integration tests as specifications. We decided that the test we've already discussed should be written like this:

  
  Given I have an order
    And the order has not yet been dispatched
  When I try to refund an amount against the order
  Then an InvalidOperationException is thrown

This is a test that anybody can read and understand, regardless of technical ability, so we decided we'd write all our tests in this way so that anyone could look at any test, be it UI Automation test, database integration test or unit test and easily understand not only what it does, what it tests and why it failed (if that were the case).

The first, and rather obvious, choice of tooling for definig the tests was SpecFlow. However, we soon realised that it wasn't a good choice for this organisation. There was (not surprisingly) some resistance to having to use a new tool from the developers - why couldn't they just keep using NUnit like they had? Also, we quickly realised that although non-technical QAs now certainly could help define unit tests using Gherkin they typically didn't. So we decided to take matters in our own hands and create our own tiny framework, one that would give the best of both worlds: Specification style tests written using nothing but NUnit and Moq. I've called this framework MicroSpec.

MicroSpec is essentially one code file (I've taken a leaf out of Dapper's book) containing a single class, the Specification class, which implements four interfaces. The Specification class is an abstract class which executes your tests and prints the specification to the console as the tests run. You write tests by specifying each step in the test as a separate method and passing these steps as delegates to the Specification class' Given-When-Then methods. The test we've already looked at, above, could be written like this:

[Test]
public void ThrowsExceptionIfIssuingRefundBeforeOrderIsDispatched()
{
  Given(i_have_an_order).
  And(the_order_has_not_yet_been_dispatched).
  When(i_try_to_refund_an_amount_against_the_order).
  ThenAn().IsThrown();
}

Here we have three methods which define the steps in our test definition. They are all called by the specification class:

```
i_have_an_order
```
creates a new order for use by our test
```
the_order_has_not_yet_been_dispatched
```
ensures that the order created in the previous step has not been dispatched. This might execute some logic on the order or just assert that the state of the order is correct.

i_try_to_refund_an_amount_against_the_order

would issue a refund against the order.

The last step in the test is a call to ThenAn which is a method that's used to capture expected exceptions. Chaining ThenAn (or it's brother ThenA for those who care about grammar) with IsThrown() asserts that a specific exceptions has been thrown during the course of the test (if you want to make sure an exception was _not_ thrown, you'd end the chain with IsNotThrown() instead).

As the test runs the Specification class creates console output before each step is executed. I'll repeat the output of this test here so you don't have to scroll:

  Given I have an order
    And the order has not yet been dispatched
  When I try to refund an amount against the order
  Then an InvalidOperationException is thrown

As you can see, the console output takes the names of the delegates/steps and prefixes them with the type of step: "Given", "When", "Then", "And", "Then an", "Then a", "is thrown" or "is not thrown". But the console output does not have to be constrained to just the name of the steps within the test. You can also include test parameters by following the following naming conventions:

integers surrounded by underscores, e.g. _0_, are replaced by the value of the corresponding parameter passed to the step.
integers preceded by the letter "g" and surrounded by underscores, e.g. "_g0_", are replaced by the name of the corresponding generic parameter defined by the step.

To illustrate, imagine that the value of the refund issued in the above test matters. You could then rewrite the test like this:

[Test]
public void ThrowsExceptionIfIssuingRefundBeforeOrderIsDispatched()
{
  var refundAmount = 20;
  var currencySymbol = "GBP";

  Given(i_have_an_order).
  And(the_order_has_not_yet_been_dispatched).
  When(i_try_to_refund_0__1_against_the_order, refundAmount, currencySymbol).
  ThenAn().IsThrown();
}

When run the output of the test would be:

  Given I have an order
    And the order has not yet been dispatched
  When I try to refund 20 GBP against the order
  Then an InvalidOperationException is thrown

Writing unit tests in this manner takes a little getting used to, and I find that it generally takes a little longer to complete the first couple of tests than when following a more traditional approach. That's because you've got a little more "infrastructure" to create in order for your tests to run. Managing state between test runs can also be a little trickier sometimes. But the tests themselves become infinitely more understandable and readable than tests written in a traditional way, and I think that the extra effort you have to put into defining your steps clearly in English language not only helps make your tests better but also aids in designing the software you're building. Describing the pictures you have in your mind with words while you're in the early stages of coding up a solution is a good way of vetting your design ideas.

Anyway - MicroSpec works for me, and it's bridged the gap between non-technical QAs who want to read and understand low-level (tests) and the developers that write them. It's the way I currently like to write my unit tests. If you want to give it a try, you can download it from BitBucket. Any thoughts and comments are most welcome.

A tidy way to organise your JavaScript

2013-01-03T16:55:00.002+00:00

Last year I was lucky enough to work on several projects with some very good UI developers. Doing so enabled to greatly improve my own skills in that area, and one of the biggest 'take-aways' from these projects was the way in which these guys preferred to manage the JavaScript in a project. In this post I will outline how they did it, and why they did it this way.

Note: I really like this approach because it's solved (and neatly so) a problem I never seemed to sort out in a satisfactory manner on my own. I am sure there are many other good ways of doing this - I'm just particularly fond of this solution. I welcome discussion on the matter!

The basic idea behind how the JS should be organised can probably be summed up in three simple points:

Everything is namespaced (and thus organised accordingly).
Every page that requires JS has a single 'page class' that creates and initialises JS components that work on that particular page. A 'page class' should not do anything except initialisation.
All JS code that provides functionality to a page should is organised into logical components.

I'll address each bullet point in order, but before doing so let's have a quick way at how the JS files are organised in the web project (or on disk, for that matter). Note that the code examples and screen shots are from a ASP.NET MVC4 project in VS2012.

As you can see from the picture on the right I have modified the default project structure somewhat. In the "Content" folder I have created a "Scripts" folder (with multiple sub-folders) and also a "Styles" folder. In this post I'll only talk about the "~/Content/Scripts/MyApp" folder and its files/sub-folders. I'll mention here, though, that the "~/Content/Styles" folder contains the "site.css" stylesheet and the "themes" folder from the original project. The "~/Content/Scripts/Plugins" folder contains all the scripts that were originally placed in the "~/Scripts/" folder, and the "~/Content/Scripts/Jasmine/" folder will hold all Jasmine files and tests.

Now, back to the bullet points. We'll address them in order, starting with:

Namespaces

The "~/Content/Scripts/MyApp" folder should be named in accordance with whatever your application is called. Inside this folder, place a single JS file named in accordance with whatever the root namespace of you application's JS should be. I usually use the application name as the root namespace, hence I name the root namespace file MyApp.js.

Inside this file I simply declare the root namespace like this:

  
  var MyApp = {};

You'll notice that inside the "~/Content/Scripts/MyApp/" folder there is also a "Pages" folder. This is the folder that will hold all the JS files that define the previously mentioned page classes. The "Pages" folder has two files: MyApp.Pages.js, which defines the MyApp.Pages namespace...

  
  MyApp.Pages = {};

... and also MyApp.Pages.Home.js, which defines the "Home" page class. We will get onto the details of this particular file in a second.

Although we've only talked about two folders and three files, I've hinted at a pattern with regard to namespaces. Every folder under "~/Scripts/Content/MyApp/" represents and is named in accordance with a namespace. That namespace is defined in a JS file named exactly the same as the full namespace, e.g. MyApp.Pages.js or MyApp.MappingComponents.js.

In this example there are only two namespaces, and that's fine to start with. I keep all components in the root namespace unless some are completely page specific (thus not really reusable) or unless there are too many of them so that it becomes useful to group them.

Page classes

All page classes are defined under the "MyApp.Pages" namespace. The purpose of a page class is to create and initialise all JS (components) required by a specific page in your web application. In this example we have the MyApp.Pages.Home class. Let's take a closer look:

  $(function () {
    MyApp.Pages.Home = new function () {
      this.CountryMap = new MyApp.GoogleMap($('#map_canvas')[0]);
      this.CountryMap.init(66.196009, 14.143799, 4);
    }
  });

All this page class does is create a GoogleMap component, and initialise it. On creation the component is passed a reference to the div that we want to render the map within, and then it is initialised by calling the init method of the component and passing in the latitude, longitude, and map zoom level.

This is a contrived example, so I've hardcoded the initialisation of the map instance. In a 'real world' scenario you'd probably have your page class either read the lat/lng from hidden form fields on the page or perhaps request the lat/lng by making an ajax call. The point is, beyond doing the necessary work for creating and initialising components, the page class is pretty simple.

Components

All JavaScript for a page should be encapsulated in (reusable) components, and each component should be defined in its own, separate file. There are two reasons for this: It makes your JS more manageable because each component is defined in one place and has one purpose. It also makes your JS easier to test, because each component is discrete. The latter point is still subject to how you choose to build your components, though, and I'm not going to go into testing of JS here.

Let's have a quick look at the GoogleMap component that's used by the Home page class:

  MyApp.GoogleMap = function (canvas) {
    this.canvas = canvas;
  };

  MyApp.GoogleMap.prototype.generateMap = function (lat, lng, zoomLevel) {
    var canvasElement = this.canvas[0];
    var mapOptions = {
        center: new google.maps.LatLng(lat, lng),
        zoom: zoomLevel,
        mapTypeId: google.maps.MapTypeId.ROADMAP,
    };

    this.map = new google.maps.Map(canvasElement, mapOptions);
  };

  MyApp.GoogleMap.prototype.init = function (lat, lng, zoomLevel) {
    this.generateMap(lat, lng, zoomLevel);
  };

This is a very simple component that creates a Google map instance on a div in your HTML markup. As you can see, when an instance of this component is created you pass it a reference to the div that should be used as the canvas for the map. This reference is then stored so that when the init() method is called the map can be drawn within the given div.

Putting it together

In order to make all of this work we just have to do the following:

Add a reference to the Google Maps API within the tag of _Layout.cshtml
Add references to "~/Content/Scripts/MyApp/MyApp.js" and "~/Content/Scripts/MyApp/Pages/MyApp.Pages.js" within _Layout.cshtml
Add references to "~/Content/Scripts/MyApp/MyApp.GoogleMap.js" and "~/Content/Scripts/MyApp/Pages/MyApp.Pages.Home.js" within the "~/Views/Home/Index.cshtml" view.
Add a div with the id "map_canvas" within the "~/Views/Home/Index.cshtml" view. Oh - and you should style it, too, to the desired size.

With all this in place, the home page should look something like this:

Points to note

While I really like this solution, there are a couple of things to beware of before you start using it yourself. The most important thing to realise is that as your site grows, so will the number of JavaScript files. If you reference each file separately the web browser will potentially have to make a lot of requests in order to render a single page, and this is bad for performance. Therefore you should utilise bundling so that multiple files can be combined into a single downloadable unit.

While bundling is really helpful for the above scenario, you should also exercise some restraint when defining these. Because of the number of JS files you might have in a large project it can be tempting to "bundle everything" into one big, eh, bundle and reference that everywhere. That's ultimately counter productive because the web browser will have to download more than what's required for a single page, and it will probably lead to a lax attitude towards the boundaries that you've defined within your JS, too.

MVC Lower-case URLs

2011-11-07T22:47:00.007+00:00

SEO guidelines usually recommend that a site's URLs should be kept in all lower-case. The reason for this is that search engines and web servers alike (IIS is a notable exception) will treat two differently cased URLs as two different resources. While the host name of a URL is case insensitive (i.e. there's no difference between http://www.mysite.com and http://www.MySite.com) the resource path is not. Therefore http://www.mysite.com/home and http://www.mysite.com/Home are considered different resources.

While this might not make much sense semantically, consider this: The world's most widely used web server, Apache, treats URLs as case sensitive. Therefore the above URLs do, in fact, represent two different pages. As such, search engines treat these two URLs as different pages, too - and if your website doesn't care about URL casing you might end up with a split index for your pages.

So - how do we ensure that your website generates only lower-case URLs? With ASP.NET MVC this is easy. All you need is:

A LowercaseRoute class
An extension method for RouteCollection
An extension method for AreaRegistrationContext

And yes - the solution I'm about to detail will work with MVC Areas.

The LowercaseRoute class extends the Route class and basically lets that class do all the work. LowercaseRoute just ensures that the host and path portions of he URL are turned to lower-case while the querystring portion is left alone:


internal class LowercaseRoute : Route
{
    public LowercaseRoute(string url, IRouteHandler routeHandler)
            : base(url, routeHandler){}

    public LowercaseRoute(string url, RouteValueDictionary defaults, IRouteHandler routeHandler)
         : base(url, defaults, routeHandler){}

    public LowercaseRoute(string url, RouteValueDictionary defaults, RouteValueDictionary constraints, IRouteHandler routeHandler)
            : base(url, defaults, constraints, routeHandler){}

    public LowercaseRoute(string url, RouteValueDictionary defaults, RouteValueDictionary constraints, RouteValueDictionary dataTokens, IRouteHandler routeHandler)
            : base(url, defaults, constraints, dataTokens, routeHandler){}

    public override VirtualPathData GetVirtualPath(RequestContext requestContext, RouteValueDictionary values)
    {
        var path = base.GetVirtualPath(requestContext, values);

        if (path != null)
        {
            var virtualPath = path.VirtualPath;

            if (virtualPath.LastIndexOf("?") > 0)
            {
                var leftPart = virtualPath.Substring(0, virtualPath.LastIndexOf("?")).ToLowerInvariant();
                var queryPart = virtualPath.Substring(virtualPath.LastIndexOf("?"));
                path.VirtualPath = leftPart + queryPart;
            }
            else
                path.VirtualPath = path.VirtualPath.ToLowerInvariant();
        }

        return path;
    }
}

The RouteCollection extension method creates an instance of LowercaseRoute and adds it to the route collection:


public static Route MapRouteLowercase(this RouteCollection routes, string name, string url, object defaults)
{
    if (routes == null)
        throw new ArgumentNullException("routes");

    if (url == null)
        throw new ArgumentNullException("url");

    var route = new LowercaseRoute(url, new MvcRouteHandler())
                    {
                        Defaults = new RouteValueDictionary(defaults)
                    };

    routes.Add(name, route);
    return route;
}

The AreaRegistrationContext extension method calls the MapRouteLowercase extension method on RouteCollection and also adds the current context's AreaName property to the route's DataTokens collection. This second step is crucial for areas to work:


public static Route MapRouteLowercase(this AreaRegistrationContext context, string name, string url, object defaults)
{
    var route = context.Routes.MapRouteLowercase(name, url, defaults, constraints, namespaces);

    route.DataTokens["area"] = context.AreaName;
    return route;
}

And that's all you really need. Of course, you may want to add more extension methods of your own so that you can add route constraints or any other data that your route handler may need (such as namespace differentiators). But I'll leave that for you to flesh out on your own. Happy coding!

Route Constraints: Working with conflicting routes in MVC

2011-11-01T12:48:00.005+00:00

Routing is one of the things in the MVC framework that seems to just 'get me' every once in a while. Routing isn't that hard - it's pretty straight forward stuff. Routing is something you should, ideally, set up once - and then forget about. In order to do this, though, you need to have a plan up front - and you don't always have that (personally I think it's best if you've got a site map and a URL schema worked out before you start). If you add routes as you need them you can end up with more routes than you need and route conflicts that you didn't foresee.

This isn't intended as a post about MVC routing in general. Rather I wanted to post about a little piece of work I had to do in order to make use of two routes that conflict with one another. I think these routes highlight the most common problem people have when they're getting to grips with MVC routes; your URL is matched by the wrong route entry.

I like to keep things simple, and I don't like making extra work for myself. As such I like the default route that any Visual Studio MVC project comes set up with:

routes.MapRoute(string.Empty, "{controller}/{action}/{id}",
  new { controller = "Home", action = "Index", id = UrlParameter.Optional });

This route entry is simple to understand and you can build large applications based entirely on this single route entry. Of course, you may want to add some "pretty" routes as well such as "/login" or "/signup" - but that single route is really all you need. That is, until you decide that not all your URLs should be on the form "{controller}/{action}/{id}."

In my case, I also needed a route like this:

routes.MapRoute(string.Empty, "{controller}/{id}",
  new { controller = "Clubs", action = "Index", id = UrlParameter.Optional });

This second route is important to my application because it's used to display certain entities by their unique identifier. Such entities can be a member of the site, a club, or a store. Example URLs are:

http://mywebsite.com/members/oyvind
http://mywebsite.com/stores/oyvindsmegamart
http://mywebsite.com/clubs/oyvindsgreatbigfanclub

As you can tell from the example URLs, several controllers can be mapped by this route and, if they are, the route should always map to the "index" action method and pass in the "id" parameter. But, if you add these routes to your application, you'll run into trouble because they conflict with each other. Let's look at why.

An incoming URL will be matched by one route and one route only. Routes are examined one by one and the first match is the one that will be used. This means that the order in which we add routes is important. We always want our most specific routes to be listed first. Let's apply this principle to our two routes:

routes.MapRoute(string.Empty, "{controller}/{id}",
  new { controller = "Clubs", action = "Index", id = UrlParameter.Optional });
routes.MapRoute(string.Empty, "{controller}/{action}/{id}",
  new { controller = "Home", action = "Index", id = UrlParameter.Optional });

Here I've added the "{controller}/{id}" route first because I feel this is the more specific of the two routes. Now let's look at a sample URL:

http://mywebsite.com/members/oyvind

If we break this URL down you'll see that the "/members" section of the URL will map to the "{controller}" portion of both routes. Also, the "/oyvind" section of the URL will map to the "{id}" portion of the first route. Happy days! We have a match! It looks like our two route entries might work after all.

But not so fast. What about this URL?

http://mywebsite.com/account/changepassword

This URL should look familiar to you as it's more of a traditional MVC route; in fact, it's a classic default route for any standard MVC project. But will this work with our two route entries? The "/account" section of the URL will map to the "{controller}" portion of both routes. The "/changepassword" section of the URL will map to both the "{id}" portion of the first route, and the "{action}" portion of the second route. However, because the first match wins, the first route is chosen and the request will end up being directed to the Index action method on the AccountController class, with an id parameter of "changepassword"... this isn't what we intended.

What happens if we change the order of the routes?

routes.MapRoute(string.Empty, "{controller}/{action}/{id}",
  new { controller = "Home", action = "Index", id = UrlParameter.Optional });
routes.MapRoute(string.Empty, "{controller}/{id}",
  new { controller = "Clubs", action = "Index", id = UrlParameter.Optional });

Let's look at the last URL from the previous example first:

http://mywebsite.com/account/changepassword

The "/account" section of the URL will map to the "{controller}" portion of both routes. The "/changepassword" section of the URL will map to both the "{action}" portion of the first route, and the "{id}" portion of the second route. In this case our first route will be selected - and the request will be directed to the ChangePassword action method on the AccountController (with an empty id). This is the desired result for this URL. But what about this URL?

http://mywebsite.com/members/oyvind

The "/members" section of the URL will map to the "{controller}" portion of both routes. The "/oyvind" sectin of the URL will map to the "{action}" portion of the first route, and the "{id}" portion of the second route. Because of the order of precedence, the first route will be selected and our request will be directed to the Oyvind action on the MembersController, with an empty id. Most likely we'll end up with a "404 - Not Found" because I doubt very much you'll have an action called Oyvind on any of your controllers.

I need both routes to work, but they clearly conflict with each other and changing the order of the routes doesn't actually help. What can I do? Somehow I need to help the MVC framework understand when to pick one route over the other. Thankfully there's a built-in mechanism we can leverage to help us: the route constraint.

When you add a route to the route table you can specify that this route has certain constraints. A constraint applies to a portion of the route (for example the "{id}" portion) and can set out that this portion has to match certain values, be of a certain format, or exclude specific values. When defining routes you pass the constraints as a third parameter to the MapRoute method:

routes.MapRoute(string.Empty, "{controller}/{action}/{id}",
  new { controller = "Home", action = "Index", id = UrlParameter.Optional },
  new { action = "MySpecialAction"});

In this contrived example I've specified a route using the standard/default route pattern, but I've specified a constraint for the "{action}" portion of the route. The constraint states that unless "{action}" equals "MySpecialAction" the route will not be matched. This route constraint is actually a regular expression constraint, so you if you want to allow "{action}" to include not only "MySpecialAction" but also "YourSpecialAction" you can alter the route entry as follows:

routes.MapRoute(string.Empty, "{controller}/{action}/{id}",
  new { controller = "Home", action = "Index", id = UrlParameter.Optional },
  new { action = "MySpecialAction|YourSpecialAction"});

You can read more about route constraints here (http://www.asp.net/mvc/tutorials/creating-a-route-constraint-cs) as I'm not going to dwell on the specifics here. Rather, I want to get on with the problem at hand. Let's break it down a little:

I want to use the default route "{controller}/{action}/{id}" as much as possible. This is the route I want to base my whole site on.
In some special cases I want the route "{controller}/{id}" to take precedence. At the moment I know that I want this route to take precedence for the MembersController, the ShopsController, and the ClubsController.
I want to be able to define action methods other than Index on the MembersController, ShopsController, and ClubsController - and I want these actions to be matched by the default route.

The problem we encountered with the routes in their raw, unconstrained, form is that the "{id}" portion of a route will happily match the "{action}" portion of the other route, and vice versa. Since we add the most specific route first

routes.MapRoute(string.Empty, "{controller}/{id}",
              new { controller = "Clubs", action = "Index", id = UrlParameter.Optional });

we need to make sure that the "{id}" parameter does not match any action methods on the controller. Also, we don't want this route to apply to all controllers, so we need to constrain the "{controller}" portion of the route to the desired controllers. Let's start with the controller constraint first. We want this route to only apply to the ClubsController, ShopsController, and MembersController:

routes.MapRoute(string.Empty, "{controller}/{id}",
  new { controller = "Clubs", action = "Index", id = UrlParameter.Optional },
  new { controller = "Clubs|Members|Shops"});

That's all we need to do.

The other constraint, however, is a little bit more involved. The route should not be matched if the "{id}" portion of the URL matches any of the action methods on any of the controllers that this route applies to. We can do this by applying another regex constraint which contains the names of all the action methods on these controllers:

routes.MapRoute(string.Empty, "{controller}/{id}",
  new { controller = "Clubs", action = "Index", id = UrlParameter.Optional },
  new
{
   controller = "Clubs|Members|Shops",
   id = "ClubMembers|Photos|News|Deals|Staff|Wall|About|OpeningHours|Info|Friends"
});

The above example is contrived - but it attempts to highlight a problem with the approach. Not only will this list of action names grow very quickly, you will also have to remember to add action names to this list whenever you add an action on any of the controllers (or modify the list if you change the name of any of the action methods). This approach will work, but it's not a very maintainable solution.

A better approach would be to use a custom route constraint. A custom route constraint is a class which implements the IRouteConstraint interface. This interface defines a method called Match:

bool Match(HttpContextBase httpContext, Route route, string parameterName, RouteValueDictionary values, RouteDirection routeDirection);

The job of the custom route constraint is to decide if a given route parameter is valid for the given route. We want to check a single parameter, "id" against a potentially large list of values. To this end, I've created a ValuesConstraint class:

public class ValuesConstraint : IRouteConstraint
{
  private readonly bool _include;
  private readonly string[] _values;

  public ValuesConstraint(params string[] values) : this(true, values){}
  public ValuesConstraint(bool include, params string[] values)
  {
      _include = include;
      _values = values;
  }

  public bool Match(HttpContextBase httpContext, Route route, string parameterName, RouteValueDictionary values, RouteDirection routeDirection)
  {
      return _include && (_values.Contains(values[parameterName].ToString(), StringComparer.InvariantCultureIgnoreCase));
  }
}

The ValuesConstraint class is instantiated by passing in the list of values, and an an optional flag which indicates if the route parameter should be a match or not be a match for these values. It can be used in the following fashion:

routes.MapRoute(string.Empty, "{controller}/{id}",
new { controller = "Home", action = "Index", id = UrlParameter.Optional },
new
{
controller = "Clubs|Members|Shops",
id = new ValuesConstraint(false, "ClubMembers", "Photos", "News", "Deals", "Staff", "Wall", "About", "OpeningHours", "Info", "Friends")
});

While the above would work it doesn't actually solve the problem of maintainability, because we're still hard-codign a list of strings representing the action methods on our controllers. So, the final piece of the puzzle is to create a method that outputs a list of all the action methods on controllers of our choosing:

private string[] GetActionNames(params Type[] controllers)
{
  var actionNames = new List();
  foreach(Type controllerType in controllers)
  {
MethodInfo[] methodInfos = controllerType.GetMethods(BindingFlags.Public | BindingFlags.Instance | BindingFlags.DeclaredOnly);
 foreach(var method in methodInfos)
  actionNames.Add(method.Name);
  }

  return actionNames.ToArray();
}

And then we can use it like this:

var controllerActions = GetActionNames(typeof(ClubsController), typeof(MembersController), typeof(ShopsController));
routes.MapRoute(string.Empty, "{controller}/{id}",
new { controller = "Home", action = "Index", id = UrlParameter.Optional },
new
{
 controller = "Clubs|Members|Shops",
 id = new ValuesConstraint(false, controllerActions)
});

Now our "{controller}/{id}" will only be matched by URLs where "{controller}" equals "Clubs", "Members", or "Shops" and "{id}" does not equal any action method name on any of these controllers. Any URL that does not match this route will then default to our, uhm, default route. Ta-dah!

Using DomainTime Instead of DateTime

2011-10-13T12:16:00.008+01:00

In a previous post about favouring DateTime.UtcNow over DateTime.Now I mentioned that I don't use the DateTime struct directly in code to obtain the current date or time. Instead I use what I call DomainTime, a wrapper around the DateTime struct. It looks like this:

   public static class DomainTime
   {
       internal static DateTime OverrideForTesting = DateTime.MinValue;

       public static DateTime UtcNow { get { return OverrideForTesting == DateTime.MinValue ? DateTime.UtcNow : OverrideForTesting.ToUniversalTime(); } }

       public static DateTime Now { get { return OverrideForTesting == DateTime.MinValue ? DateTime.Now : OverrideForTesting; } }

       public static DateTime Today { get { return OverrideForTesting == DateTime.MinValue ? DateTime.Today : OverrideForTesting.Date; } }

       public static DateTime MaxValue { get { return DateTime.MaxValue; } }

       public static DateTime MinValue { get { return DateTime.MinValue; } }

       internal static void Reset()
       {
           OverrideForTesting = DateTime.MinValue;
       }
   }

The whole point of using this class is that it makes it easy to test other classes that have some kind of time dependency. To use a contrived example, imagine that you've got a class which will only do its work if the time is between 1am and 2am. It makes the decision (should I work or should I not?) by checking DateTime.Now.

How do you test this? You _could_ run your tests just before 1am, between 1am and 2am, and then again after 2am - but that's just stupid. You should be able to run your tests anywhere, any time, and as many times as you want.

The solution, here, is to make the class depend on DomainTime.Now instead. By doing so, you can
override the current time during testing by setting it with the OverrideForTesting property.

Note that this property is an internal property. Expose it to your test assemblies by using the

[assembly: InternalsVisibleTo("Your.Test.Assembly")]

directive in the AssemblyInfo class in the assembly where DomainTime resides.

Now you can test to your heart's content. It's just a matter of setting the appropriate DateTime for each test.

One final note: The DomainTime.Reset() method is there for your SetUp() or TearDown() methods so that you can avoid having the DateTime set by one test bleed over into another test.

Binding Views to Navigation Elements

2011-10-13T10:08:00.007+01:00

Last night I did a bit of work on how I bind views to navigation items. I have tended to include information about 'active tabs' as part of the view model (which fits well with the idea of having one model per view) - but I didn't like the hierarchy of view models that emerged from it.

UPDATE: After a an anonymous comment on this post I have updated the implementation to use ViewData rather than TempData as the commenter rightly pointed out that, while the TempData implementation will work, TempData is for redirect.

What I ended up doing was sticking a piece of data in the ViewData dictionary and pulling it out in the view to determine which tab should be rendered as 'active'. I created some extension methods for ViewData to do this:

 
public static class ViewDataExtensions
{
 public static void SetNavigation(this ViewDataDictionary viewData, T navElement)
 {
  var key = GetNavKey(navElement);
  viewData.Add(key, navElement);
 }

public static T GetNavElement(this ViewDataDictionary viewData)
 {
  var key = GetNavKey(typeof(T));
  T t;
  try
  {
   t = (T)viewData[key];
  }
  catch
  {
   t = default(T);
  }

  return t;
 }

 private static string GetNavKey(T navElement)
 {
  return GetNavKey(navElement.GetType());
 }

 private static string GetNavKey(Type t)
 {
  return "sitenav:" + t.Name;
 }
}

Then I created an action filter which I can stick on a controller and/or an action. Notice the AttributeUsage which specifies the allowable targets and that the attribute can be applied more than once (this could be important if you've got more than one menu):


[AttributeUsage(AttributeTargets.Class|AttributeTargets.Method, AllowMultiple = true)]
public class BindNavigation : ActionFilterAttribute 
{
 private readonly object _navElement;

 public BindNavigation(object navElement)
 {
  _navElement = navElement;
 }

 public override void OnActionExecuting(ActionExecutingContext filterContext)
 {
  filterContext.Controller.ViewData.SetNavigation(_navElement);
  base.OnActionExecuting(filterContext);
 }
}

I apply this to a controller like this:

   
[BindNavigation(MainNavigation.Members)]
public class MembersController : FlyingFieldsBaseController
{
 ...
}

And an action like this:

 
[BindNavigation(ProfileNavigation.Wall)]
public ActionResult Index(string id)
{
 var model = _getMemberProfileViewQuery.Invoke(Guid.Parse(id));
 return View(model);
}

As you can tell I am using enumerations for my different "types" of navigation (main header nav, left
hand nav for profile pages, left hand nav for club management pages, etc). The thing is, though, you
can use anything you like - because TempData stores things as objects (you'll notice that my TempData extension methods use generics so you get type safety as well). You could, for example, store an object that holds the state for several layers of navigation if that's what you need.

In the views you just do this:

@{
var currentSection = ViewData.GetNavElement();
}

and use 'currentSection' however you please. I just use it to determine if I should set a CSS "selected" class on my navigation items.

Thoughts are welcome!

Working with dates

2011-10-05T12:49:00.005+01:00

Lately I've been doing a good amount of work on a website feature that requires the output of a relative date and time. For example, a entry written on a user's wall (the website has social aspects) may be annoted with "written by John Smith about two hours ago." It is a relatively straight forward task to accomplish this - but I thought I'd write a few words about some pitfalls you may come across.

Even if you have only every written the most trivial of applications you are likely to have used the DateTime structure in .NET (if you've written .NET apps, that is). And you're very likely to have used DateTime.Now; Let's take a closer look at the DateTime structure. According to Microsoft's documentation a DateTime "Represents an instant in time, typically expressed as a date and time of day." And, DateTime.Now "Gets a DateTime object that is set to the current date and time on this computer, expressed as the local time."

Cool. DateTime.Now is really handy for getting a handle on the current time, and we've all used it. But now I'm going to tell you that you shouldn't.

DateTime.Now returns a DateTime object that represents "the current date and time on this computer, expressed as the local time." As convenient as this may be, it's a potential source of trouble. "This computer" is the computer where the code executes. It could be your desktop machine, a development server, a production server, or a mobile device. The time on that machine depends on where the machine is located (which timezone it is in) and whether or not the machine is affected by daylight savings. So why is this a problem?

The problem is that if you cannot guarantee that all the machines in your infrastructure are all in the same timezone and are equally affected (or not affected) by daylight savings, using DateTime.Now in your code will potentially yield different timestamps on different machines even if the call to DateTime.Now was made at exactly the same time on the machines in question. 1pm in Oslo, Norway, on October 5th 2011 is not the same time as 1pm in London, UK, on the same date. "But that's just silly", I hear you say. "All our infrastructure is in the same data centre in one place." OK. Fine. That may very well be the case. But what about your users. Where are they? Are all of them in the same time zone as your servers? And is it likely that you'll never grow beyond having only local users and having only one data centre?

Even if your answer to the above questions is "we'll never scale beyond one data centre and all our users are in the same place and always will be" I think you should keep reading. It might just make your life a little simpler down the road. Just in case.

The problem with DateTime.Now is that it always represents the local time of the machine on which the code executes, and you don't really want to worry about where that machine is, because doing so makes life as a developer painful. What you want to do instead is use DateTime.UtcNow which returns an instance of DateTime representing the Coordinated Universal Time (UTC) of now. UTC is the local time of the server less any timezone differences and less any daylight savings difference. If you only ever store and use UTC DateTimes then none of your DateTime comparisons will ever have to take into consideration any time differences caused by time zones or daylight savings.

The only thing you now have to worry about is the thing you should worry about, which is displaying the correct date to your end users. You'll have to adjust for the timezone they're in because a date for an event at 12pm in London should be rendered as 1pm for a user in Oslo (they're always an hour ahead of London time).

Regardless of whether you use UTC or not, you'll always have to consider time zones and daylight savings when rendering dates for a user. Using UTC, that's all you'll have to worry about. If you use DateTime.Now, however, you'll also have to ensure that you know what the time offset of that DateTime instance is if you're going to compare it to another date, or if you're going to render it to a user. Pain in the arse (PITA).

I reckon that you should always use UTC times in your applications regardless of what your user base might look like. It makes life simpler from the start, and if you ever need to support users across different timezones you'll be a step ahead.

So, as a rule, this is what I do:

Always call DateTime.UtcNow and never DateTime.Now. (In fact, I don't use DateTime... I use DomainTime which is a wrapper I've created around DateTime. I'll write more about that in a later post).
Always treat DateTime stored in a database as UTC. This means that when I read that DateTime out of the database I specify that it is a UTC DateTime using the DateTime.SpecifyKind() method. This is very important, because the machine will by default treat any DateTime as local time.

Note that if you're using an ORM such as NHibernate you need to tell the ORM that the date should be treated as UTC. With FluentNHibernate this is really simple:

Map(x => x.DateCreated).CustomType().Not.Nullable();
Lastly, before displaying the date to the user, I apply the time difference between UTC and the user's location. There are several ways of doing this. For example you can have your users tell you which time zone they're in and you can apply the offset. Or, if your users are web users you can use Javascript's Date.getTimezoneOffset() method and apply the difference (in minutes) to your UTC date. Check out this StackOverflow question for some specific pitfalls of that particular method.

I'll follow up on this post with another post or two about displaying relative times and how to use a DomainTime wrapper around your dates.

NHibernate session management and MVC

2011-09-20T00:20:00.008+01:00

NHibernate session management is one of these things that occasionally catches me out. Usually once it's set up on a project I forget about it because it just works, but recently I came across a problem on a project which prompted me to write this post. There's a lot to say about NHibernate session management and this post is just a small contribution to the plethora of articles on the subject.

What follows here is my implementation of session management in an MVC web application (it shouldn't matter what version of MVC you're on). What I've set out to accomplish is this:

Define a unit of work by using NHibernate's ICurrentSessionContext
Enforce the unit of work by applying transaction management across controller calls.
Ensure that a session and transaction is available across multiple calls to child actions.
Make the session available for injection via my container of choice, Windsor.

In order to make any of this happen my application needs a session factory. I'm not going to go into the details of how I construct my session factory as it isn't really relevant to this post - but suffice to say that the creation of the session factory is triggered by the Application_Start() method in Global.asax - and that I store the session factory as a static property on the HttpApplication. Actually, there is one aspect of the session factory which is relevant to this post - but I'll come back to that a little later.

The Unit of Work

In web applications the obvious scope for a unit of work is a web request. Everything that happens, persistence-wise, between when a new request arrives and when the same request completes, can be treated as a unit of work. In other words, the changes to state in your application that takes place within a single web request should be atomic; the should either be persisted or rolled back at the end of the web request.

With this in mind I've set up the following methods on Global.asax:

private void OnBeginRequest(object sender, EventArgs args)
{
  if(RequestMayRequirePersistence(sender as HttpApplication) && Factory != null)
  {
      var session = Factory.OpenSession();
      session.FlushMode = FlushMode.Auto;
      ManagedWebSessionContext.Bind(HttpContext.Current, session);
  }
}

private void OnEndRequest(object sender, EventArgs args)
{
  if (RequestMayRequirePersistence(sender as HttpApplication) && Factory != null)
  {
      ManagedWebSessionContext.Unbind(HttpContext.Current, Factory);
  }
}

Ignore the call to RequestMayRequirePersistence - this is just a helper method to check whether the request is for a resource that may require an NHibernate session, such as a controller.

When a request arrives, I call OpenSession() on the session factory to obtain a new session. Then I bind this session to the current HttpContext by calling the Bind method on NHibernate's ManagedWebSessionContext.

Let's take a step back. Remember that I said that there's one aspect of the session factory set-up that's relevant? Well, we've already come to it. In order for this solution to work we need to tell the session factory which type of session context to use. A session context defines the scope of given session instance. In other words, if a session instance belongs to a context then the NHibernate session factory will keep serving up that same instance whenever a call is made to OpenSession() within that context. We can tell NHibernate which session context to use when setting up the session factory. Using FluentNHibernate syntax you can set up NHibernate to use the ManagedWebSessionContext by adding this to your session factory fluent config:

   .ExposeConfiguration(config =>
    config.SetProperty(Environment.CurrentSessionContextClass,
    typeof(ManagedWebSessionContext).AssemblyQualifiedName))

Now let's go back to handlers for BeginRequest and EndRequest. In addition to telling NHibernate which session context we want to use, we have to define when to bind and unbind the current session from that context. That's what the OnBeginRequest and OnEndRequest methods do; they define the actual scope of our NHibernate session, our unit of work.

You can read more about NHibernate session context here.

Enforcing our Unit of Work

Now we've defined a unit of work for our application. However, this unit of work is no good to us yet because we still need to set up some controls around when transactions are created, committed, and rolled back. For my application I think the following rules make sense:

Begin a transaction when an action method starts executing
If an exception occurs during the execution of an action, roll back the transaction.
If an exception occurs during the rendering of a view, roll back the transaction
If the execution of a controller and rendering of a view complete successfully, commit the transaction
Any calls to child actions should 'enlist' in the current transaction, and a child action should never roll back or commit a transaction.

I have implemented these rules through an ActionFilterAttribute which I've called, uhm, TransactionAttribute. It looks like this:

public class TransactionAttribute : ActionFilterAttribute
    {
     //Create transaction
     public override void OnActionExecuting(ActionExecutingContext filterContext)
     {
         var controller = filterContext.Controller as IPersistenceController;

         if (controller != null && !filterContext.IsChildAction)
         {
             controller.CurrentSession.BeginTransaction();
         }
     }

     //rollback on exception
     public override void OnActionExecuted(ActionExecutedContext filterContext)
     {
         var controller = filterContext.Controller as IPersistenceController;

         if (controller != null && !filterContext.IsChildAction)
         {
             ITransaction transaction = controller.CurrentSession.Transaction;
             if (transaction.IsActive)
             {
                 if (filterContext.Exception != null)
                 {
                     transaction.Rollback();
                 }
             }
         }
     }

     //commit transaction, or rollback on exception
     public override void OnResultExecuted(ResultExecutedContext filterContext)
     {
         var controller = filterContext.Controller as IPersistenceController;
         if (controller != null && !filterContext.IsChildAction)
         {
             ITransaction transaction = controller.CurrentSession.Transaction;
             base.OnResultExecuted(filterContext);
             try
             {
                 if (transaction.IsActive)
                 {
                     if (filterContext.Exception != null)
                         transaction.Rollback();
                     else
                         transaction.Commit();
                 }
             }
             finally
             {
                 transaction.Dispose();
             }
         }
         base.OnResultExecuted(filterContext);
     }
 }

There are really only two things worth noting here:

Controllers are cast to IPersistenceController. IPersistenceController defines a single property ISession CurrentSession {get;set;} which is used to obtain the current session.
I check the IsChildAction property of the ActionExecutingContext to make sure that child actions don't mess with the current transaction.

You could argue that having every controller implement IPersistenceController is a bad thing and that letting the controllers know about ISession is even worse - and I'd probably tend to agree with you. If you don't like this approach you can of course abstract the access to the current session away from the controller. I've opted for this approach because of ease of implementation; Windsor - which I'll talk about in a minute - resolves all controllers for me, and therefore sets the ISession on the IPersistenceController.CurrentSession property automatically.

Making the Session Available to Windsor

The last piece of the puzzle is to make ISession available to Windsor so that it can be injected:

   container.Register(Component.For()
              .UsingFactoryMethod(() => MvcApplication.Factory.GetCurrentSession())
              .LifeStyle.PerWebRequest);

Note the use of a factory method, and the call to MvcApplication.Factory.GetCurrentSession(). When Windsor needs to resolve an instance of ISession it will call GetCurrentSession() on the application's session factory. The current session is governed by the session context which we set up earlier. See? So Windsor will be handed the same instance of ISession every time it asks the factory for it during the course of a single web request.

The last thing to notice is the lifestyle that's chosen for the ISession instance: PerWebRequest. If you choose anything other than this lifestyle you'll run into trouble:

If you set the lifestyle to Transient then Windsor will dispose of ISession if it disposes of any objects that have been injected with ISession
If you set the lifestyle to Singleton then Windsor will break the scope of the Unit of Work we've so carefully set up and you'll end up with a single session for the lifetime of the application.

Summary

In this post I've shown one way of managing NHibernate sessions in the context of an ASP.NET MVC application. There are many ways of doing this, but this way seems to work well for me. Comments are welcome!

Reflector is becoming a paid-for tool

2011-02-14T09:25:00.001+00:00

Sadly, RedGate is breaking their promise (or, as they call it, 'intention') of keeping Reflector free of charge. So hurry, get your copy of Reflector now, before you have to pay for it.

Hadlow: IDependencyResolver Is Broken

2011-02-07T09:41:00.003+00:00

In my haste and determination to use MVC 3.0's dependency resolver in order to enable injection on attributes I took some suggestions from Christian Prieto's blog post and implemented a Windsor-backed IDependencyResolver. It worked well and, despite the fact that I was effectively embracing an anti-pattern and using a new global variable, I was pretty happy with the solution.

I'd overlooked something really fundamental, however. Mike Hadlow points this out in his recent post on Code Rant. The issue is simply this: IDependencyResolver doesn't support a mechanism for releasing components, and this poses a problem when using a container such as Windsor as backing for the resolver. If you can't release components you'll eventually end up leaking memory.

In hindsight I should have stopped and listened more carefully to that gut feeling that told me I was doing something dirty when I embraced the service locator.

And for the first time I feel a bit let down by the MVC team; why did they ignore this (see the comments trail)? I have to agree with Hadlow on this: They shouldn't shout about the IDependencyResolver being container-agnostic when it blatantly isn't.

So this afternoon I'll be rolling my good old WindsorControllerFactory back into the solution.

Annoying issue with the ASP.NET membership databases

2011-01-18T10:06:00.002+00:00

In order to speed up making changes to my databases during development I've set up a .cmd script that drops and recreates my project databases, and fills them with some seed data. This is pretty expedient, though in hindsight I think a solution using something like Visual Studio's database projects might be better. At any rate, I digress...

Yesterday I ran into a problem with the ASP.NET membership database tables. I kept getting this error:

The 'System.Web.Security.SqlMembershipProvider' requires a database schema compatible with schema version '1'. However, the current database schema is not compatible with this version. You may need to either install a compatible schema with aspnet_regsql.exe (available in the framework installation directory), or upgrade the provider to a newer version.

My script uses the aspnet_regsql.exe tool to install the membership database - so this was very strange. The actual error stems from data missing in the aspnet_SchemaVersions table. Depending on what membership features you have installed you will have some of the following rows in this table:

common 1 1
health monitoring 1 1
membership 1 1
personalization 1 1
profile 1 1
role manager 1 1

The weird thing for me, though, was that this data was present! So, what was going on?

The error was only thrown by IIS, but not by the development web server in VS. Discovering this prompted me to restart IIS... and the problem went away.

In my case I figured out that the problem was that my database script had deleted all the rows in the aspnet_SchemaVersions after the database had been created. This caused the error in the first place. When I updated the script, however, the error didn't go away (in IIS) and I can only guess that this must be because this data had been cached in the IIS worker process.

Verifying that Windsor is configured correctly

2010-12-02T13:42:00.010+00:00

Yesterday I experienced some very weird behaviour in an MVC app I am building - and it all came down to me being sloppy when configuring Windsor to resolve instances of HttpContextBase. In my haste I'd left the lifestyle configuration as default, rendering the resolved HttpContextWrapper as a singleton. That's not particularly useful.

When this happened it occurred to me that it would be nice to be able to verify that you've configured Windsor in the correct way and that you haven't inadvertently changed that configuration during development. So I knocked up a couple of extension methods on IWindsorContainer that can help. With these you can run tests such as:


_container.ShouldMap<IDisposable>().To<MyClass>();
_container.ShouldMap<IDisposable>().To<MyClass>().WithLifeStyle(LifestyleType.PerWebRequest);
_container.ShouldMap<HttpContextBase>().WithLifeStyle(LifestyleType.Singleton);

All you need is an instance of IWindsorContainer and the extension methods below. Note, that if you're testing stuff that's environment dependent (i.e. resolving HttpContext which is dependent on the ASP.NET runtime) you'll have to set that up separately. Lastly, I've built this against NUnit - but refactoring to other frameworks should be easy.


    public static class ContainerExtensions
    {
        public class ComponentWrapper
        {
            public IWindsorContainer Container { get; set; }
            public ComponentModel Component { get; set; }
        }

        public static ComponentWrapper ShouldMap<T>(this IWindsorContainer container) where T : class
        {
            List<GraphNode> graphNodes = new List<GraphNode>(container.Kernel.GraphNodes);
            List<ComponentModel> componentModels = new List<ComponentModel>(Convert(graphNodes));

            ComponentModel componentModel = componentModels.Find(x => x.Service == typeof(T));
            if (componentModel == null)
                throw new AssertionException(string.Format("Service {0} has not been registered in the container",
                                                           typeof (T).FullName));

            return new ComponentWrapper {Container = container, Component = componentModel};
        }

        public static ComponentWrapper To<T>(this ComponentWrapper wrapper) where T : class
        {
            Type serviceType = wrapper.Component.Service;
            try
            {
                var instance = wrapper.Container.Resolve(serviceType);

                if (instance.GetType() != typeof(T))
                    throw new AssertionException(string.Format("Expected implementation of {0} to be {1}, but was {2}",
                                                               serviceType,
                                                               typeof(T).FullName, instance.GetType()));
            }
            catch(Exception exception)
            {
                throw new AssertionException(string.Format("An exception was thrown when resolving {0}. The exception message is: {1}",
                                                               serviceType, exception.Message), exception);
            }

            return wrapper;
        }

        public static ComponentWrapper WithLifeStyle(this ComponentWrapper wrapper, LifestyleType expectedExpectedLifestyle)
        {
            VerifyLifestyle(wrapper.Component.LifestyleType, expectedExpectedLifestyle);
            return wrapper;
        }

        private static void VerifyLifestyle(LifestyleType actualLifestyle, LifestyleType expectedLifestyle)
        {
            if (actualLifestyle == LifestyleType.Undefined && expectedLifestyle == LifestyleType.Singleton)
                return;

            if(expectedLifestyle != actualLifestyle)
                throw new AssertionException(string.Format("Expected lifestyle {0} but was {1}",
                                                           expectedLifestyle, actualLifestyle));
        }

        private static IEnumerable<ComponentModel> Convert(List<GraphNode> graphnodes)
        {
            foreach(GraphNode node in graphnodes)
                yield return node as ComponentModel;
        }
    }

Encapsulating boolean return types.

2010-11-30T08:47:00.004+00:00

.Net 4 introduced some changes to the way DataAnnotations ValidationAttributes work. Pre .NET 4 you would check the validity of a property on a class by attributing it with a ValidationAttribute (custom or otherwise) and then calling the IsValid():bool method. This is straight forward and logical. However; this approach leaves a bit to be desired. If IsValid() returns false, what exactly is it that invalidates my property? It would be better if validation was approached differently, and this is what DataAnnotations in .NET 4 does.

In .NET 4 the use of IsValid():bool is discouraged. In fact, if you create a new custom validation attribute (extending ValidationAttribute) and do not override IsValid() before you call it, it will throw a NotImplementedException with the message "IsValid(object value) has not been implemented by this class. The preferred entry point is GetValidationResult() and classes should override IsValid(object value, ValidationContext context)."

As you can see, you're encouraged to override an overload of IsValid(). If you look closer you'll see that the overload does not return true/false, but instead returns a ValidationResult which is a wee bit more informative. Also, the overload is protected - so you can't call it externally. Instead you call the GetValidationResult() method to see what the result of validation is.

Why is this better than just returning true or false? It's because a ValidationResult carries information about why validation failed.

You might now think that this is a bit overkill for scenarios in which validation is successful. In this case, more often than not, all you care about is knowing that validation has passed and that you can carry on. The ValidationResult class facilitates this by applying the Null Object Pattern and encapsulating a static property called ValidationResult.Success against which you can compare the ValidationResult instance returned to you by GetValidationResult() (ValidationResult.Success always returns null, because a null validation result signifies successful validation).

This approach doesn't just apply to validation scenarios. Ayende Rahien talks about why and how he uses this approach here. If you have a method that returns true/false and there is no more relevant information available, fine. However, if the true/false answer masks other information then the approach of encapsulating the answer in a class is better.

Go on. Get NuGet.

2010-11-29T09:50:00.002+00:00

I spent most of yesterday afternoon (Sunday!) messing about with FluentNHibernate, trying to compile the source to .NET4, NHibernate 3 Beta, and Castle Windsor 2.5.

What. A. Waste. Of. Time.

Sometimes I just don't think. Somebody out there would probably have done this already, right? The answer to that question is yes. But it wasn't until I happened upon the hornget project that bells started ringing: "Hmmmm.... that's awfully similar to NuGet, isn't it?" Yes, it is.

Suffice to say that 10 minutes after this realisation I had FluentNHibernate running in my solution, with NHibernate 3 Beta and Castle Windsor 2.5.

So if you haven't already, go on and get NuGet.

Testing routes with MVC3 RC1 and .NET 4

2010-11-25T09:01:00.009+00:00

Yesterday I found myself needing to test some MVC routes. I wanted to avoid setting up all the mocking infrastructure needed to do so, and decided to use the MVCContrib project to ease the work. However, I am building an MVC 3 RC1 app on .NET 4 - and MVCContrib targets .NET 3.5 and MVC 2, so I quickly ran into trouble.

I tried converting the solution to .NET 4.0 - but it was too time consuming to do so. Instead I ripped out the pieces I needed, i.e. the route testing extension methods, and built a new assembly targeting the right versions of the framework. And I replaced RhinoMocks with Moq.

Using the Mvc.TestHelper assembly you can easily test routes with syntax like this:

"~/".ShouldMapTo<HomeController>(x => x.Index());
"~/Account/".ShouldMapTo<AccountController>(x => x.Register(null));

Note: I take zero credit for this work. All the source code is taken directly from the MVCContrib project.

I have made the source available on BitBucket so that you can test your MVC 3 routes. The project uses NUnit and Moq for testing.

The LIBUSWKAIQ anti-pattern

2010-01-21T13:57:00.002+00:00

Design patterns have been all the rage for quite some time now, and with them have come an increased awareness of patterns that pretend to be design patterns but really are anti-patterns; a pattern that appears obvious but really is far from optimal in practice (read: stupid).

A relatively recent (and greenfield) implementation where I work is built around such an anti-pattern. We've named this lovely piece of instant legacy the LIBUSWKAIQ anti-pattern. It's pronounced "Libbus-wah-cake" and stands for "Let It Blow Up So We Know About It Quickly."

This pattern gives you free license to forget about exception handling and encourages applications to fall over and die if any exceptional circumstances arise.
This pattern encourages you to throw exceptions with the explicit purpose of killing your app.
This pattern hates error handling.
This pattern creates needy applications that require immediate attention.
This pattern encourages 3am support calls. This pattern wants your support developers to always be deprived of sleep. This patterns wants you to spend your ENTIRE support budget.
This pattern appeals to lazy people.

Don't do this! Handle your errors. Keep your apps running. Put errors to the side and let humans deal with it as soon as it is conveniently possible. Don't stop your entire business process running just because it experienced a minor 'blip.'

You're smarter than this. Don't get sucked into becoming a Libbus-wah-caker.

Literate Programming

2009-09-28T18:26:00.002+01:00

A while back I wrote a rather lengthy entry about the significance of strong and clear naming conventions, and I spent some time explaining how well-defined, unambiguously named methods with to-the-point parameter names end up reading like sentences out of a book.

Today a friend pointed me to the Literate Programming website, where the following snippet can be found:

"I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: 'Literate Programming.'

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other."

When I read this I immediately thought: YES! This is exactly what I've been trying to say. Code should not be a language for a select 'elite' that prides itself on obscurity. It should be something that can be read with ease and even by someone with very little technical understanding. I dare say that if you achieve that, you've achieved maintainable code.

Boolean Polymorphism

2009-09-23T12:29:00.001+01:00

I think this is a rather good article about the pitfalls of large parameter lists and code maintainability.

Factory Assembly Lines, Red Cars, and TDD

2009-07-22T08:39:00.001+01:00

For the last five weeks I have been supporting developers on a project that makes full use of automated unit and integration tests, including the use of a mocking framework. The frameworks of choice are NUnit and Moq, which is fairly standard stuff. What makes our little project special, though, is that the developers were all (bar one) completely new to the concepts of unit testing and mocking! This has made for some interesting challenges. All the developers are highly capable and intelligent people, so they've adopted the new principles with amazing speed. But as anyone who's transitioned to TDD will know, the mindset required is very different from that of 'traditional' development. As such, I've had to do a lot of mentoring during the last month or so.

There's nothing quite like having a good example to go by when you're trying to learn something new. That's the case with TDD as well. I also think that in order to learn TDD and the test-first discipline you need something more. What's needed is a school of thought. Perhaps even a dogma. I think that this is far more important than specific examples of how to do specific things, because with the correct line of thinking you'll arrive at good solutions to any of your testing problems. It was with this in mind that I wrote what follows; a rather absurd testing scenario involving a factory assembly line and lots of red cars.

What I want to address now is the creation of tests, and the scope of this discussion includes what a test should test (the scope of the test, if you like), where boundaries should be drawn, and how such decisions should influence your design while you’re coding. For now, imagine that you are responsible for the production line of cars, and that you want to be able to test that a car is painted in the colour that you have specified.

How would you go about testing such a thing? The first thing that springs to mind is perhaps to instruct your assembly line (people and machines) to build you a red car, and then go have a look at the car when it’s built to see if it is, in fact, red. Such an approach would certainly work, but it would be a hell of an expensive test! What if the car came out the wrong colour? Or a different shade of red than you expected? You’d have to keep cranking out cars while making adjustments until you get the colour right, and that’s just not a sensible approach.

Of course, this example is absurd because you would never do that if you owned a car factory – but I’ve chosen this example exactly for that reason; you’re clearly doing too much work just to check that the car turns out with the right colour. Too much work. That’s a key thing to remember.

How could you improve on the process? Well, you might start by skipping the entire “build-me-a-car” bit and focus on the paint job itself. A car is painted by a big robot with lots of paint guns, and this whole mess takes place at the end when the car has been assembled and all non-metallic surfaces have been carefully masked etc. Since this is where paint is applied we can narrow our testing to this machine. We can put a piece of paper in front of the paint gun and ask it to colour the paper red. If things turn out unexpectedly, we can easily repeat the test. Paper is cheap, and even paint is much cheaper than a car. Not only that, but repeating the test is much faster also. This test is therefore infinitely better than the first test. We’re doing much less work, it’s costing less, and we’ve focused right down on the thing that makes a car red (or any other colour). Focus. That’s another key thing to remember.

Let’s stop and think about focus for a moment. In the first test, if a car turned out burgundy rather than the sports-car red you’d imagined, where would you make your adjustments before testing again? Sure, you may know that it’s the big ol’ paint robot at the end of the line that does the work, but how do you get your instructions to it? Is there a human involved? At what stage of the car assembly do you have to ‘input’ the colour? Right at the start? Does anything happen to your colour instruction while the car is being built? Does one human tell another, or is it written down on paper and later typed into a computer? It should be fairly easy to see that a test with such wide focus (or no focus at all) is prone to all kinds of environmental noise that can affect the output and thus make accurate testing difficult. So focus is important.

Now, we’ve narrowed our focus to the robot that paints the car, and we’ve devised a test that involves the robot spraying paint onto a sheet of paper. This is, in the scheme of things, probably a decent test. But we can do better. Does the paint gun produce the colour? No it doesn’t. The purpose of the paint gun is to deliver paint at the correct pressure and velocity, and to ensure that the nozzle produces a mist of paint with exactly the right droplet size etc. We can certainly use the paint gun to test colour, but since it’s got nothing to do with producing the colour of paint, we should see if we can create a better test. We should narrow our focus again.

If you keep repeating the process of narrowing your focus you’ll eventually end up at the part of the machine that mixes paint to create specific colours. Now the focus seems to be about right (you can probably narrow things down even further, though). The part of the machine that mixes the paint is what’s responsible for the colour that eventually ends up on the car. Arguably, you can take the whole paint element out of it because your paint is likely to be generic and colourless – so you can just focus on the mixing of pigments. But I don’t want to be too pedantic, either.

Now that we’ve got the focus right, we’ve got to get our test right. We’re trying to verify that when we ask for red, red is what we get. But if you think about it, red isn’t very specific either. Is it blood red? Burgundy? Maroon? A bit more on the pink side of the spectrum? To try and test for red isn’t specific enough. And here’s another thing to be mindful of. Be specific. Don’t test for red, but instead test for a specific shade of red. And so your test will start to change shape as well. Rather than testing for a colour you’ll find that you’ll be testing that the paint mixer dispenses the correct amounts of red, green, and blue (the basic components of the RGB colour system) in order to produce a specific shade of a specific colour. Now you’ve got a good test. A valuable test. A test you can write home about.

Such a test can be carried out without much work, it’s focused (it involves only part of a sub-system), and it’s very specific (it tests conditions for very specific input). All these things are good. In the context of the car factory you’ve now got a fast, cheap, repeatable, and accurate test that’ll verify that your factory is capable of cranking out cars in every colour of the spectrum.

Well, that’s actually a half truth. Or less than a half truth. You’ve only created a test for mixing pigments. You’ve not tested that the right amount of mixed pigment is added to the correct volume of paint. Nor have you tested that the paint gun actually works like it should and that the paint-robot moves like it should. And there isn’t a single test, yet, for any other aspect of the car assembly line. All this is beyond the scope of this discussion, but suffice to say that if you are a car producer hell-bent on making big bucks you’d apply the same principles as above to creating tests for every single aspect of your production line.

Now let’s try and relate this example back to software. The car assembly line would likely be implemented as a number of applications and/or services that each carry out specific tasks (basic assembly, welding, engine installation etc). The paint-robot might be one such application. The robot’s paint gun would be represented by a class, as would the pigment mixer. And the actual mixing of pigments would probably be represented as a single method on the pigment mixer class. That’s the unit you’d be testing. You wouldn’t write a test that invokes all those applications because it would require too much work and be too difficult, and it would result in an inherently inaccurate test.

So, when you’re writing tests and designing your code you should always make sure that what you’re working on lends itself to testing (it doesn’t require a lot of work), it is focused, and very specific. If what you are testing is part of something much, much larger then ensure that your unit is isolated. You do this by using mock objects for its dependencies. If you can’t use mock objects for whatever reason you should stop and think about why that is and see if you can change your design. Maybe you don’t have to. Maybe you can run your test in a slightly wider context without doing too much work or becoming too unfocused or non-specific. If you can, fine. If you can’t – change your design.

Careful thinking about how you’d test the code you are going to write will help you write better systems. As with anything, it requires practice and experience (and you’ll never stop learning) and it’s possible to go terribly wrong – but if every decision you make is the result of careful, informed consideration the likelihood of failure is minimal. Good tests are tests that are focused on one system, and specifically a single function of that one system – and that do very little work in order to test that function. Make the creation of such tests your goal, and you’ll quickly learn how to write clean, robust, and testable code.

PartCover - an alternative to NCover?

2009-06-22T11:25:00.002+01:00

I've been looking for a cheap or free tool for measuring NUnit test coverage and just stumbled upon PartCover. I've installed it and fiddled with it and it seems to be an OK tool. It's Open Source, too - which I think is great.

I have to say, though, that the documentation is poor and the application itself is buggy (I experienced a critical exception when trying to save a coverage report to file). Despite this, I'll take a buggy PartCover over NCover which would set me back $650 for a license!

Might write more about this later. Check it out!

Names and the Importance of Semantics

2009-03-13T11:12:00.002+00:00

I've taken the below 'post' from some documentation I've recently written for the developers where I'm currently working. It appears to me that, in general, developers (and, indeed, architects) spend far too little time thinking about names and naming conventions. Personally I spend hours thinking about names. Good names are an incredibly important aspect of good software design. Anyway - if you care to read on, this is what I've said on the subject so far:

Aside from writing code that is correct, efficient, and actually works, the most important aspect of software development is, arguably, naming. Choosing good names for namespaces, classes, methods, and properties (even member variables, local variables and parameters) is incrediby important (and therefore also difficult) because the semantics they convey. A name must be unambiguous and clearly convey the purpose and function of the named component when viewed in isolation, as well as when it is viewed in the context of its root namespace, immediate namespace, class, and so on.

Good type and namespace names leave little room for misunderstandings and mistakes because of ambiguity. Namespaces and types defined in the .NET Framework are very clearly named throughout and the semantics of each name are typically very clear. A good example of this is the System.IO namespace.

The System.IO namespace name is unambiguous because it is short, because the relationship between the components of the namespace ("System" and "IO") is clear, and because each component of the namespace is named well semantically:

"System" implies a logical grouping of functionality that is 'close to the machine' or 'close to the framework'. The "System" namespace, by virtue of its name, is very clearly not a task or application specific namespace.

While it may be argued that the word "System" is ambigous because it can encapsulate so much functionality (and varied functionality at that), when seen in its context (it is the main root namespace of the entire framework) the name is still very clear.

"IO" is a very old and commonly used abbreviation ("InputOutput") in computer science and is always associated with data transfer between devices (both internal and peripheral). The immediate association of "IO" is that of file read/write operations, and this is exactly the kind of functionality that the classes in this namespace provides.

System.IO is therefore a really good namespace because the semantics of the first component's name lends meaning to the other. "System" tells the developer that we're dealing with general, non application-specific functionality, and "IO" implies that the functionality is file-operation specific.

The File class within the System.IO namespace is another good example of good naming. Its fully qualified name, System.IO.File, makes it absolutely clear what the class is and what it does - it's very clearly a representation of a file on a file system and provides file operations to the caller.

The methods on the File class are also very well named. A couple of examples illustrate how clear, short names can convey a lot of information when viewed in their proper context:

public static System.IO.FileStream Open(string path, System.IO.FileMode mode)

The method name File.Open is in itself very clear; it is obvious that the Open() method will open a file on a disk. There is sometimes a tendency to be too specific when naming methods - the above method might for example be called OpenFile(). Viewed entirely in isolation, the second method name, OpenFile(), is clearer than Open() - but when viewed in the context of its class, OpenFile() is obviously a poorer name than Open() because the context (the File class) already makes it obvious that we are in fact dealing with files!

public static bool Exists(string path)

This method name is clear because it can be phrased as a question with a simple yes/no (or true/false) answer: "Does this file exist?"

public static void Move(string sourceFileName, string destFileName)

This method name is unambiguous (clearly File.Move() is a method that moves a file on a file system), but pay particular attention to the parameter names; sourceFileName and destFileName leave no doubt about what you are dealing with. If this method's signature is paraphrased into a sentence it would read something like "move this source file to this destination."

The above examples above illustrate the importance of context when constructing names in software. A named element must make sense in isolation, but it is also very important that it makes sense contextually. Methods must be named so that the name itself carries the correct semantics, but the method's parameters (and return type) should be named in a manner so as to add further semantic value to the method's signature.

Orange Mocha Frappucino

2009-03-10T22:23:00.003+00:00

This is just a quick note to those of you that I know read this blog - because I know you know Steve. He's started blogging over on Orange Mocha Frappucino. First post is about handling web.config in unit tests. Good one, Steve!

James Joyce .NET

2009-02-24T12:44:00.002+00:00

Last week, after doing a code review, I coined the term "James Joyce .NET". Though the James Joyce factor isn't particularly .NET specific (I'm sure there are Ruby, C++, Java, and most certainly C developers out there who do things in similarly cryptic manners), I think the term has a nice ring to it. And in fairness to Joyce, I think the code I reviewed was far less readable than Ulysses.

Aside from software that works and "does its thing" in a reliable manner, clients care a lot about code that's maintainable. The client may not know that they care about this, at least not at first - but once you tell them that a change is going to take three weeks to complete "because of this, that, and the other" (because the code you've written isn't maintainable) you bet your sweet ass they start caring. They care not because of the state of your code; they care because of the cost. And rightly so.

There are many key things to consider when writing maintainable code but the subject of my current rant will be readability. Does your code read like a book? Probably not (hey, it's not fiction) - and that's OK. But do your method names and signatures read like sentences? Could you translate the body of your methods into short little textual paragraphs that clearly illustrate what they do? If you answered "no" to both of these questions it's probably time to stop and think a little.

Disclaimer: I'm renowned for harping on about ideals and I've been caught out many a time falling short of my own mark. That said, I stick to my ideals because without them we've got nowhere to go.

To start with, code must be legible. That means you have to choose names (for your classes, methods, parameters, variables) that clearly indicate purpose. Favour readability over brevity when creating names. Second, your names must make semantic sense. A class-method name combination should be completely unambiguous, easy to read, and clearly convey "what you get". Classes and methods should do what it says on the tin. Don't be obscure, don't be ambiguous.

Third: Use the appropriate constructs for the job. Don't embed an algorithm in a property. Don't use private properties. Properties are there to expose aspects of a class, so if you're not going to expose it, use a private member variable instead. Don't use indexers for anything but accessing collection data. Don't use generics unless you need generic code, and then only if generics give you something that a typed parameter list doesn't (using interface/abstract classes instead of concrete types).

Seriously, think long and hard about any code you write. Just because something works doesn't make it good. And give some thought to those people that come after you. Will they be able to understand what you've done? You might very well be a genius and the best thing since sliced bread but really, what good is that if nobody understands what you've done? Don't obfuscate your code by being lazy, too clever, or by using constructs in a way that they were not intended.

</ rant>

What not to do 5 minutes before a meeting...

2009-02-18T13:28:00.000+00:00

I typically don't read the Metro magazine on my way to work, but today I did. And there was a little snippet in there about a YouTube video that was supposed to be very funny. This tickled my curiousity, so when I found myself with a couple of minutes to spare before a meeting this morning, I went to YouTube to watch the clip about David After Dentist.

Bad decision. It took me a good 10 minutes to stop grinning and get my sudden bursts of laughter under control. Not good when someone's called a meeting with you to give you an update on serious matters.

Funny as hell though :-)

Brittleware

2008-11-13T21:32:00.004+00:00

This is really just an observation, and a highly subjective one at that. To any die-hard ASP.NET traditionalist out there: This isn't meant as an attack, so don't take it as one.

I've been working on the ASP.NET MVC framework together with my buddy Steve for a while now and we've been trying out a lot of different things while getting to grips with this new (and much better) way of doing things. We've been trying to establish our own patterns for developing MVC applications, and while doing so we have experimented and written a lot of code, and very few tests.

During this phase of experimentation I truly came to love the MVC framework for its flexibility and elegance, but for some reason I had this nagging feeling that all was not well. It was a familiar feeling, too, and one that I associate specifically with web development. But I couldn't put my finger on it.

Then just a couple of days ago I realised what it was. We'd decided to start building in earnest, and using the MVC framework in anger. Nothing would be written unless it was tested. And after a couple of hours of intense controller-testing I suddenly realised that the uneasy feeling was gone, and in its place was a feeling of security and contentment.

What I'd felt before was the same feeling I always had when writing ASP.NET applications. Things just felt brittle and ready to break. I could go to any length in order to ensure that the application did what it should, worked like intended, and would fail gracefully - but somehow that feeling of brittleness never went away completely. I didn't have any tests, no way of verifying that I was still on the right path, the straight and narrow. And writing MVC applications without tests gave me that same feeling because really, I was no better off.

With the introduction of tests that feeling of brittleness disappeared and instead the application felt robust. Solid. Stable. Reliable. Add any number of synonyms. If you believe in TDD you know what I'm talking about.

I don't know if there's a moral to this story, but the realisation I had has confirmed to me yet again how correct it is to develop everything with tests first. There simply isn't another way.