The StartableFacility will start each service eagerly by default, as soon as all of its dependencies have been registered in the container. But what if your services take a long time to start up, or you want more control over the time at which they start?

One option is to use the facility’s built-in Deferred Mode that waits until all components have been registered before starting any services.

If that is too early however, you can register all your IStartable components, but not drop the StartableFacility into the container until you want to start them. It will immediately start them all.

public void RegisterServices()
{
    // register startable services
    container.Register(Component.For...));
}

public void StartServices()
{
    // drop this in when you're ready to start them
    container.AddFacility<StartableFacility>();
}

If you need even more fine-grain control, don’t register the facility at all — just loop through all your IStartable components and call Start() on them manually.

Git, on the other hand, uses a 40-character SHA-1 string as a unique ID for commits. As you can see, this will not fit in a .NET assembly version:

Example git commit: c9d183c8570143142ca61c555360e7f0732efc09
Example git commit (short version): c9d183c857
Example .NET assembly version: 1.2.3.4

One place it will fit is the AssemblyInformationalVersion attribute, which accepts any string (thanks Joshka for the tip!). Here’s a quick MSBuild script to do it (using the AssemblyInfo task from MSBuild Community Tasks).

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <MSBuildCommunityTasksPath>packages\MSBuildTasks.1.3.0.528\lib\net20</MSBuildCommunityTasksPath>

    <!-- Use the short version of the git hash. -->
    <GitCommitShortHash>$(build_vcs_number.Substring(0, 7))</GitCommitShortHash>
  </PropertyGroup>

  <Import Project="$(MSBuildCommunityTasksPath)\MSBuild.Community.Tasks.Targets"/>

  <Target Name="GenerateAssemblyInfo">
    <AssemblyInfo CodeLanguage="CS"
      OutputFile="MyApp\Properties\AssemblyInfo.cs"
      AssemblyInformationalVersion="$(GitCommitShortHash)" />
  </Target>
</Project>

Then in C# you can use something like the following to display it on startup or your About page:

public void Main()
{
    var gitCommit = Assembly.GetExecutingAssembly()
        .GetCustomAttributes(inherit: false)
        .OfType<AssemblyInformationalVersionAttribute>()
        .Single().Configuration;

    Console.WriteLine("My App starting up (git commit {0})", gitCommit);

    ...
}

(Note Josh Flanagan has an alternative approach where he finds a way to convert the git commit into an int so you can use it in the AssemblyVersion).

I discovered this last week while porting all our tests to a different framework. Under QUnit, everything was green, but under Jasmine, most of the end-to-end tests (that exercise our whole app, simulating user actions via the DOM down to a live API and back) were failing with all sorts of weird errors.

The problem? Unlike our regular tests, the end-to-end tests run the whole application at once, using the entire DOM, plus a globally-scoped event aggregator.

In QUnit all the tests ran fine, because they were completely isolated from one another. But in Jasmine they were running concurrently, all racing to update the DOM at the same time, and publishing all sorts of events that were being picked up by other tests. We fixed the problem by switching to Mocha instead… but definitely something to watch out for!

If it were the other way around — database is case sensitive, app is not — simply discarding the case information by converting everything to a common lowercase representation (a lossy transformation) would do the trick.

Our situation is a bit harder, however. We somehow need to represent the key as a string including each letter and also store whether it was uppercase or not. You could write a custom converter for this (maybe using special escape characters to indicate uppercase letters)… but a much easier way would be simply to convert it to Base32.

Why Base32? Using Base64 would produce shorter strings (more efficient encoding), but but it encodes data using both upper and lower case characters, so you are still at risk of collisions. Base32 on the other hand only uses uppercase, so it is safe to use for a case-insensitive key-value store.

Hex would work too (only uppercase characters from A-F), but it would need even more space to do so.

Disclaimer: this is my first-ever book review on this blog! I’m not a javascript/HTML developer by trade so it’s not going to be a critical review or anything — just how I found reading it.

I’ve worked on a few web applications over the years, and I’m familiar with at least a couple of other MVC-style frameworks, but it’s all been .NET, and recently, all on the desktop. Only in the past few months have I attempted my first full-on browser-based javascript application, using the fantastic Backbone.js. The journey so far has been pretty bumpy, but I’m finally getting to the point where I’m comfortable enough with Backbone (and the javascript language itself) to really start being productive. But recently I’ve been starting to hit some complex situations that I’m not sure how to implement, and am struggling to find online. As well, I’m always on the look out for tips confirming the code I’ve already written is on the right track.

I stumbled across Recipes With Backbone book by chance from a blog post by one of the authors, where he was discussing how to implement default routes. I was a bit hesitant at first when I couldn’t find many reviews of it, but ‘advanced Backbone’ is a pretty new subject area (even to find on blogs) and it was cheap so I bought a copy. I am glad to say I was very satisfied with my purchase.

The book has 152 pages, and it took me a day to read on my Kindle. It covers:

1. Writing Client Side Apps (Without Backbone)
2. Writing Backbone Applications
3. Namespacing
4. Organizing with Require.js
5. View Templates with Underscore.js
6. Instantiated View
7. Collection View (Excerpt)
8. View Signature
9. Fill-In Rendering
10. Actions and Animations
11. Reduced Models and Collections
12. Non-REST Models
13. Changes Feed (Excerpt)
14. Pagination and Search
15. Constructor Route
16. Router Redirection
17. Evented Routers
18. Object References in Backbone
19. Custom Events
20. Testing with Jasmine

The book is based around a hypothetical online calendar application, analogous to Google Calendar. I use GCal a lot so it was nice to have familiar examples — some books use made-up applications that are unfamiliar or too vague (even a blog or a todo list could be designed in many different ways). But when examples are based based off a specific real-world application like GCal or Twitter then you already know how it’s supposed to behave and it simply becomes a matter of mapping that behaviour to the code examples on the page.

The book is structured as a series of enhancements to the calendar — starting with a plain jQuery $.getJSON() on a server-generated HTML page, just like we used to write in 2008. This was a good familiar starting point for me, before leaping into a basic Backbone structure and then refactoring it and adding more advanced behaviour.

The twenty chapters are each presented in a problem: solution format. They are very brief but I really liked this — they are clear, succinct, get straight to the point, and are very readable. Code is explained in 3-4 line chunks at a time, which fit well on my Kindle (which has a small screen and no colors). Overall I thought it was very good value for time spent reading.

For me, the book was valuable because:

• It corrected some things I thought I already knew :) like $(el) injection
• It showed patterns for dealing with things like view deactivation and dangling event references (as a WPF developer this stuff gives me nightmares)
• It showed how simply and elegantly difficult things like paging could be implemented
• It suggested some neat things I hadn’t even thought about yet e.g. constructor routing

The book also includes a chapter on Require.js, which it presents early on as a foundation — chapter four — right after namespacing. I’m a fan of require.js and have no doubt it will soon become a standard requirement for any serious JS development in future. But right now it’s not widely supported and — in my experience — can cause a lot more problems than it solves. Unless you’re totally comfortable accepting the fact you’ll probably have to hack a lot of third party jQuery plugins just to make them work, I would not recommend require.js to beginners until the rest of the community catches up.

Regardless, Recipes With Backbone is still the single best text I’ve read on Backbone (aside from the Backbone docs themselves), and I’m looking forward to seeing what else these guys write. I would definitely recommend it to anyone wanting to take their Backbone skills to the next level. Go check it out and read the sample chapters here: http://recipeswithbackbone.com

// a .NET class like this...
public class Book
{
    public int NumberOfPages { get; set; }
    public string Author { get; set; }
}

// ... should be serialized into JSON like this
{
    "numberOfPages": 42,
    "author": "JK Rowling"
}

Luckily this is quite easy to fix with a custom formatter. I started with Henrik Nielsen’s custom Json.NET formatter and changed it slightly to use a camelCase resolver and also indent the JSON output (just for developers; we would turn this off once the app was deployed). You can grab the code here: https://gist.github.com/2012642

Then just swap out the default JSON formatter in your global.asax.cs:

var config = GlobalConfiguration.Configuration;

// Replace the default JsonFormatter with our custom one
var index = config.Formatters.IndexOf(config.Formatters.JsonFormatter);
config.Formatters[index] = new JsonCamelCaseFormatter();

var order = session.Include<Order>(x => x.CustomerId)
    .Load("orders/1234");

// this will not require querying the server!
var cust = session.Load<Customer>(order.CustomerId);

That doesn’t look too difficult at first glance – it looks pretty similar to futures in NHibernate, which I’ve used plenty of times before. But hang on. The first line instructs RavenDB to preload a second object behind the scenes, but how does it know it specifically to be a Customer?

session.Include<Order>(x => x.CustomerId)

At first I thought there should be a Customer type argument somewhere. Something like this:

// WRONG
var order = session.Include<Customer>(...)
    .Load<Order>(...)

Otherwise how can RavenDB know I want a Customer and not some other type? Maybe the Order.CustomerID property is actually stored in RavenDB as sort of strongly-typed weak reference to another object? Maybe the order returned is some sort of runtime proxy object with referencing metadata built-in?

No no no. It is much simpler than that. Let’s take a step back.

In a traditional SQL database, you need both the type (table name) and ID to locate an object. The ID alone is not enough, because two differently typed objects may have the same ID (but in different tables). So you need the type as well.

In RavenDB, you only need the ID. This is possible because RavenDB does not have the concept of types – under the covers it’s effectively just one big key-value store of JSON strings which get deserialized by the client into different CLR types. Even though the RavenDB .NET client is strongly typed (Customers and Orders), the server has no awareness of the different types stored within it.*

This is what makes includes work. Raven doesn’t need to know the type of the document being included, it’s just another chunk of JSON (which could be deserialized as anything). And the ID can only point to exactly one document because all documents are stored in the same single key-value store. So, back to the original example:

// This line instructs RavenDB to preload the JSON document
// that has an ID == x.CustomerId
var order = session.Include<Order>(x => x.CustomerId)
    .Load("orders/1234");

// This line accesses the previously-loaded JSON document and
// deserializes it as a Customer.
var cust = session.Load<Customer>(order.CustomerId);

That makes much more sense now.

* actually RavenDB does keep metadata about the CLR type, but for unrelated purposes.

REST APIs get you great end-to-end test coverage

Line for line, an end-to-end system test covers a lot more code than a deep down class-level unit test. They also more closely simulate a user’s actions, providing a realistic path of possible scenarios that need to be verified. So for the most bang for your buck, you want to be testing at the outermost level possible.

The ultimate level here is testing through UI automation — simulating clicks and looking for responses on screen, as a real user would do. However, although UI automation libraries are improving, UI tests still tend to be very complex to write and are often brittle to things like positioning/layout changes. A public API provides a fantastic alternative ‘hooking’ point of entry where application behaviour can be invoked from external code, without involving the UI but still typically mirroring fields and actions on screen pretty closely (if well-designed in order to keep your clients fast and lightweight).

So testing against an API avoids the complexity of UI testing but still give the system a thorough end-to-end workout.

Tests written against REST APIs aren’t brittle

Although the back-end behind your API may change considerably, a public API must continue to work in the exact same way or you’ll break all your clients and have a lot of very angry users. So as well as covering more lines of code for less effort, tests written against a public API won’t be as brittle and need updating as often as ‘subcutaneous’ ones testing against internal code structures.

Everyone can connect to a REST API

If you had to choose a protocol for interacting with your application, you couldn’t find a much simpler one than REST. Stateless HTTP, verbs, status codes and JSON — 99% of the time you need nothing but a browser to debug it, and your tests can be written in a completely different language than the API back-end and still be completely understandable.

Compare this to previous ‘standard’ HTTP protocols that were often anything-but understandable – even with things like service discovery and WSDLs (designed to help developers), debugging SOAP XML mismatches between a Java Metro client and a .NET WCF service is one personal hell I hope never to have to relive.

Not just for big APIs

Remember you don’t need a formal public API like Twitter or Facebook to realise the testing benefits mentioned here. Pretty much any sort of REST endpoint will do. The JSON handlers powering your single-page web app would be a great entry point to get started testing underlying behaviour, for example.

However, Raven DB does guarantee uniqueness in one place: each document must have a unique ID, or a ConcurrencyException will be thrown. By creating dummy documents with say, an email address for an ID, this feature can be effectively exploited to achieve unique constraints in Raven DB.

You can easily add this behaviour to your database if you install the Raven DB UniqueConstraints Bundle, which will enforce uniqueness on updates as well as inserts. However… if the field is immutable and you just want something quick and dirty you can use this: RavenUniqueInserter.cs :)

using (var session = documentStore.OpenSession())
{
    var user = new User
                   {
                       EmailAddress = "rdingwall@gmail.com",
                       Name = "Richard Dingwall"
                   };
    try
    {
        new RavenUniqueInserter()
            .StoreUnique(session, user, p => p.EmailAddress);
    }
    catch (ConcurrencyException)
    {
        // email address already in use
    }
}

It works by simply wrapping the call to DocumentSession.Store() with another document – in this case, it would also create a document with ID UniqueConstraints/MyApp.User/rdingwall@gmail.com, guaranteed to be unique.

You can grab it here: https://gist.github.com/1950991

• You do not want your test to be affected by any existing documents, so ideally the Raven DB database would be completely empty.
• Your test may span multiple document sessions, so doing it all within a single transaction and rolling it back is not an option.
• You want your tests to run fast.

What are your options?

Raven DB currently has no DROP DATABASE or equivalent command. The recommended method is simply to delete Raven DB’s Server\Data or Server\Tenants directories, but this requires restarting the Raven DB service (expensive). Also any live document stores may throw an exception at this point.

Multi-tenanting

One option that Raven DB makes very cheap, however, is spinning up new database instances (aka tenants). In fact all you need to do is specify a new DefaultDatabase and the document store will spin a new database up for you. For example:

var store = new DocumentStore
    {
        Url = "http://localhost:8080",
        DefaultDatabase = "MyAppTests-" + DateTime.Now.Ticks
    };
store.Initialize();

// now you have an empty database!

Pretty easy huh? Here’s a little test helper I wrote to help manage these sandbox databases, stores and sessions. Here’s how you would use it in a tenant-per-fixture test:

[TestFixture]
public class When_doing_something
{
    [TestFixtureSetUp]
    public void SetUp()
    {
        RavenDB.SpinUpNewDatabase();

        using (var session = RavenDB.OpenSession())
        {
            // insert test data
        }
    }

    [Test]
    public void It_should_foo()
    {
        using (var session = RavenDB.OpenSession())
        {
            // run tests
        }
    }
}

You can grab it here as a gist on Github: https://gist.github.com/1940759.

Note that if you use this method, a number of sandbox databases will (of course) build up over time. You can clean these up you by simply deleting the Raven DB data directories. (See gist for an example batch file you can throw in your source control to do this.)