Katas also have the added benefit of making non-geeks think we’re healthy individuals that don’t just sit in dark basements all day. In fact, we’ve started using the word dojo to make absolutely sure our new image sticks.

Anyway, I had an interesting kata-like problem at work and I figured it’d be cool to describe it here for the masses of programmers out there having cold sweats and shaking in need of their next kata fix.

Feel free to have a go, and if you do, please leave a comment linking to your solution so I can collect them all at the bottom of this post. Then we can all mock each other (no pun intended). It’ll also be interesting to see if the choice of programming language affects the solution.

The Kata

Imagine we have a list of jobs, each represented by a character. Because certain jobs must be done before others, a job may have a dependency on another job. For example, a may depend on b, meaning the final sequence of jobs should place b before a. If a has no dependency, the position of a in the final sequence does not matter.

The goal of the kata is to parse the job dependency structure and produce a sequence of jobs in the order that observes their dependency chain.

Start with a method that accepts a single string argument and returns a string which represents the ordered sequence of jobs (since each job is a single character). We’ll refine the algorithm by evolving the requirements with each step, just like the string calculator kata.

Step 1 – Empty String

Given you’re passed an empty string (no jobs), the result should be an empty sequence.

Step 2 – Single Job

Given the following job structure:

a =>

The result should be a sequence consisting of a single job a.

Step 3 – Multiple Jobs

Given the following job structure:

a =>
b =>
c =>

The result should be a sequence containing all three jobs abc in no significant order.

Step 4 – Multiple Jobs, Single Dependency

Given the following job structure:

a =>
b => c
c =>

The result should be a sequence that positions c before b, containing all three jobs abc.

Step 5 – Multiple Jobs, Multiple Dependencies

Given the following job structure:

a =>
b => c
c => f
d => a
e => b
f =>

The result should be a sequence that positions f before c, c before b, b before e and a before d containing all six jobs abcdef.

Step 6 – Multiple Jobs, Self Referencing Dependency

Given the following job structure:

a =>
b =>
c => c

The result should be an error stating that jobs can’t depend on themselves.

Step 7 – Multiple Jobs, Circular Dependency Chain

Given the following job structure:

a =>
b => c
c => f
d => a
e =>
f => b

The result should be an error stating that jobs can’t have circular dependencies.

Completed Solutions

In Ruby

Ash solves the kata using RGL and RSpec

Caius solves the kata using black magic and testrocket

Sam solves the kata using RSpec

Kevin solves the kata in the style of TDD as if you meant it using RSpec

Matt solves the kata using RSpec

In C++

Thomas solves the kata using C++11

In C#

Martin solves the kata using MSpec

Thomas solves the kata using MSTest

Gemma solves the kata using NUnit

In Python

Mark solves the kata using unittest

In SQL (yes, SQL)

Sherwin solves the kata using manual tests

Johnno solves the kata using EYEUnit

Kev solves the kata using manual tests

In CoffeeScript

Tom solves the kata using nodeunit and documents his solution

In Scala

David solves the kata using specs

In JavaScript

Sam solves the kata again using Jasmine

Initially, I wondered what exactly it meant until someone on Twitter clarified it.

Monkey patching! It surprised me because, until now, I saw the future of C# as an increasing story of ceremony. In recent months F# has been gaining an unbelievable amount of attention because of its awesome inference and perceived simplicity due to lack of ceremony. And let’s not even mention Ruby.

Lots of the dynamic languages, in fact, seem to involve much less work these days when it comes to bending the language into a shape that fits the problem well. And really, that’s what we do as programmers. The question is: how can the language be so flexible that it lets us solve any problem?

Without Monkey Patching

I’ve been writing a really simple app that lets users register for an account and store notes. Until today, I had been jumping through hoops trying to aim for the right amount of SRP and DI that makes this thing testable. What I ended up doing was extracting an interface for each dependency of the unit that I needed to test, so that I could test it in complete isolation.

We know that interfaces weren’t intended solely for producing seams for testing, but that’s pretty much how we all use them anyway. We end up with two, three, maybe four additional interfaces and associated classes, and a dependency chain, when all we really wanted was to test the damn thing.

It’s true that we potentially get a better design in terms of looser coupling and separation of concerns, but get this: I don’t want that in this case. This is a single controller app with a small and perfectly understandable behaviour. I should be able to bend C# (and not have to work around it) into testing my app.

Ultimately we end up trading complexity for testability. Incidentally, isn’t complexity proportional to number of bugs? In reality, testability should be easy and should be part of the pit of success.

C# Just Took Up Yoga

Well, things just changed. From what I understand, the CLR guys managed to implement new functionality that allows the assignment of a delegate to a method group. It does some kind of smart matching with the delegate parameters. I don’t know all the technical details, but I do know that it freaking rocks.

Consider my simple app:

public class UserService
{
    public void Register(string username)
    {
        using (var context = new DataContext())
        {
            context.Users.Add(new User
            {
                Username = username,
                Created = DateTime.Now
            });

            context.SaveChanges();
        }

        Notifications.Send("New user: " + username);
    }
}

Normally I’d be coupled to DataContext, DateTime.Now and my static Notifications.Send method, making unit testing this method particularly difficult. But since C# 6 supports monkey patching, this thing is now perfectly testable and without the otherwise unnecessary interfaces and complexity.

We can patch DataContext (stubbing it, in test parlance) and make it do nothing. We can patch DateTime.Now to give us a more predictable value. And we can certainly patch Notifications.Send so that it doesn’t send anything and just allows us to inspect the message.

Here’s the test:

[Test]
public void Register_WithValidUsername_RegisterUserAndNotifies()
{
    User user;
    string notification;

    // Patch

    DateTime.Now = () => new DateTime(1, 1, 1);

    DataContext.SaveChanges = (context) =>
    {
        user = context.Users.FirstOrDefault();
    };

    Notifications.Send = (msg) =>
    {
        notification = msg;
    };

    // Act

    new UserService.Register("bob");

    // Asset

    Assert.That(user.Username, Is.EqualTo("bob"));
    Assert.That(user.Created.Year, Is.EqualTo(1));
    Assert.That(user.Created.Month, Is.EqualTo(1));
    Assert.That(user.Created.Day, Is.EqualTo(1));
    Assert.That(notification, Is.EqualTo("New user: bob"));
}

Not Limited To Testing

Monkey patching (also know as duck punching, if you prefer) is not only useful for testing. This new ability to patch stuff means we can replace behaviour in classes that we don’t necessarily own.

Some HTTP library you’re using have a broken URL encoding method? Just patch it. Want to redirect a method to somewhere else without introducing a subclass? Just patch it.

What Does This Mean?

Today was a big day for C# – it just became easier to fall into the pit of success:

• Testing code is now much easier out of the box since all we have to do is stub it via a good old duck punch to the gut.
• We don’t have to introduce 5 interfaces purely for the sake of testability when the design doesn’t require such decoupling.
• All that legacy (otherwise untestable) code is now testable – just patch it.
• Bugs in code we don’t own just became fixable.

But most importantly, C# gave us back some control and let us decide what’s dangerous and what’s not. C# just became more flexible and gave us a chance to be more awesome with it. C# just trusted us.

In the final post, we’ll work through a to-do list demo which will pull together a number of the features already covered in the series into a complete application.

What We’re Building

We’re going to build a simple web application with a JSON/XML API that allows the creation, deletion and completion of simple to-do items. We’ll have a view that displays the current list, a method for removing and completing individual items and a form for creating new ones.

The Resources

Let’s consider which resources we’ll need to create in order to support the requirements.

/login

The LoginHandler will allow a user to authenticate by providing a login view.

/todo/list

The TodoListHandler will display the current list of to-do items.

/todo/add

The TodoAddHandler will create a new item and redirect back to the list.

/todo/complete

The TodoCompleteHandler will complete an item and redirect back to the list.

/todo/uncomplete

The TodoUncompleteHandler will undo the completed status and redirect back to the list.

/todo/remove

The TodoRemoveHandler will delete an item and redirect back to the list.

The API

As it’s a demo, we’ll keep the API simple. Our imaginary requirement here is that the current to-do list should be available outside of the application for things like external widgets or mobile phone applications to consume.

We’ll achieve this with a single handler at /api/todo/list that returns the current to-do list in either JSON or XML format.

Authentication

For the sake of keeping the demo easy to understand, our security requirements are simply going to be that a user must log in using a hard-coded username and password before they can use the application. We’ll use an authentication filter to implement this.

Logging

Finally, to catch any errors with our to-do list, we’ll also implement error logging so that we can periodically check any exceptions that have been thrown by the handlers.

Here’s One I Prepared Earlier

To use the demo, the first thing we need to do is authenticate at /login using the hard-coded username and password admin and password respectively:

We’re then presented with the to-do list at /todo/list:

Now that we have a feel for what this thing looks like, let’s go through the implementation details and discuss how it’s built with Tinyweb. If you’d like to follow along beyond the snippets used in the rest of this post, you can do so by looking at the demo code on github.

Project Layout

Although Tinyweb does not enforce a particular convention in terms of where you put files within the project, I tend to follow my own to be consistent between projects. Handlers go in a Handlers folder, filters in Filters and so on. Here’s the project layout for the to-do demo app.

It should be fairly easy to figure out what’s going on. Don’t worry too much about the files inside the Database directory since data access isn’t especially relevant to the demo app. Similarly, the Content directory isn’t too interesting either, it just contains CSS and JavaScript.

The core of the app is contained within the directories you see expanded. We have the aforementioned handlers right there in Handlers. Note how I’ve separated the API and the web app handlers to make it more explicit (again, just my own convention here).

There aren’t many views, so I’ve just bunched them together under Views. We also have a partial view named Add.spark which just creates a <form> that enables new to-do items to be posted to /todo/add.

From The Beginning

As we’ve covered in the previous posts, the first step in creating a Tinyweb app is to initialise the framework in Global.asax:

protected void Application_Start(object sender, EventArgs e)
{
    Tinyweb.AllowFormatExtensions = true;

    Tinyweb.Init(new DatabaseRegistry());

    Tinyweb.OnError = (exception, request, handler) =>
    {
        var error = String.Format("Error at {0} from {1}:\r\n{2}",
                                  handler.Uri,
                                  handler.Type.Name,
                                  exception.ToString());

        var log = request.HttpContext.Server.MapPath("/errors.txt");
        File.AppendAllLines(log, new[] { error });
    };
}

The first thing we do is turn on format extensions, allowing the Accept header to be specified on the URL (i.e. /api/todo/list.xml and /api/todo/list.json).

Next we initialise the framework and pass in a StructureMap registry. The DatabaseRegistry configures how the IDatabase dependency (used by handlers to persist the to-do list to a text file database) can be resolved at runtime.

Finally, we set up error logging using the Tinyweb.OnError delegate. In this instance, we just want to append to a log file every time an error occurs, storing the handler, the URL and the exception.

OK – Initialisation – check, let’s look at the root request handler.

RootHandler

I hope you didn’t get too excited, as the RootHandler is pretty dull. The only reason we have a RootHandler is so people new to Tinyweb running the demo actually reach the login page without having to find and enter the URL themselves. As such, RootHandler simply redirects to the LoginHandler:

public class RootHandler
{
    public IResult Get()
    {
        return Result.Redirect<LoginHandler>();
    }
}

LoginHandler

Moving right along, the next leg of the request takes us to the LoginHandler:

public class LoginHandler
{
    public IResult Get()
    {
        return View.Spark("Views/Login.spark", "Master.spark");
    }

    public IResult Post(RequestContext request, string username,
                                                string password)
    {
        if (username == "admin" && password == "password")
        {
            issueCookie(username);
            return Result.Redirect<TodoListHandler>();
        }

        return Result.Redirect<LoginHandler>();
    }

    private void issueCookie(string username)
    {
        var ticket = new FormsAuthenticationTicket(username, true, 60);

        HttpContext.Current.Response.Cookies.Add(
          new HttpCookie(FormsAuthentication.FormsCookieName,
                         FormsAuthentication.Encrypt(ticket))
        );
    }
}

When a GET request is made to the LoginHandler, the login view that we saw in the screenshot is rendered. When the login form is posted back, the username and password are checked against our hard-coded values. If they don’t match, we redirect to the LoginHandler so the user can try again.

If the username and password are correct, we use ASP.NET Forms Authentication to issue a ticket and log the user in. We can then redirect the user to the to-do list, safe in the knowledge that the authentication filter will let them through.

AuthenticationFilter

Our AuthenticationFilter runs before every request and makes sure that only authenticated users can access the to-do list.

public class AuthenticationFilter
{
    IList<Type> allowedHandlers = new List<Type>
    {
        typeof(LoginHandler), typeof(ApiTodoListHandler)
    };

    public IResult Before(RequestContext context,
                          HandlerData handler)
    {
        if (!context.HttpContext.User.Identity.IsAuthenticated)
        {
            if (!allowedHandlers.Contains(handler.Type))
            {
                return Result.Redirect<LoginHandler>();
            }
        }

        return Result.None();
    }
}

This is achieved by maintaining a list of allowedHandlers and checking each request against the list. If the request handler is not in the list, a check if made to see if the user has authenticated to determine if they’re allowed access to the resource. If the user isn’t authenticated, a redirect result is returned which bypasses the rest of the execution pipeline and asks the user to log in.

TodoListHandler

When authenticated, we hit the TodoListHandler:

public class TodoListHandler
{
    IDatabase _database;

    public TodoListHandler(IDatabase database)
    {
        _database = database;
    }

    public IResult Get()
    {
        var model = _database.GetAll();

        return View.Spark(model, "Views/List.spark", "Master.spark");
    }
}

The TodoListHandler is a fairly standard handler which uses its IDatabase dependency to retrieve the current to-do list.

The DatabaseRegistry that was registered during initialisation will allow Tinyweb to supply a concrete Database at runtime. The IDatabase dependency is a file-based database for storing and retrieving the to-do items. In a real application, we might depend on some service class instead of directly depending on a data access class like this, but it’s a demo – it’s allowed to suck.

The TodoListHandler retrieves the current to-do list and renders the Views/List.spark view, passing the to-do list as the model. Let’s take a look at the view:

<viewdata model="TodoList" />

<content name="header">

    Todo List

</content>

<content name="body">

    <div if="!Model.Items.Any()" class="notification">
        Woohoo - nothing to do!
    </div>

    <div each="var todo in Model.Items" class="${todo.Complete ? 'complete' : 'todo'}">

        <div class="text">
            ${todo.Text}
        </div>

        <div class="date">
            ${todo.Date.ToString("dddd dd MMM yy")}
        </div>

        <div class="menu">
            <a href="${Url.For<TodoRemoveHandler>(new { todo.ID })}">Remove</a> |
            <a href="${Url.For<TodoUncompleteHandler>(new { todo.ID })}" if="todo.Complete">Undo</a>
            <a href="${Url.For<TodoCompleteHandler>(new { todo.ID })}" if="!todo.Complete">Complete</a>
        </div>

        <div class="clear"></div>

    </div>

    <render partial="partials/add" />

</content>

The first thing to note is line 1 where the expected view model type is declared. The view is then broken into two sections – the header and the body.

The first thing the view does is conditionally show the Woohoo – nothing to do message depending on whether the model contains any to-do items. Notice the very clean if=”” Spark syntax for performing this check.

Next, the view repeats a <div> for each of the to-do items that exist within the model. For each item, the class of the <div> is set depending on the state of the to-do item (complete or not) and the content of the <div> is built up to reflect the data about the particular item, such as the text and date.

Lastly, we render the Partials/Add.spark view which provides the <form> for creating new to-do items:

<form id="add" method="post" action="${Url.For<TodoAddHandler>()}">

    <input type="text" name="todo" />

</form>

<script type="text/coffeescript">

    $ ->
      $('#add input').focus()
      $('#add').submit ->
        false if $('#add input').val() is ""

</script>

The partial exists mainly as a demonstration of how this is done using Spark, but also to show how the application might be broken up at the view level to reuse separate elements of the system (we may want to add a to-do item in some other area of the application).

Also notice the use of the Url.For helper. The use of Url.For is encouraged as it keeps the details of the actual URL in one place and makes refactoring safer and easier.

TodoAddHandler

When a new to-do item is posted, a request will be made to /todo/add with a single value named todo in the request. The TodoAddHandler will then come to the rescue:

public class TodoAddHandler
{
    IDatabase _database;

    public TodoAddHandler(IDatabase database)
    {
        _database = database;
    }

    public IResult Post(string todo)
    {
        _database.Add(new TodoItem {Text = todo, Date = DateTime.Now});
        _database.Save();

        return Result.Redirect<TodoListHandler>();
    }
}

Much like the TodoListHandler, the TodoAddHandler takes a dependency on IDatabase and simply delegates the work of adding the new to-do item to it. After adding the item, the user is redirected back to the TodoListHandler.

The TodoRemoveHandler, TodoCompleteHandler and TodoUncompleteHandler are all alike, delegating to an IDatabase dependency to perform their single task and redirecting back to the main to-do list afterwards.

The API

The API in this example is just a single end point that gives us back the current to-do list in either JSON or XML format. As you may have noticed before, the ApiTodoListHandler is exempt (as it’s contained within the allowedHandlers list) from authentication, allowing unauthenticated users to request data from the API.

public class ApiTodoListHandler
{
    IDatabase _database;

    public ApiTodoListHandler(IDatabase database)
    {
        _database = database;
    }

    public IResult Get()
    {
        return Result.JsonOrXml(_database.GetAll());
    }
}

Nothing should be too surprising here – we have a simple handler that supports GET requests at /api/todo/list and gives us back the representation we requested via the Accept header or via an extension override.

Recap

And that’s a wrap! We’ve now built the 7 web app handlers that collaborate to form the to-do list and we’ve also created a single API handler which allows the to-do list data to be consumed outside of the core application.

We’ve implemented error logging inside Tinyweb.OnError by appending log messages to a text file, allowing us to easily diagnose any errors resulting from handlers at runtime.

Finally, we saw how a global before filter could be used in conjunction with Forms Authentication to ensure that only authenticated users could access particular resources of the system.

The full to-do demo app can be found at https://github.com/martinrue/Todo-Demo if you’d like to play around with it.

That’s All Folks

So, this was the final post in the Tinyweb series and I hope by now it has touched on enough aspects of the framework to give you a good idea of where it sits and what it’s good at. Hopefully, at least one takeaway from this series of posts will be how simple Tinyweb makes building close-to-the-metal web applications – after all, that is Tinyweb’s primary goal.

I’d love to hear from anyone using the framework and please let me know if you come across any issues or have any suggestions. And remember, Tinyweb is open source and can be forked and contributed to from the github repository.

All of the content in this series is also detailed in the official documentation, so please check there for any clarifications or give me a nudge on Twitter.

In this post we’re going to see how to render views using the Spark view engine and take a closer look at how model binding works.

Views

We’ve already looked at the various result types that you can return from a handler, but we skipped over arguably the most important one, a view. A view is just HTML, but usually rendered through the use of a templating engine that makes it easier to combine HTML and data.

You may have played around with different view engines in MSMVC and come across the Spark view engine. If not, don’t worry – it’s fairly easy. Tinyweb ships with support for Spark, so that’s what we’ll use for the examples here.

Let’s see a simple example:

public class RootHandler
{
    public IResult Get()
    {
        return View.Spark("Views/Index.spark");
    }
}

We have a pretty typical handler which accepts GET requests at / (the root request) and outputs the Spark view at Views/Index.spark.

The notable difference from the other result types is that views come from the static class View, whereas other results come from Result i.e. Result.String. The only reason for this is that simple types and views are considered different and therefore kept separate.

You’ll notice that the view path starts with a directory named Views. Unlike MSMVC, this is not a convention – it’s just a pattern I tend to follow. If the view file was placed at the root of the application, we could simply return View.Spark(“Index.spark”).

There’s little point regurgitating the Spark documentation in this post, but in case you have never come across Spark before, here’s what a typical view might look like:

<viewdata model="QuestionAnswerJokes" />

<ul>
  <li each="var joke in Model.Jokes">
    Q: ${joke.Question}
    A: ${joke.Answer}
  </li>
</ul>

Our contrived view tells Spark that it’s expecting an instance of QuestionAnswerJokes to be passed to it. It then produces an <li> element for each joke contained within the QuestionAnswerJokes.Jokes collection, outputting the question and answer part of each joke into the <li>.

So, how does it get the model object?

View Models

In the handler above, the astute will have noticed that there’s no model being passed to the view. Fear not, I wasn’t trying to hide hideous complexity:

public class RootHandler
{
    public IResult Get()
    {
        var jokes = JokeService.GetQAJokes();
        return View.Spark(jokes, "Views/JokeList.spark");
    }
}

The view model is simply passed as the first argument to View.Spark, and as long as the model type matches the <viewdata model=”…”/> declaration, we’re good to go.

Master Pages

If we want a view to be part of a master layout, we must specify the master’s name (relative to the location of the view) in the call to View.Spark. This may become cleaner in the future, but for now, it looks like this:

public class RootHandler
{
    public IResult Get()
    {
        return View.Spark("Views/Index.spark", "Master.spark");
    }
}

Rendering views from Tinyweb doesn’t get much more difficult than that, so let’s continue on and take a look at model binding in Tinyweb.

Model Binding

Model binding is the process of automatically taking data from the request (such as the query string or form post data) and mapping that data to the parameters (or properties where a class is used as a parameter) of the handler method. Model binding is useful because it means you write less code and let the framework deal with boring jobs like digging into the request data and populating objects.

There are three locations that Tinyweb will search for data. It’ll look in the query string, followed by the form post data and finally the route data (which only applies if you are using custom routes with route parameters, see Routing).

Three types of model binding are currently supported:

• Simple parameters such as int and string
• Custom class parameters such as LoginModel and UserSignupModel
• Array parameters such as int[] and bool[]

Let’s go through each one and see an example of where it might be helpful.

Simple Parameters

public class CalculatorAddHandler
{
    public IResult Get(int first, int second)
    {
        return Result.String((first + second).ToString());
    }
}

If we now make a GET request to /calculator/add?first=4&second=2, we should be seeing 6 in the response. In the event no value is sent for first or second, we’ll get an error telling us that required parameters are missing. If you need optional parameters, see the Optional URL Parameters section of the docs (you could also use a custom class, where non-matched properties are just ignored).

Custom Class Parameters

We may also want to use our own classes as parameters to handlers for composing lots of separate fields. For example, If we were implementing a search handler we may want to use a SearchData class to hold the various search options:

public class SearchData
{
    public string Query { get; set; }
    public bool NewestFirst { get; set; }
}

Our handler can now accept an instance of this class, which the model binder will create and populate from the data in the request:

public class SearchHandler
{
    public IResult Get(SearchData searchData)
    {
        var results = SearchService.Search(searchData);
        return View.Spark(results, "Views/Results.spark");
    }
}

A request to /search?query=help&newestFirst=true will result in the creation of the SearchData object with the relevant properties populated. If the model binder can’t find data for a property, it will simply ignore it without throwing an exception.

Array Parameters

Binding to array parameters can be useful for situations where a collection of values is posted to a handler (via AJAX for example). Let’s assume we have a list of ToDo items in a view and when an item is clicked we toggle an attribute that marks it as complete. Clicking the Save button might run something like the following:

var completed = new Array();

$('#todos').each(function() {
    if ($(this).attr('complete') == 'true') {
        completed.push($(this).attr('todoId'));
    }
});

$.post('/todo/delete', { Completed: completed }, function() {
    alert('Saved');
});

The script builds up an array of numbers and posts them to /todo/delete. A handler can receive the collection like this:

public class TodoDeleteHandler
{
    public IResult Post(int[] completed)
    {
        var deleted = TodoService.DeleteMany(completed);
        return Result.JsonOrXml(deleted);
    }
}

Special Binding Cases

Tinyweb’s model binder has two special cases where the handler or filter can get access to either the RequestContext or the HandlerData for the current request.

The RequestContext gives you access to the underlying ASP.NET infrastructure (the HttpContext – please, don’t run away, come back) and means you can do anything that you’d do from within a raw HttpHandler, such as access the Request, Response, Cache and Session collections.

HandlerData is a class from tinyweb.framework that holds the handler’s System.Type and its URL, in addition to any default route values it has defined. Accessing HandlerData is useful more so in filters where the handler for the current request needs to be identified for things like logging.

The model binder will supply RequestContext and HandlerData to any handler or filter that declares a parameter of either type.

Model Binding Limitations

As of version 2.1.0 of Tinyweb, the model binder provides no way to exclude individual properties from model binding. The recommended practice is to use a type specifically crafted for receiving only the data you care about from model binding. The next release will add support for binding exclusions, addressing those situations where you wish to bind to existing objects but restrict the binding scope.

EDIT As of version 2.1.2, binding exclusions are supported via use of the [Ignore] attribute on class members that should be excluded from model binding. See model binding for more information.

In This Post

We looked at rendering Spark views and touched on how to use view models and master layouts. We then focused on model binding in a little more depth, looking at each of the three (simple, complex & array) types of binding supported and – as is tradition at this point – built a couple of contrived examples to demonstrate the point. Finally, we saw the two special binding cases for getting access to RequestContext and HandlerData.

Keep in mind that everything we’ve covered so far is also covered in the documentation, which is the best place to go if you require clarification. Failing that, I’ve been known to tweet once or twice.

In The Final Post

We’ll put together a few of the things talked about so far and build a ToDo application, dealing with things like API access, authentication and logging. We may even get time to do some benchmarking.

The examples in the last post used made-up dependencies and you may have wondered how does the handler get these dependencies? In this post, we’ll look at how easy it is to have dependencies injected into handlers. We’ll also take a look at the use of filters to facilitate things like logging and error handling.

Dependency Injection

We probably all know what dependency injection is, but let’s just clarify. Assume we have a UserService which implements IUserService, allowing us to invert the dependency (SOLID). In a handler (or filter), we need access to an instance of UserService, but we can’t create one directly as we’d violate DIP. Instead we need a container to create the dependency chain for us. We simply depend on the interface and leave the dependency construction to the container.

Let’s see how we can do this in Tinyweb.

In line with its goal of keeping things as simple as possible, Tinyweb takes a dependency on StructureMap in order to support dependency injection out of the box. This means that all you need to do is create StructureMap registries and tell Tinyweb about them – the rest will be handled by the framework.

Using the UserService example from above, let’s assume we have the following:

public interface IUserService
{
    User GetById(int id);
}

public class UserService : IUserService
{
    public User GetById(int id)
    {
        // find the user and return it
    }
}

The next thing we need to do is create a StructureMap registry which associates these two, like so:

public class ServiceRegistry : Registry
{
    public ServiceRegistry()
    {
        Scan(x =>
        {
            x.TheCallingAssembly();
            x.WithDefaultConventions();
        });
    }
}

The ServiceRegistry tells StructureMap that interfaces IFoo and IBar in the current assembly should have concrete types called Foo and Bar respectively.

We need to tell Tinyweb about this registry for it to be  able to construct handlers that have constructor dependencies. Registering them is as easy as passing them to Tinyweb.Init, like so:

protected void Application_Start(object sender, EventArgs e)
{
    Tinyweb.Init(new ServiceRegistry());
}

Internally Tinyweb associates any registries with StructureMap, which it then uses to create handlers when requests come in. This allows us to create handlers with abstract dependencies and have the framework deal with it for us:

public class UsersAddHandler
{
    IUserService _userService;

    public UsersAddHandler(IUserService userService)
    {
        _userService = userService;
    }

    public IResult Post(User user)
    {
        var added = _userService.Add(user);
        return Result.JsonOrXml(added);
    }
}

When a POST request is made to /users/add, the framework will create an instance of the UsersAddHandler using StructureMap, and because we have registered the ServiceRegistry the IUserService dependency will be supplied as a concrete UserService.

Filters

Moving on, let’s take a look at filters and see how they let us plug into the execution pipeline of a request. Tinyweb supports both handler filters and global filters. A handler filter is a Before or After method on the handler which is run before or after the intended HTTP method is run, like so:

public class RootHandler
{
    public IResult Before()
    {
        return Result.String("Before the request...");
    }

    public IResult Get()
    {
        return Result.String("Root request");
    }

    public IResult After()
    {
        return Result.String("After the request...");
    }
}

Notice how the two filters also return IResult, allowing them to affect the response. Filters can have void return types if they don’t wish to add anything to the response. The example above, predictably, outputs the following:

Before the request...
Root request
After the request...

Filters also have the same model binding support that handler methods have, allowing a filter to log events using data from the request, for example:

public class UsersDeleteHandler
{
    public IResult Post(int id)
    {
        var deleted = UserService.Delete(id);
        return Result.JsonOrXml(deleted);
    }

    public void After(int id)
    {
        Logger.Log("Deleted user " + id);
    }
}

Since we’re simply logging that a user has been deleted, we don’t use the IResult return type on the After filter.

To recap, handler filters are just well defined ways of running code just prior or just after a handler method is executed. Let’s move on and have a look at global filters.

Tinyweb also supports global filters that apply to all handlers, which is useful for system-level logging or performance monitoring. Use a global filter when something needs to happen before or after every request.

Like handler filters, global filters also support model binding – though it may not be very useful for situations where you’re logging every request (as you wouldn’t know which request and hence what required data has been sent).

Global filters are just like handler filters except they must exist in a separate class which ends with the word Filter. MyLoggingFilter would be discovered as a valid filter (as long as it had a Before or After method), whereas MyLoggerFilterClass would not be found because it doesn’t end with the word Filter.

Let’s see an example:

public class TimingFilter
{
    Stopwatch timer;

    public void Before()
    {
        timer = Stopwatch.StartNew();
    }

    public IResult After()
    {
        timer.Stop();
        return Result.String("Time: " + timer.ElapsedMilliseconds);
    }
}

This filter adds the Time: xxxx message to the bottom of every request, allowing us to see how quickly each request executes.

Global filters can also get access to the underlying RequestContext (from ASP.NET) and the HandlerData – Tinyweb’s internal structure used to identify the intended handler. If we wanted to create a list of every handler that was requested, we could use a global filter with HandlerData to do it:

public class RequestLoggingFilter
{
    public void After(HandlerData handler)
    {
        Logger.Log("Request completed to " + handler.Type);
    }
}

Finally, in terms of logging errors, this can be dealt with by supplying a delegate to Tinyweb.OnError which will receive the exception, the RequestContext and the HandlerData for the offending handler, like so:

protected void Application_Start(object sender, EventArgs e)
{
    Tinyweb.Init();

    Tinyweb.OnError = (exception, request, handler) =>
    {
        Logger.Log(exception + " error for " + handler.Type);
    }
}

See the documentation for more details about error logging with the OnError delegate.

In This Post

We saw how Tinyweb makes injecting dependencies into handlers (and filters) easy through its internal use of StructureMap. We then moved onto filters and saw how Tinyweb supports filtering at both the handler level and globally.

We then walked through a couple of demos showing how we can use global filters for logging and timing requests. Finally we saw a brief example of how error logging can be achieved using Tinyweb.OnError.

In The Next Post

We’ll see how to use the Spark view engine and take a closer look at model binding.

We took a brief look at how handlers return content to the client, but in today’s post we’ll take a more in-depth look at how this works.

Returning Data From Handlers

In case you can’t remember, here’s a typical Tinyweb handler which processes HTTP GET requests at the URL /users/create and returns an HTML view:

public class UsersCreateHandler
{
    public IResult Get()
    {
        return View.Spark("Views/Signup.spark");
    }
}

The UsersCreateHandler is simply rendering a Spark view when a request is made to /users/create, providing the client with an HTML form to sign up. Let’s take a look at what else we can return from handlers.

The Result Class

To make handler result types more discoverable, you can use the static Result class to create them. This also serves the purpose of making any generic uses of the result types cleaner. Currently we have the following members in Result:

Result.None
Result.String
Result.Html
Result.File
Result.Json
Result.Xml
Result.JsonOrXml
Result.Redirect<T>

Let’s look at each one and see what it can be used for.

Result.None

No result? It may initially throw you, but the purpose of Result.None is to process a request without affecting the response body. Result.None exists to support two situations:

• Filters that don’t wish to affect the response in any way.
• Handlers that are to be treated in a fire-and-forget manner, where the response doesn’t matter.

We haven’t looked at filters yet, but here’s a contrived example for the fire-and-forget usage of Result.None:

public class ServerRebootHandler
{
    public IResult Get()
    {
        TheServer.Reboot();
        return Result.None();
    }
}

A caller just wants to signal that the server should be rebooted (don’t ask me why we’d want this, it’s contrived people) and not care about any result, so the handler returns Result.None so that it won’t waste time adding anything to the response body.

Result.String

We’ve seen this in some of the demos, and it’s fairly self explanatory. Result.String returns a raw string with an HTML content type, causing the browser to render any content as normal. It’s not something you’d use in an API or a web application necessarily, but it’s useful for diagnostics and situations where you just need to output simple things.

Result.Html

Result.Html is essentially the same as Result.String but it takes the data from a disk file instead of a raw string. Not especially exciting.

Result.File

Admittedly, this is becoming quite predictable now. Yes, Result.File allows you to send a file back in the response, causing a browser to show the familiar Save File dialog.

Result.Json and Result.Xml

Keeping with the theme of blatantly obvious, both these types do exactly what you might expect. Let’s see some more code:

public class UserDetailsHandler
{
    public IResult Get(int userId)
    {
        return Result.Json(UserService.GetById(userId));
    }
}

A request to /users/details/42 might return a JSON representation of the user object, like so:

{
  "ID":42,
  "Username":"Igor",
  "Age":62
}

Replacing Result.Json with Result.Xml would have the expected effect, and we’d be seeing beautiful XML in place of that horrible JSON. Erm, I think I got that right.

As a side note, you may be wondering about the parameter in the handler method. Tinyweb supports model binding of simple, complex and array types and will supply values to the handler that were found in the request or route data. We’ll look into this more in a future post.

Result.Redirect<T>

Stop – you missed one.

I’ll come to Result.JsonOrXml in a second, which will take us nicely into the discussion about building APIs with Tinyweb.

As I was saying – Result.Redirect<T> allows us to redirect from one handler to another. It kind of goes without saying that this is important, since otherwise there’d be no way for us to pass control between handlers to form more complex behaviours.

Result.Redirect<T> takes the handler type as the generic parameter, giving us some safety for future changes to handler names and such refactorings. There’s also a version that you can pass a raw URL to, if you so wish.

Quick example:

public class CuteKittensHandler
{
    public IResult Get()
    {
        GullibilityCount++;
        return Result.Redirect<RickHandler>();
    }
}

public class RickHandler
{
    public IResult Get()
    {
        return Result.Redirect("http://bit.ly/4kb77v");
    }
}

Don’t blame me, the signs were there all along.

Result.JsonOrXml

And finally we come to Result.JsonOrXml. The point of this type is to return the resource in a format that is preferred by the client. Clients typically specify this using the Accept header, but Tinyweb also allows Extension Overrides to make it easier.

Let’s look at the role Result.JsonOrXml plays in building JSON and XML APIs using Tinyweb.

Building APIs

Because Tinyweb enforces a development model where each handler can only support the basic HTTP methods for a single URL, we get lots of small, well defined handlers forming a system. This decoupling and focus on single responsibility works well for building web applications, but especially well for building HTTP APIs.

Let’s improvise another contrived example and build an HTTP API. We’ll assume the API is going to support a rich client in the browser, but also some legacy systems which require XML representations. In other words, we’ll be supporting both JSON and XML responses.

The API will allow us to manage a set of users via three resources, /users/add, /users/delete and /users/view for adding, deleting and viewing users respectively.

public class UsersAddHandler
{
    public IResult Post(User user)
    {
        UserService.Add(user);
        return Result.JsonOrXml(user);
    }
}

public class UsersDeleteHandler
{
    public IResult Post(int id)
    {
        var deleted = UserService.Delete(id);
        return Result.JsonOrXml(deleted);
    }
}

public class UsersViewHandler
{
    public IResult Get(int id)
    {
        var user = UserService.Get(id);
        return Result.JsonOrXml(user);
    }
}

Let’s have a look at each handler and see what’s going on.

First we have the UsersAddHandler which supports POST requests at /users/add. Any POST data that matches properties on the User object will be model bound automatically by Tinyweb.

The UsersAddHandler is pretty simple, it just creates a user by delegating to UserService.Add and then returns a representation of the new user back to the client.

Next we have the UsersDeleteHandler which is very much the same, supporting POST requests at /users/delete to remove users. This handler returns a representation of the true/false return value from UserService.Delete, indicating whether the user was deleted.

Finally, the UsersViewHandler returns a representation of the requested user at /users/view.

The Accept Header

As mentioned earlier, a handler that returns Result.JsonOrXml is specifying that the actual representation can be JSON or XML, depending on which is requested by the client via the Accept header. For example, if the UsersViewHandler is requested like this:

GET /users/view?id=42 HTTP/1.1
Accept: application/xml;q=0.8,application/json;q=0.7

Because the Accept header is preferring application/xml over application/json, Tinyweb will return an XML representation of the user. If it was requested with a preference for JSON over XML, the reverse would happen. Tinyweb defaults to JSON if no preference can be determined.

Extension Overrides

In addition to the Accept header, Tinyweb can be configured to use Extension Overrides which allow a URL extension to be used to control the preferred response type. For this to work, you’ll need to set AllowFormatExtensions to true during initialisation, like so:

protected void Application_Start(object sender, EventArgs e)
{
    Tinyweb.AllowFormatExtensions = true;
    Tinyweb.Init();
}

Now the same resource can be requested without the Accept header by appending either a .xml or .json extension to the URL, i.e. /users/view.json?id=42 or /users/view.xml?id=42. This makes debugging easier and some people prefer the more discoverable method of specifying response types in the URL.

In This Post

We looked at Tinyweb’s various response types and considered what they are useful for. In particular we saw how Result.Redirect<T> allows us to pass control between handlers in order to compose groups of handlers into more complex behaviours – albeit in a somewhat contrived example.

We then looked at how Tinyweb is suited to building HTTP APIs and looked at how Result.JsonOrXml allows us to defer specification of the response type to the client through the Accept header or through URL extensions.

In The Next Post

We’ll take a look at how Tinyweb tackles dependency injection with StructureMap and how we can use handler and global filters to extend the execution pipeline for things like logging and error handling.

Full documentation for the project was completed recently and I figure it’s time to write a how to series of posts that cover the most interesting aspects of the framework.

So here we are with the first instalment. My goal for part 1 is to explain the thinking behind the project and show you how easy it is to file –> new project.

What’s Tinyweb?

From the docs:

Tinyweb is a lightweight web framework for ASP.NET that embraces HTTP and aims to be ridiculously simple.

Approaching the project with a background in using the MVC pattern, my goal was to move away from the issue of fat controllers and provide less abstraction over the core functionality of HTTP.

In Tinyweb, the URL, or more precisely the resource is the starting concept. By resource, I mean a single entity addressable by its URL and able to respond to any of the standard HTTP methods.

The resource is just a simple class with methods for each HTTP method it wishes to respond to, for example:

public class SignupHandler
{
    IUserService _userService;

    public SignupHandler(IUserService userService)
    {
        _userService = userService;
    }

    public IResult Get()
    {
        return View.Spark("Views/Signup.spark");
    }

    public IResult Post(UserModel user)
    {
        _userService.CreateUser(user);
        return Result.Redirect<WelcomeHandler>();
    }
}

Because the SignupHandler has a single URL and can only respond to the core HTTP methods, a certain level of SRP is enforced by this model. Tinyweb encourages an application to be broken into separate resources that collectively form a coherent system.

Tinyweb leans more toward a service-oriented approach to building web applications, where every endpoint within the system has a well defined purpose and collaboration between endpoints is used to form more complex behaviours. This is particularly fitting for pure JSON or XML APIs and I’ll be covering some related features of Tinyweb later in the series.

Another underlying goal of Tinyweb is simplicity. The framework itself is small, with a tiny pipeline and simple conventions to save you having lots of configuration. Conventions aren’t concrete and can be overridden, but using Tinyweb should to be fun, easy and consistent.

File –> New Project

So, let’s see how we create a new project using Tinyweb.

We’ll need an empty project to start with, so go ahead and create a new ASP.NET Empty Web Application project in Visual Studio. Done it?

OK, next we need to install the latest version of Tinyweb using the wonderful NuGet. Open the Package Manager Console and cast this spell:

Install-Package Tinyweb

NuGet will go and grab the relevant assemblies and add them to your exciting new empty project. Once done, Tinyweb is installed and ready for us to start writing some code.

Fortunately Tinyweb doesn’t require you to add anything to the web.config. Instead, Tinyweb is initialised from within Global.asax. You won’t have one yet, so you’ll need to add a new Global.asax file to your project. After you’ve added it, initialise Tinyweb like so:

protected void Application_Start(object sender, EventArgs e)
{
    Tinyweb.Init();
}

That wasn’t too painful, was it? Tinyweb is now loaded and routes have been configured to the various handlers that were discovered. There are other things you can do at this point, but we’ll cover them later in the series. For now, this is all you need.

The Handler

All the required setup and initialisation is done, and we’re now ready to build our actual application. Since this is Tinyweb land, we need to think about the first resource our system will need. Given this is the introduction post, and I’m creatively numb, let’s be traditional. The first handler will respond to HTTP GET requests at /hello/world and respond with the message Hello World. Exciting huh? Just me then?

public class HelloWorldHandler
{
    public IResult Get()
    {
        return Result.String("Hello World");
    }
}

Pretty simple, but let’s break it down and understand what’s going on here.

The Handler Name

Firstly, notice how the class doesn’t implement any base or interface. A handler is a handler if it ends in Handler. Say that fast 10 times. When Tinyweb.Init is called, handlers are discovered by scanning for classes that end with the word Handler. There’s the first convention.

The first part of the handler name is significant too. Breaking it up into its constituent Pascal-cased words, the handler name is used to build the URL of the resource. Because our handler is named HelloWorldHandler, Tinyweb produces the URL /hello/world.

Had the handler been called HomeHandler, we’d have the URL /home, or YabaDabaDooHandler would be addressable at /yaba/daba/doo. There’s the second convention.

The Handler Method

Next we have the method itself. Tinyweb recognises four potential methods which mirror the underlying HTTP methods, i.e. Get, Post, Put and Delete. You can also have Before and After methods, but we’ll talk about those later in the series.

Notice how the method returns IResult. This is the interface used to represent a handler response. Handlers must have a return type of IResult to be properly discovered. Tinyweb supports a number of result types including Result.String, Result.Json and View.Spark and we’ll look at these in the next post.

Finally, the handler returns a value to the client by using the static Result class. Result provides access to the supported result types while View provides access to the supported set of view engine results. Tinyweb currently ships with support for the Spark view engine.

In This Post

I introduced Tinyweb – the minimal web framework that encourages the use of concepts from HTTP to build service-style applications using ASP.NET. I talked about Tinyweb’s core goal of simplicity and explained how Tinyweb makes use of conventions and discovery to keep your code as simple as possible.

We built an example application, demonstrating how to install, initialise and write our first handler. We then dug a bit deeper into the method used for generating handler URLs and looked at what a handler can do.

Until Next Time

If you want to dive in and have a play around, simply install Tinyweb from NuGet, check out the documentation and if you have any questions, I’d be happy to help.

Next time we’ll look at the different types of content that can be returned by a handler, and look specifically at some features which are aimed at building JSON/XML APIs.

To some, the zone is seen as some kind of rare Zen state. Some think it’s a myth that doesn’t actually exist. Either way, it’s understandable that there are so many different opinions; it’s not an easy thing to objectively discuss.

But, what the hell – here’s what I think.

In actual fact, the zone is nothing to do with programming – though it is a term that’s used much more often in this context. Being in the zone is just a condensed version of:

• Having a good understanding of the task
• Feeling as though you have the dedication and skill to complete the task
• Being able to concentrate
• Feeling happy in yourself and your environment

These are not simple states; being able to concentrate might be a combination of a quiet atmosphere and a good music playlist, or perhaps a tidy desk and no interruptions. There are lots of subjective elements of each of these states, but none of them are inherently difficult to achieve.

If you understand exactly what you need to do, know how to do it, know that you actually want to do it and can remain focused, the zone comes quite naturally.

But I think we can simplify this into something more fundamental.

Back in college, I did not like mathematics at all. I enjoyed the application of concepts rooted in mathematics, but the study of abstract things on their own totally disengaged me. But don’t worry, I wasn’t a total failure – I did well in other subjects, and it’s no coincidence I enjoyed them more.

Enjoyment has wonderful side effects. It’s much easier to focus on something you enjoy. It also requires much less effort to develop skills in subjects you enjoy; they sometimes even appear to develop transparently. And fairly obviously, it’s easier to achieve happiness through doing things you enjoy.

This is nothing new:

Success in highest and noblest form calls for peace of mind and enjoyment and happiness which comes only to the man who has found the work he likes best.

– Napoleon Hill

If we are lucky enough to be working on something we enjoy, the points above all become side effects of the fact that we’re enjoying ourselves. If we’re struggling to find the zone, we should look for opportunities to make what we’re doing more interesting. This will improve the chances of being able to focus and finding the required inspiration.

If we don’t enjoy what we’re doing, it’s unlikely we’ll find the zone without a good amount of self discipline. Maintaining focus and dedication, and building understanding without the catalyst of enjoyment is the reason people tend to do worse at things they hate and better at things they love.

There isn’t just one zone, there are many zones each competing for our attention. It’s not a coincidence that those who can’t get into the zone are telling us about it on Twitter. In fact, they have found the zone. They’re in the zone of socialising, which is a pretty easy zone to get into since it’s very enjoyable, but is it the zone you want to be in?

The zone is not some unachievable state of Zen, reserved only for the enlightened ones. You don’t need to sit with your legs crossed, humming, waiting for it to bless you with the ability to do awesome things – you already have that ability.

The zone is just a fancy-ass way of describing the required focus and dedication you need to do something to the best of your ability. When you enjoy what you’re doing, these things happen much more naturally. When you don’t, you need to compensate with discipline, and your mileage certainly may vary.

The zone isn’t random and it isn’t a myth – you can create it as often as you like.

Sentiment analysis is the process of analysing data to determine its sentiment, or mood. It’s an important area of research as it relates to improving things like customer satisfaction and making advertising more effective.

Sentiment analysis can add certain meaning to data and move us away from the simple keyword matching that we currently use. However, it’s a difficult problem to solve with around a 70% agreement rate between human analysers.

The simplest implementations tend to be things like bag of words where a collection of known positive and negative words are manually maintained and a subject is classified by calculating which collection has the most matches.

These word lists don’t scale well however. Much effort is needed to keep them up to date and deal with things such as misspellings and grammar errors. When you factor in context, which can often change the meaning, you’re left writing rules around the bag of words to capture those situations.

When you’re aiming to analyse data from a wide set of possible sources, the rules approach starts to fall short as the total number of possible words grows too large and problems such as including foreign languages cost you the entire effort all over again.

Instead we look to statistical solutions that help us deal with such large amounts of data. One such approach is naive Bayesian classification, which works by maintaining known classes of data (such as positive & negative) and calculating the combined probability that an input falls into each one.

The statistical approach also means that the problems mentioned above start to matter much less. Spelling errors and grammatical mistakes become part of the set and have a weighting like any other word – and the same applies for foreign language words.

Of course, seeding the classes with quality data then becomes the problem, and the effectiveness of the statistical approach does very much depend on the quality of the data used to seed it.

Some studies have been done that used data from sources such a movie reviews, which was known to be good or bad through the star rating. Unfortunately, such sources are too specific to a particular domain and tend not to perform well enough for more general analysis.

One possible source for mass amounts of data is Twitter, but the problem then becomes a matter of categorising a set of tweets into positive or negative in order to seed the algorithm. A fairly simple way to produce the two sets of data is to assume that all tweets containing a :) are positive and that all tweets containing a :( are negative.

Though there would be countless exceptions in a large set of data, it doesn’t matter too much as it would only be a problem if there were enough exceptions to affect the probability significantly.

The approach described is in production currently and producing good results. The set of seed data is fairly good with around 1 million tweets, but could be significantly bigger and consequently produce better results.

There are a number of real world applications of Bayesian classification that you’re probably already using, such as the spam filter. In addition, there are more sophisticated models that have been built on top of Bayesian classification and extend its application to fields like medicine. For further details, I recommend watching the 2010 Turing Lecture which goes into great detail about this subject.

I’ve built a full demonstration application to show how it works in reality. The demo takes a sentence and performs a classification, showing how each word is analysed in the process. You can play around with the demonstration at http://sentiment.brandlisten.com.

If you feel like extending the algorithm, or you’re just curious to see how it works at a code level, you can find the code for the demo at https://github.com/martinrue/Sentan.

And finally, here’s a link to the slides (which are mostly condensed versions of what has already been said here).

http://portal.sliderocket.com/AQJJH/Sentiment-Analysis

I’m having a perfectly reasonable day, improved slightly by the amount of Tina Turner I had been listening to. I’m working on an application that captures interesting conversations from Twitter, with the intention of seeding it with a great discussion between Uncle Bob and Dan North from last week.

The said conversation is withering away in Twitter’s archive and I’m hoping to complete this application swiftly before parts of the conversation become inaccessible to the API. I’m actually in the process of finishing the last bit that allows you to remove tweets from the final conversation.

In order to remove individual tweets, the full list is sent down to the client in an AJAX response. Each tweet is rendered in a <div> and has a new attribute that holds the tweet ID.

Let’s emulate the situation to demonstrate the problem:

<script type="text/javascript">

    var data = { id: 487592080484679444 };

    function addAttribute() {
        $('#element').attr('id', data.id);
    }

</script>

<div id="element"></div>

<a href="javascript:addAttribute()">Add Attribute</a>

Starting from the top, we have an object called data which has a field called id. The value of id is the numeric ID of a tweet, which we’ll be adding to the <div>. The addAttribute method finds the <div> and sets the id attribute to the value from the object.

Let’s run it and see what happens. Before we click the link, the DOM looks like:

As expected, we have our <div> and its id is still set to ‘element’. Now let’s click the link and cause the addAttribute to run. Here’s the DOM afterwards:

And there we go, our id is now set. But wait, what the hell – take another look at the value of the attribute and compare it to the value in the object. In pure JavaScript magic, it seems our original id of 487592080484679444 has been transformed into 487592080484679400.

While being wholly entertaining, and the very good trick not withstanding, I’d like to keep my hair for a few more years. After looking into the problem, it turns out that I was (until now) blissfully unaware that:

All numbers in Javascript are 64bit (8 bytes) floating point numbers…

Integers are considered reliable (numbers without a period or exponent notation) to 15 digits (9e15). Floating point numbers are considered only as reliable as possible and no more!

(http://www.hunlock.com/blogs/The_Complete_Javascript_Number_Reference)

Ah, 15 digits – that’s how it’s done.

Good one JavaScript, but not so impressive now that I know your dirty secret. Looks like it’s strings for this one.

So, we’ve all heard enough times by now the benefits of the SOLID principles. In particular, we know that we should minimise the responsibility of a class, with the aim of having just one responsibility per class and consequently only one reason for that class to change.

That’s an interesting word – change. We often refer to new work on an existing system as change, but unless the new work involves modifying the way something worked before, it shouldn’t be change, it should be extension.

As you know, another SOLID principle tells us that code should be open for extension, but closed for modification. Usually this refers to being able to extend behaviour by subclassing and using polymorphism to effectively replace the old behaviour – but can’t OCP be more generally applied?

What about our architecture, project layout, working conventions? Have these been arranged to support extension or will a change require that we have to rethink these things in order to accommodate future changes?

How Tinyweb Helps

Tinyweb takes a rest-style approach to building web applications by enforcing that a handler can only handle the standard HTTP methods for a single URL. For example, if we have a UsersHandler (liken this to a controller in MSMVC parlance) we will have a /Users URL and will only be able to respond to the HTTP GET, POST, PUT and DELETE methods for this resource.

Where in MSMVC you might have an AccountController with all kinds of actions, Tinyweb dictates that every URL is a separate resource independent of all others and requires its own handler.

I think this helps in enforcing a certain level of granularity and responsibility. While you can’t really argue that a handler has single responsibility (since it might handle both GET and POST), it more broadly has the single responsibility of controlling interactions with that resource.

This is why the web has evolved so successfully – everything is ultimately just an addressable resource that can send you to other resources in some coherent way to achieve a goal. Adding new functionality simply involves deciding which new resource to introduce and deciding how it will integrate with the existing system.

User Signup Example

Let’s see this workflow in action by using a simple example. Let’s pretend we’re building some web based system that requires users to sign up for accounts. We’ll start with a generic user registration system.

public class UserRegisterHandler
{
    public IResult Get()
    {
        return View.Spark("Signup.spark");
    }
}

By creating a handler named UserRegisterHandler, I’m in effect creating a resource addressable at /User/Register which can support any of the standard HTTP methods. In this particular case, I’ve implemented the HTTP GET method to allow the resource to display a view for a potential user to submit their account details.

Still thinking in terms of resources, we should now consider which resource will handle receiving a user’s details and creating the account. For the purposes of this example, we’ll use the same resource. So, a GET request to /User/Register will get the user registration view and a POST request to /User/Register will create the user.

public class UserRegisterHandler
{
    IAccountService _accountService;

    public UserRegisterHandler(IAccountService accountService)
    {
        _accountService = accountService;
    } 

    public IResult Get()
    {
        return View.Spark("Signup.spark");
    } 

    public IResult Post(User user)
    {
        _accountService.Create(user);
        return Result.String("Done");
    }
}

I’ve made a couple of changes to the handler here. I’ve introduced a dependency on an IAccountService which will handle the user registration. I’ve also implemented the HTTP POST method which binds the POST data to a User object and passes that down to the account service to do its magic.

Let’s continue this pretentious silliness and imagine that we’ve just been informed of our next requirement. Apparently, our current handling of new users leaves a lot to be desired. We’ve been told that when new users sign up, they should be taken to a page that welcomes them and confirms their details.

Because we’re thinking exclusively in terms of the resources our system is composed of, the next question becomes: which resource do we need to introduce to support this extension?

We’ll create a UserWelcomeHandler, giving us a new resource addressable at /User/Welcome. Let’s assume that a client will pass us the ID of the user we’re welcoming when issuing a GET request to this resource.

public class UserWelcomeHandler
{
    IAccountService _accountService;

    public UserWelcomeHandler(IAccountService accountService)
    {
        _accountService = accountService;
    }

    public IResult Get(int id)
    {
        var model = _accountService.GetWelcomeDetails(id);
        return View.Spark(model, "Welcome.spark");
    }
}

The user ID is now being taken from the GET request and being passed to the account service to fetch a model that represents the welcome details for that user. The model can then be rendered to a view as normal.

The new requirement has been implemented by introducing a new resource and extending the original system. But there’s still a missing link between the two resources, and we’ll have to return to the UserRegisterHandler and modify it. Instead of just displaying “done”, we want it to delegate responsibility to our new /User/Welcome resource.

public class UserRegisterHandler
{
    IAccountService _accountService;

    public UserRegisterHandler(IAccountService accountService)
    {
        _accountService = accountService;
    } 

    public IResult Get()
    {
        return View.Spark("Signup.spark");
    } 

    public IResult Post(User user)
    {
        var userID = _accountService.Create(user);

        var url = Url.For<UserWelcomeHandler>(new { UserID = userID });
        return Result.Redirect(url);
    }
}

With this change, the responsibility of UserRegisterHandler has been contained to dealing with the new account creation only. Satisfying our new requirement of welcoming the user has been implemented by introducing a new resource. We now simply move between the separate resources as required.

The Point

Although you could easily work this way with any framework, Tinyweb makes it more explicit with its opinionated approach to what a handler can do. You’re forced to think about separate resources and how they should collaborate to form a coherent system – and ultimately, this feels like a very natural and intentional way to build applications.

Times have certainly changed, particularly when it comes to web development. Thanks to awesome projects like Mono, it’s no longer the case that working with C# / ASP.NET binds you to Microsoft development tools and forces you to use Windows for development and hosting.

Mono brings a C# compiler and CLI implementation (in addition to other things) to operating systems such as Linux and Mac OS X, making technologies like C# and ASP.NET much more feasible and available.

Let’s see how easy it is to get up and running on Mac OS X using things we’d normally only assume were doable using Visual Studio and Windows. We’ll create a C# ASP.NET application using Mono and MonoDevelop (the IDE). We could also use ASP.NET MVC, but to further demonstrate how easy cross-platform has become with Mono, we’ll use a lightweight web framework that I have been working on called Tinyweb. And while we’re at it, let’s add the Spark view engine and StructureMap to the mix too.

The first thing you’ll need to do is install Mono and MonoDevelop. Head over to http://www.go-mono.com/mono-downloads/download.html and http://monodevelop.com/download and install the packages for your version of OS X. If you’re following this using Linux instead, just install the Linux packages and everything else should work in the same way.

Here’s one I prepared earlier:

MonoDevelop provides much the same experience that Visual Studio provides, so you should be pretty familiar with how it works, even if you’ve never used it before. The next job is to create a new solution, which is done exactly how you might expect: File –> New –> Solution.

Here’s another one I prepared earlier:

After entering the name and location, you should have a new solution with an empty ASP.NET project. Since we’re using Tinyweb as our web framework, the next thing we need to do is add the Tinyweb assemblies to the project.

You can get Tinyweb from its github repository and compile it yourself, but to make life easier there’s also a continuous release build here. You don’t need an account to access the CI server, just click the Login as a Guest User link at the bottom:

Once you have logged in, you should see the latest build of Tinyweb and a link to the build artifacts. Download the Tinyweb.zip archive which contains the various assemblies you’ll need to work with Tinyweb.

As an interesting side-point, the TeamCity server is actually a Windows Server 2008 machine building the Tinyweb project directly from its github repository using MSBuild, and yet we’re able to download these same assemblies and use them on a completely different operating system.

Let’s add references to the assemblies we’ll need. You’ll notice that the archive is organised into two directories: Framework and View Engines. You need to add references to both assemblies from Framework, and both assemblies from View Engines/Spark:

To keep things simple, we’ll create an application which handles requests for the URL /home. In Tinyweb land, this is a simple matter of creating a HomeHandler class and adding the required method to reflect the type of request we want to handle:

Tinyweb uses a convention whereby the name of the handler (excluding the word handler) is used as the URL that the handler responds to. It’s possible to override this convention by declaring a Route field in the class, like this:

public class HomeHandler
{
    Route route = new Route("UnconventionalUrl");

    public IHandlerResult Get()
    {
        return Result.String("Hello World");
    }
}

The handler would now respond to requests for the URL /UnconventionalUrl, not its original URL of /home.

Looking at our code so far, you’ll notice that we have a public method named Get. Methods in Tinyweb handlers must be named to match one of the HTTP verbs that they intend to process. Currently, we’ll be processing HTTP GET requests and returning a raw string as output.

So, we have a solution, we have a project, we have references to Tinyweb and we have a handler. Next up we need to initialise the Tinyweb framework at application start-up, cue Global.asax:

Nothing too ground-breaking here. We’ve just added a Global.asax file so we can hook into the ASP.NET application start-up event and call Tinyweb.Init. The Tinyweb.Init call simply provokes the framework to scan for handlers and set up the routes that have been found.

The last remaining thing to do is to make sure we’re targeting .NET 4 (because Tinyweb is compiled against version 4 of the CLR). Simply right-click the project and select properties. If any rocket scientists are reading, I apologise:

With any luck, you should now be able to build the solution and run it. When you run the project, MonoDevelop will start a local instance of the XSP web server on port 8080 in much the same way that Visual Studio uses its own local development server:

That was a pleasant experience, let’s continue with the demo and see how we can bring Spark to the party. In terms of code, we only need to make a slight change in order to return a Spark view instead of the raw string currently being returned:

The return statement has been changed to point to the Spark view file Hello.spark. Let’s see what happens when we run the project again:

Good, that’s what we should have expected since we’ve not created the view file yet. Easy fix – let’s create the view file Hello.spark in the root of the project:

It’s not a particularly ambitious view, we’re just keeping with the hello world theme while also using the Spark encoded output syntax ${} to output the current date and time from System.DateTime.Now. And, for my final trick:

If you were wondering what happened to StructureMap – it’s actually a dependency of Tinyweb and used internally when a handler needs instantiating to handle a request. If you were to add a constructor-injected dependency to a handler, you’d just need to supply a StructureMap registry to the Tinyweb.Init call in order to have that dependency supplied at runtime.

So there you have it – C#, ASP.NET, Tinyweb, Spark and StructureMap coming to you from sunny OS X, thanks to Mono.

EDIT

Due to the use of images in this post, the code samples have not been updated to reflect the latest public API changes in Tinyweb v2.0.0. The only significant difference is the renaming of IHandlerResult to IResult, so please be aware of this when following along.

From my very early days as a programmer, I would only be interested in very ambitious projects. It all started when I thought writing a compiler couldn’t exactly be rocket science, but of course, I hadn’t factored in the badly. Turns out rocket science is easy. But that was nothing compared to the firewall I tried to write (to be fair, I did actually get it working for defined packet filter rules. Please stop clapping). And let’s just not mention the protected mode kernel in x86 assembly.

Back then, and even now, people often say things like why bother? or but there’s already this other thing. To me, these are just challenges. I’m not trying to change the world and I won’t lose more than 3 nights of sleep if nobody ever uses what I’m working on. 4 at the most.

The point of a side project (if not commercial) is to push yourself out of your comfort zone – sometimes drastically. Doing this forces you to learn a ton. Learning how to write a compiler probably doesn’t transfer the most relevant knowledge, but generally speaking, ambitious projects provide lots of learning opportunity that you don’t tend to find in smaller projects, and I suspect this is why I am addicted to them.

Tinyweb

Earlier this week I released Tinyweb – a simple web framework for asp.net. While a web framework sitting on top of asp.net isn’t particularly ambitious, it was something I had little knowledge of. Pushing myself out of my comfort zone definitely taught me a lot and I’ll be writing some more about Tinyweb in another post.

Mide

Before questioning how hard a web framework could possibly be, I did briefly wonder how hard Visual Studio itself could be to write. And that brief moment was all it took. Apparently I have too much free time on my hands.

Well, let me tell you, the answer is hard. Luckily, I set my goals a little lot below those of Visual Studio. I figured having a simple text editor that could provide some of the core features of Visual Studio in terms of solution management and compilation/publishing would be great for situations where you don’t have VS (crazy idea, I know), or you want to quickly write a throw-away experiment.

So the result is Mide (Mini IDE).

Before a solution is opened, Mide acts like a normal text editor – letting you edit and save individual files. Once you open a solution, Mide shows you the familiar tree structure you see in VS:

For the most part, Mide offers the same control over the solution tree. Files, folders, references and projects can be added and removed from the solution. Mide is exclusively keyboard driven, so all such actions can only be performed through their associated keyboard shortcut (see shortcuts.txt in archive).

Mide still doesn’t implement some key things, such as execution of a test runner for unit test projects or the creation of new solutions from scratch (the File –> New Solution menu option doesn’t work yet). However, if you have an existing solution that you quickly need to edit, Mide should be able to handle that.

Mide can also be configured (though Build –> Settings…) to build and publish projects. This means that you can run builds as you’re writing code, and then publish directly to an IIS instance for testing your application locally. However, there’s no debugger or IntelliSense – sad trombone.

You can download an archive containing Mide here, please feel free to leave feedback. Note: Mide rewrites your .csproj and .sln files as changes are made to the solution tree, so it’d be wise to backup any solutions before opening them in Mide – just in case.

It made me laugh, actually. In a guilty kind of way. Rob nailed it, it’s true, and you know how I know? Because that bad code I was writing was kind of pretty much exactly my new black.

I wouldn’t argue that we need another web framework, but I would say that a web framework is a cool project to undertake to learn more about how these things work (and how to write them badly).

In the spirit of hacking, I figured I’d try and write a simple web framework that sits on top of all the goodness of ASP.NET. Not having to worry about dealing with the underlying HTTP fundamentals and also having ASP.NET Routing at my disposal, it seemed like a fun thing to do.

I’m writing about it here in case others are thinking of experimenting in a similar fashion, perhaps it may serve as motivation – if I can do it, trust me, you can do it better.

Tinyweb

So, with the single goal of making it as easy as possible to use, I have come up with Tinyweb (although, I can’t help but think that Black would have been a cooler name). And you know the cool thing about making your own framework? You can decide to do it how ever the hell you like, for instance:

To support dependency injection in the simplest way possible, the Tinyweb initialisation call optionally accepts an instance of a StructureMap registry and does the rest itself. Tinyweb also uses Spark for rendering views. Basically, it’s a little opinionated.

That said, you can still create a new IResult to render views using some other view engine, or supply your own version of the HandlerFactory to use another IOC container. Tinyweb hasn’t been locked into one specific way, it’s just my sensible default.

So, how does it work?

The workflow is as simple as I could think to make it. It’s important you understand that this means it could probably be much simpler. Here are the steps for creating a web app using Tinyweb:

• Create a public class WhateverYouLikeHereHandler with method(s) that match the name of the HTTP verb they respond to. For example, your SignupHandler might have a Get method that renders a view for user signup and a Post method that accepts the user registration data after the form is posted.
• Make a call to Tinyweb.Init from Application_Start

And, that’s it.

What about routes?

Oh yeah, routes. Routes are determined through the class name too. In the example above, the route to the handler is /Whatever/You/Like/Here. If I innocently created a RickRollHandler, it would be automatically configured to respond to the URL /Rick/Roll.

This is just a convention and can be modified by the creation of a Route field. If I want my RickRollHandler to be much more successful, I might do the following:

public class RickRollHandler
{
    Route route = new Route("Images/AnnaKournikova");

    public IResult Get()
    {
        return Result.Html("Muahahahah.html");
    }
}

Framework Design

Once Tinyweb has be initialised, it is aware of all URLs that the application serves and the type of handler that should be created for each one. Here’s what happens when some honest, innocent guy tries to request our image of Anna Kournikova:

• An IHandlerFactory is used to create an instance of the handler that has been associated with the URL being requested. If you haven’t set your own HandlerFactory, don’t panic, the DefaultHandlerFactory will be used – which uses Structure Map to create the handler. If you supplied a Registry to the Tinyweb.Init call, this could mean that the creation of the handler also involves the creation of any dependencies.
• An IHandlerInvoker is then used to call the correct method on the handler. If the request was an HTTP GET, the DefaultHandlerInvoker would be looking for a method called Get. The same goes for POST, PUT and DELETE. And again, if this makes you reach for the little foam stress duck on your desk with a panic of hand crunches, fear not, you can always create your own MyBatshitCrazyHandlerInvoker: IHandlerInvoker that uses star signs to call the right method.
• Lastly, the method being called on the handler must return an IResult back to the IHandlerInvoker. The IResult essentially just describes a class that must have a ProcessResult method, and some other dull things. Once the IResult is returned, the ProcessResult method is called to obtain the response, and naturally, this is then put on the response stream and sent back to the honest, innocent guy looking for naked pictures of women on the internet.

The only other bit is the scanning of handlers, which is performed during the Tinyweb.Init call. Handlers are those classes that end with the word Handler and have at least one method that corresponds to one of the four HTTP verbs.

Handlers are found by asking the current IHandlerScanner for them. You may be able to guess what I’m about to say next. If you want to customise (more likely optimise) the way that handlers are found, just create your own MyBatshitCrazyHandlerScanner and ask Tinyweb to use that instead. Despite the insanity of such a thing, it will oblige.

OK, I’m Interested

Together with the framework there are a couple of example applications demonstrating things like Spark view rendering and model binding. Feel free to browse around the project and I’d be happy to hear feedback.

There’s no binary release, as I expect the 2 people who care about this have VS2010/.NET4 and can compile it themselves, but if anyone wants to check it out and can’t, let me know and I’ll get a binary version up there too.

EDIT

There is now a binary release, so if you don’t want to compile it yourself you can pull down the latest build from the build server.

As children, we grow up believing that we should be right and that being wrong is a bad thing. If we are wrong, the other kids will laugh at us. If we are right, the other kids will think we’re smart and respect us (until the degree of geek – but that’s a whole other post). Pride and confidence become tangled up in a complex web, woven by the I could be wrong again spider.

For most of us, this isn’t something we grow out of. In fact, it gets worse. As adults we are expected to be right more often, and so it seems much worse to be wrong. This mindset quickly becomes prohibitive of doing anything that involves any risk of failure. We’ll stay on the fence of debates, we’ll only do things we have already done and we’ll only do new things in private or if there’s a low risk of failure.

I’ve wrote about this subject before when I asked Are You Failing Enough? and suggested that people learn just as much from failure as they do from success. Yet, sadly most people will avoid failure so relentlessly that they won’t do anything that could result in it.

We need to get out of the habit of caring who is right and who is wrong in a conversation. It really doesn’t matter. What matters is the learning and understanding coming from the conversation itself. Care about what you get out of the conversation.

If someone corrects you, they have taken their own time to ensure that you have grown in some way. They have invested their time into you and now you have that knowledge too. On the other hand, if you learn nothing from the conversations you engage in, you’re not growing nearly as much (and this is most likely because you’re not in the right mind to learn anything new, not necessarily because no one is able teach you something).

Accepting that you’re wrong or allowing someone to impart some knowledge is not a form of weakness, it’s very much the opposite. The one who grows from every conversation and improves by absorbing knowledge and wisdom from those around her is strong, and most able to grow stronger in the future. The one who argues the irrelevant points to gain some form of conversational victory is the weak one, and they’re missing the entire point of conversing in the first place.

When people take advantage of this, conversation is remarkably refreshing. For me, it’s just as refreshing as when I first discovered the agile method of software development. Put this into conversational terms and it kind of makes sense.

In a waterfall conversation, people try to be right upfront and aren’t typically adaptive if their opinions or understanding should be changed through being wrong. In a waterfall conversation, ideally, things said at the beginning of the conversation remain unchanged by the end.

In an agile conversation, people feel free to contribute ideas that could be wrong – using the fact that they’re wrong to drive the direction of the conversation and learn more about what they are discussing. An agile conversation iterates and people learn just as with software development.

Ultimately, the nature of a good debate is that people will disagree, but unless people want to listen and adjust their understanding (be agile in conversation), nothing will be learnt and we will just mindlessly argue.

Use the fact that you could be wrong as a tool for learning. Don’t worry about being right or being wrong, just focus on iterating the conversation and exchanging knowledge. In the end, if you end up being right about something, great – you have verified some knowledge. But more importantly, if you end up being wrong about something, even better – you have just learnt something, and that is the point.

Rather than the typical approach of creating and injecting a new mockable dependency, Harry’s example uses a public Func<> / Action<> on the controller that encapsulates the dependency and allows it to be overridden simply by assigning it a new delegate.

So, fast forward a few days I’m writing a test for the BugController’s DeleteBug method:

[HttpPost]
public ActionResult DeleteBug(int bugID)
{
    try
    {
        bugService.Delete(bugID);

        return Json(new
        {
            Succeeded = true,
            RedirectUrl = Url.Action("bugs", "project")
        });
    }
    catch (ModelValidationException exception)
    {
        return Json(exception.Description);
    }
}

Regardless of success or failure, the controller should return a JsonResult when deleting a bug. Seems like a straightforward test – let’s just make sure a JsonResult is always returned from the action:

[Test]
public void DeleteBug_WithValidBugID_ReturnsJsonResult()
{
    var bugService = new Mock<IBugService>();
    var controller = new BugController(bugService.Object); 

    var result = controller.DeleteBug(1); 

    Assert.IsInstanceOf<JsonResult>(result);
}

If only it was that simple.

Failed: System.NullReferenceException :
Object reference not set to an instance of an object.

The test is failing because of the dependency on Url.Action. When running under ASP.NET the controller is supplied with an instance, but during test it is null. In this particular case, the test doesn’t really care about what Url.Action is doing – we just need to prevent it from breaking the test.

So, rather than creating a wrapper around Url.Action and then injecting & mocking it, let’s see how Harry’s approach works. First we’re going to create a public Func<> to hold a delegate that will replace the dependency.

public class BugsController : Controller
{
    public Func<string, string, object, string> @UrlAction;

    ...
}

The reason for the somewhat redundant @ prefix is just to show the intent of this declaration more clearly. At a glance we can see that this is for testing and distinguish it from whatever else might be declared here.

Next, we need to modify the implementation slightly so that it uses the delegate instead of being coupled to Url.Action.

[HttpPost]
public ActionResult DeleteBug(int bugID)
{
    try
    {
        bugService.Delete(bugID);

        return Json(new
        {
            Succeeded = true,
            RedirectUrl = @UrlAction("bugs", "project", null)
        });
    }
    catch (ModelValidationException exception)
    {
        return Json(exception.Description);
    }
}

Almost there. We now need to ensure that the delegate gets a default instance that uses the original Url.Action. Cue constructor.

public BugsController(IBugService bugService)
{
    this.bugService = bugService;

    @UrlAction = (action, controller, routeValues) =>
    {
        return Url.Action(action, controller, routeValues);
    };
}

Action methods are now using @UrlAction instead of Url.Action and the dependency now exists in one single place. During test, we can change the behaviour of @UrlAction by assigning a new delegate to it, which gives us the same flexibility as if we had been forced to create a new interface and inject a new dependency.

Let’s see how we can make this test pass.

[Test]
public void DeleteBug_WithValidBugID_ReturnsJsonResult()
{
    var bugService = new Mock<IBugService>();
    var controller = new BugController(bugService.Object); 

    controller.@UrlAction = (action, controller, routes) =>
    {
        return "controller/action/route";
    };

    var result = controller.DeleteBug(1); 

    Assert.IsInstanceOf<JsonResult>(result);
}

We’re simply overwriting @UrlAction with a new delegate that returns a canned value, allowing the test to pass. It’s worth noting that a test setup would normally be used to make the test a little more quiet.

When you only have a few dependencies, I think this is a more elegant approach than creating wrappers and injecting them. Harry’s post goes deeper than this example shows, considering the problems that might occur if you have lots of these delegate dependencies – it’s worth a read.

There has been some positive progress in .NET land in terms of making concurrency easier. We know for certain that we don’t want to be responsible for creating threads ourselves anymore, so we now have the Task Parallel Library. The TPL also includes things like Parallel.For and Parallel.ForEach for magically converting our old decrepit loops into shiny new parallel ones.

I bet you’re wondering how much faster one of these shiny new parallel loops can count to 1,000,000 aren’t you? Truth be told, I’ve been listening to a dangerous amount of Tina Turner and I’m in a good mood, so I’ll indulge you. Let’s do it the old decrepit way first (so we can compare).

var timer = new Stopwatch();
timer.Start();

var countedTo = 0L;

foreach (var number in Enumerable.Range(1, 1000000))
{
    ++countedTo;
}

timer.Stop();
Console.WriteLine("Counted to {0} in {1} ms", countedTo, timer.ElapsedMilliseconds);

It took a mere 11 milliseconds to count to 1,000,000.

Let’s create the parallel version. I’m terribly excited – it’s going to absolutely smash 11 ms.

var timer = new Stopwatch();
timer.Start();

var countedTo = 0L;

Parallel.ForEach(Enumerable.Range(1, 1000000), n =>
{
    ++countedTo;
});

timer.Stop();
Console.WriteLine("Counted to {0} in {1} ms", countedTo, timer.ElapsedMilliseconds);

I’m on the edge of my chair. I didn’t even have to write any thread related code and I’m about to parallelise this beauty into a concurrent masterpiece. Here we go, are you ready?

Holy crap! What the hell! 116 milliseconds, are you kidding? 959,028? It hasn’t even counted to the end, there must be a bug in the framework.

*Deep Breath*, *Deep Breath*

There’s got to be a logical explanation. It couldn’t have crashed before counting to the end, or it would have never reached the Console.WriteLine, right? countedTo holds a value less than 1,000,000, which must mean that the statement ++countedTo was only successfully executed 959,028 times. It also took 10 times longer to run, which must mean it was doing 10 times more work.

Explanation

So, it turns out Parallel.ForEach isn’t a silver bullet, and was never meant to be. Parallel.ForEach is not an abstraction, it’s simply a way of making what is already possible easier. That in itself doesn’t remove the other complexities surrounding concurrency.

Let’s try and make sense of why we have those results.

First off, the count is way off. The reason for this is quite simple once you’re aware of it. A statement such as ++var is not atomic. An executing thread isn’t running your C# code, it’s running the machine instructions produced by your C# code. In this example, ++var is at least three separate machine instructions, which can be interrupted at any point. The statement looks something like this to the CPU:

mov eax, dword ptr [countedTo]
add eax, 1
mov dword ptr [countedTo], eax

Given that there’s only one version of eax, consider what will happen if the first thread only manages to execute the first instruction before being interrupted by the second thread which completes all three. If you’re thinking that upon the return of the first thread, the change made by the second thread will be destroyed, you’d be right. Code running inside a thread must be thread safe, irrespective of which fancy library you used to create the thread.

That explains why the count was way off, but why did it take 10 times longer? Wasn’t this thing in parallel damnit? It’s important to remember that parallel doesn’t imply quicker, though in lots of cases it’s a vehicle for making an algorithm execute faster. Not everything can be parallelised, and even things that can be sometimes won’t benefit from the increased overhead of a parallel solution.

The problem here (besides the concurrency issue) is also one of overhead. The C# compiler is firstly having to create a closure over the countedTo variable in order to allow instances of the thread delegate to access it. Additionally, instead of having just three instructions to increment the count, we have all the additional instructions for managing the thread. In the end, it turns out it is actually doing 10 times more work.

Solution

The solution is to synchronise the executing threads, making sure that only one thread can execute the non-thread safe code. Typically we’ll use a form of locking for this, and in fact the .NET framework allows you to use the lock keyword for this very purpose. Here’s how you’d correct the previous example:

var timer = new Stopwatch();
timer.Start();

var countedTo = 0L;
var lockObject = new object();

Parallel.ForEach(Enumerable.Range(1, 1000000), n =>
{
    lock (lockObject)
    {
        ++countedTo;
    }
});

timer.Stop();
Console.WriteLine("Counted to {0} in {1} ms", countedTo, timer.ElapsedMilliseconds);

We’re now using an instance of System.Object to lock on, ensuring that only one thread can execute the increment at any one time. Of course, this now creates even more overhead (for such a simple operation to start with) causing it to take even longer:

Conclusion

Parallel.For and Parallel.ForEach might look like silver bullets that will magically allow you to speed up a loop by making it execute in parallel, but this isn’t the case at all. Parallel doesn’t automatically mean performance improvement. It largely depends on whether the task is inherently parallelisable and the overhead involved in achieving it.

You can’t simply change a foreach loop into a Parallel.ForEach loop without thinking about concurrency issues. Neither of these methods will make your code thread safe, only you can do that.

They weren’t kidding, concurrency isn’t a simple problem to solve.

The one I remember is the story of Dave, who had recently discovered the power of document.write and took it a little too far. Why have the server do all the work when the client can do it instead? Dave decided to have the server response.write a metric ton of document.write statements which would then produce the page at runtime in the browser. It’s possible he may have been thinking too hard about what David Wheeler said about indirection.

Back when JavaScript in the browser made people as nervous as a small nun at a penguin shooting, this story was pretty funny. But with the advances of in-browser JavaScript since the days of DHTML and the widespread popularity of libraries like jQuery, perhaps (and I may be giving him too much credit here) Dave was just ahead of his time.

When it comes to rendering, either the server does it in full, the server does most of it and the client helps out, or the client does it in full (with the exception of the initial HTML document sent down on the first request). I carefully ordered these options to reflect the trend in the way web applications seem to be moving.

Go back 10 years and it was unheard of for a web application to be client-centric, where most of the rendering was done by JavaScript in the browser. They weren’t even called web applications, they were web sites. Fast forward to today and you see more and more involvement by the client as we start to realise the benefits of client rendering. Due to the lack of acronyms at the time, we also gave the idea a new name Ajax.

But why do we want the client to be responsible for rendering? While it’s easier to have the server to do it, the client has a few advantages over the server. The client can render things faster because it doesn’t require a round trip back to the server to get the content. The reduction in round trips also means less data is sent and received.

But what price do we pay for rendering content more quickly and reducing the amount of data sent/received? If it was up to Dave it would be a pretty high one, but fortunately things have changed since document.write. Let’s do an experiment to see how the rendering of content might evolve from server to client.

The Application

Let’s build a really simple To Do application that will list our current items and allow us to submit new ones.

Server Rendering

We’ll start the experiment by creating the server-rendered version. A plain old <form> will post new items to the server and we’ll use the post/redirect/get pattern to redirect the browser back to the page that shows the current list of submissions.

First up, we’ve got the controller:

public class TodoController : Controller
{
    public ActionResult Index()
    {
        return View(Database.GetAll());
    }

    [HttpPost]
    public ActionResult Index(string task)
    {
        Database.Add(new Todo() { Task = task, Created = DateTime.Now });
        return RedirectToAction("Index");
    }
}

We are using an in-memory database to hold the current list of submissions. When the client posts a new todo item we add it to the database and then redirect back to the action that displays the current list:

<ul>

<% foreach (var item in Model) { %>

     <li>
         <b><%= item.Created.ToShortTimeString() %></b> <%= item.Task %>
     </li>

<% } %>

</ul>

<% using (Html.BeginForm()) { %>

     <input name="task" />
     <input type="submit" value="Add ToDo" />

<% } %>

And it comes to life:

Let’s record some numbers so we can measure any changes in performance with later versions. Firstly, let’s see how many bytes are being received for the initial page load. We’ll then submit three new items and see what happens.

The first request shows the initial page load of 763 bytes. We then see 3 blocks of post/redirect/get in which the browser downloads 841 bytes, then 919 bytes and finally 997 bytes (the constant increase of 78 bytes is because the three todo items posted were exactly the same length). In the end, posting 3 new todo items resulted in the client downloading a total of 3,520 bytes and making 3 roundtrips to the server for rendering.

Client Rendering

Redirecting right after the POST allowed us to put the client back into a consistent state with the new data. If the client is to handle rendering, the client needs to know how to produce this new UI state too. In addition to rendering, the client also needs to be able to asynchronously update the server with new data and be able to request the set of existing data. It’s a hard life being the client.

The first thing we need to do to support updates from the client asynchronously is remove the redirect from the POST action (since the client won’t redirecting anymore). We’ll also need a new action for returning the current set of todo items, allowing the client to update the UI on the first request and any time afterwards.

public class TodoController : Controller
{
    public ActionResult Index()
    {
        return View();
    }

    public JsonResult GetAll()
    {
        return Json(Database.GetAll(), JsonRequestBehavior.AllowGet);
    }

    [HttpPost]
    public void Add(string task)
    {
        Database.Add(new Todo() { Task = task, Created = DateTime.Now });
    }
}

Now that the controller is set up for asynchronous requests from the client, we need to modify the view to support client rendering. The first thing we’ll do is remove the server tags from the previous example, since the client will be creating that content. Similarly we won’t need the form either.

<ul></ul>

<input id="task" name="task" />
<input id="submitButton" type="submit" value="Add ToDo" />

The view got a lot smaller, but we’re not done yet. Let’s use jQuery to add a page load handler which will request the current list of todo items and add them to the empty <ul>.

<script type="text/javascript">

    $(function () {
        $.getJSON("/Todo/GetAll", function (items) {
            $(items).each(function () {
                $("ul").append("<li><b>" + this.Created + "</b> " + this.Task + "</li>");
            });
        });
    });

</script>

That should cover the rendering part, but we also need to handle submitting new items. Let’s add a handler to the submit button that reads the value and posts it back to the server.

<script type="text/javascript">

    $(function () {
        $.getJSON("/Todo/GetAll", function (items) {
            $(items).each(function () {
                $("ul").append("<li><b>" + this.Created + "</b> " + this.Task + "</li>");
            });
        });

        $("#submitButton").click(function () {
            $.post("/Todo/Add", { Task: $("#task").val() }, function () {
                // todo (no pun intended)
            });
        });
    });

</script>

We can now post a new todo item to the server, but what about the client state? We have a couple of options here. We could extract just the code from line 6 into a new function and have the client add an <li> when it posts the new todo, or we could extract the code from line 4 to line 8 and have the client re-render the entire list when it posts the new todo (if the new item caused all the others to change for example). In this particular case the former option suits us best, so let’s do that.

<script type="text/javascript">

    $(function () {
        $.getJSON("/Todo/GetAll", function (items) {
            $(items).each(function () {
                insertTodo(this);
            });
        });

        $("#submitButton").click(function () {
            var todo = { Task: $("#task").val(), Created: "Just Now" };
            $.post("/Todo/Add", todo, function () {
                insertTodo(todo);
            });
        });
    });

    function insertTodo(toDo) {
        $("ul").append("<li><b>" + toDo.Created + "</b> " + toDo.Task + "</li>");
    }

</script>

And we’re done. The client now only sends and receives the data it needs and benefits from the much faster rendering (with the exception of the first page load).

And here’s how the raw requests look:

The first request is now considerably larger than before because it contains the JavaScript client rendering code, but looking at the other requests we see that the server sent down 1,373 bytes in total (39% of the server-rendered version).

Unlike the server-rendered version, there was no need for a GET after each of the three POST requests, saving the server 3 rendering jobs and the bandwidth needed to send that data back. There is also the benefit of instant feedback to the client, since it’s not having to wait for the server to render the results.

What’s The Cost?

Simplicity has been traded off for responsiveness and bandwidth. Letting the server handle rendering was easier to understand and contained less moving parts, while on the other hand, letting the client handle rendering allowed for a leaner application which put less load on the server and resulted in a lightning fast experience for the user.

You may be thinking but do I want the simple solution, or the solution that is lightning fast? The question I have is how can we have both?

Where’s The Complexity?

When the controller was modified to support the asynchronous client, it didn’t really become any more complex. In fact, I think I prefer it in its current state – it now looks like a basic data access API. However, when we changed the view (by introducing the JavaScript) it became considerably more complex. So what’s making the view more complex and how can we solve it?

Originally I thought well, of course, it’s all the jQuery, but when I thought about it a little more I realised it’s not jQuery that is introducing the complexity for client rendering – that has been there all along. If anything, jQuery is making it easier than it would have been otherwise. The problem is the level of indirection that we are working at in the current solution.

Manually adding, editing and removing lots of individual elements of the DOM is akin to when we used to declare a pointer, ask for some memory, copy a value into it and then make sure it was correctly terminated in order to store a string; it’s too low level and fiddly. We need another layer of indirection.

Templating

Rather than getting down and dirty with the DOM, I think I’d much rather create an association between a data model and a visual template. When the data model is modified, either through something being added, removed or changed, the visual template should simply be able to re-render itself to reflect those changes.

JavaScript templating is a relatively new area of experimentation, but there are still a number of options. We’ll use the jQuery templating library jquery-tmpl for this example. Let’s replace the manual DOM manipulation code with templating:

<ul></ul>

<input id="task" name="task" />
<input id="submitButton" type="submit" value="Add ToDo" />

<script id="todoTemplate" type="text/html">

    <li><b>${Created}</b> ${Task}</li>

</script>

<script type="text/javascript">

    var model;

    $(function() {
        model = {
            data: <%= new JavaScriptSerializer().Serialize(Model) %>,
            add: function() {
                var todo = { Task: $("#task").val(), Created: "Just Now" };
                $.post("/Todo/Add", todo, function() {
                    model.data.push(todo);
                    model.render();
                });
            },
            render: function() {
                $("ul").html("");
                $("#todoTemplate").render(model.data).appendTo("ul");
            }
        };

        $("#submitButton").click(function() {
            model.add();
        });

        model.render();
    });

</script>

The initial mark-up is unchanged. We still have the empty list and the two inputs for adding new todo items. Starting on line 6 we create the client-side template that will be used to render the data.

The biggest change is the script. We’re creating the model on line 17 and supplying the initial set of data from the server (meaning we save a request and don’t need the getAll method). Notice how there is no jQuery code to manually add DOM elements now. Instead the item is added to the model and the template is simply re-rendered.

Can This Be Improved?

There is a definite improvement when we compare the current version with the original client-rendered version. We are no longer having to write code to manually create individual elements as we’re using a template to keep that in one place. Because the template is rendered directly from the model, adding, editing and removing items all share the same rendering logic (which saves lots of manual DOM manipulation).

However, when it comes to adding a new item, we’re still having to write code to read the value from the UI, add it to the model and tell the template to re-render itself. Another problem is that the data is bound only one way. If the todo items were editable, modifying one of them would not update the underlying model.

How can we go one step further?

JavaScript With Observers

At the moment the solution can be thought of as a pull-based system. That is, when something changes we pull the new values from the UI and update the model data ourselves. But what if the idea was reversed – what if, when a value changed, our model knew about that change immediately because the new value was pushed into it? Well, it would mean we didn’t need to write pulling code anymore (reading from the DOM manually). Ideally, we wouldn’t even need to tell the template to re-render itself. Best of all we could write less code.

A number of libraries are already emerging that support this observable pattern of building rich client applications in the browser. Recently Steve Sanderson announced his own library, Knockout. Taken from his introductory post:

Knockout is an open-source JavaScript library that makes it easier to create rich, desktop-like user interfaces with JavaScript and HTML, using observers to make your UI automatically stay in sync with an underlying data model. It works particularly well with the MVVM pattern, offering declarative bindings somewhat like Silverlight but without the browser plugin.

From the short amount of time I’ve had to look at Knockout, I have to say that it’s pretty awesome. There’s no point in paraphrasing what Steve has already said, so I urge you to go read his blog post about it and see for yourself.

Back to the problem at hand, how does Knockout help? Let’s identify the problems with the current solution:

• The add function is concerned with locating and reading the new todo data directly from the UI; it’s coupled to the presentation.
• The very fact we need a render method isn’t good – why should we need one? It would be better if the template re-rendered itself automatically when the model data changed.
• Let’s say we add a new feature where all current todo items are made editable. We’re then going to have to write more code to pull those values back into the model when they are modified.

How does Knockout solve these problems?

The add function no longer needs to be concerned with locating the new data, instead it will be pushed into an observable within the view model through Knockout’s various bindings. Say goodbye to the render method too, we won’t be needing that – templates are automatically re-rendered when Knockout detects that the observable they are associated with has been modified. Finally, if we make the todo items editable, Knockout’s two-way binding means that any changes we make in the UI will automagically end up back in the model. Similarly, if we change the model data (perhaps we have a background timer that is updating from the server) the UI will reflect those changes without us having to write a single additional line of code.

Here’s a Knockout version (pun intended):

<ul data-bind="template: { name: 'todoTemplate', foreach: todos }"></ul>

<input data-bind="value: newTodo" />
<input data-bind="click: addTodo" type="submit" value="Add ToDo" />

<script id="todoTemplate" type="text/html">

    <li><b>${Created}</b> ${Task}</li>

</script>

<script type="text/javascript">

    $(function() {
        var model = {
            todos: ko.observableArray(<%= new JavaScriptSerializer().Serialize(Model) %>),
            newTodo: ko.observable(""),
            addTodo: function () {
                this.todos.push({ Task: this.newTodo(), Created: "Just Now" });
                $.post("/Todo/Add", { Task: this.newTodo() });
            }
        };

        ko.applyBindings(document.body, model);
    });

</script>

You’ll notice that the <input> and <ul> elements now have data-bind attributes. The data-bind attribute tells Knockout how the element interacts with the view model. In the case of the <ul> element, the data-bind attribute is specifying that it is bound to each item of the collection named todos and that each item should be rendered using the template named todoTemplate.

The first <input> element has a value binding that links the value of the element with the observable named newTodo. When a new value is entered into the <input>, it is also pushed into the observable. The second <input> element has a click binding that links it to the addTodo function in the view model.

The script has been reduced even further and now only contains the declaration of a view model and a call to the applyBindings method. Notice how the todos collection and the newTodo field are observables. Observables are key to allowing Knockout to push changing values in the UI back into the model and propagate changes in the model back to the UI.

Conclusion

We’ve seen how a simple todo application has gone from being rendered on the server to being rendered on the client. Moving the rendering down to the client has some advantages, such as a snappier user experience and less overhead in terms of bandwidth/reducing requests (post/redirect/get).

Moving logic onto the client also introduced some additional problems, such as having to be concerned with updating the client UI state independently of the server. However, as we refined the solution we were able to swap out manual DOM manipulation and state coupled with UI elements for a more decoupled solution through the use of the Knockout library. Knockout bridges the gap between the UI and the data model by keeping the two cleanly separated while still allowing a high degree of interactivity between the two through observable collections and various UI bindings.

In the end, the client solution was clean and pretty straightforward, making a good case for future situations where building some functionality on the client would be desirable, but would have otherwise been avoided because of the complexity of interacting with the DOM (in both directions).

As support for JavaScript explodes in the browser, more and more opportunities are emerging for cool things to be done on the client with the same compatibility you’d get from the server-based alternatives. We’re in an exciting time where we’ll see people really pushing to get the most out of the client, rather than just using it as a viewer for content rendered only by the server.

Getting back to the underlying question, was Dave really a genius? In order to accurately and fairly answer the question, I consulted a magic 8 ball. The answer: don’t count on it.

As it is being said, I detect the whatever works attitude emanating from the person saying it. No concept of continuous improvement. No interest in reflecting. Not even 60 seconds invested to consider whether the process is efficient or could be improved. It most cases it’s almost a canned response to any comment referring to the efficiency of a process that is considered to be working.

Maybe the process breaks once per month, causing Fred to stop what he’s doing (see Gerald Weinberg’s rule of thumb) and fix it. But, who cares, it works, and Fred doesn’t mind. Paper-based filing systems, typewriters and horse and cart worked but this didn’t exclude them all from being significantly improved by someone with the right mindset.

Applying the if it isn’t broken, don’t fix it mentality to everything is naïve; you end up with lots of suboptimal processes. Based on the fact that you never get it right the first time, processes need to evolve, and for this to happen a culture of reflection and improvement must exist.

To consider something to be either working or broken is a simple model which doesn’t leave much room for improvement. Considering the degree to which something is working is a better model that puts your mind in the right place. How reliable is the process? Can it execute quicker? Can the execution cost be reduced? We need to think about quality, not just if by some vague definition the process can be considered to be working.

I recently finished reading The Toyota Way. In the book, Jeffrey Liker explains the management philosophy behind Toyota. Interestingly, one of the principles within Toyota is to “build a culture of stopping to fix problems, to get quality right the first time”. Liker goes on to explain the apparent productivity paradox:

Toyota management say that it’s OK to run at less than 100% of the time, even when it’s possible to run full time, yet Toyota is regularly ranked amongst the most productive plants in the auto industry. Why?

Investing time and effort into quality from the start sounds like the slower and more expensive method to most people. Let’s just get something working and improve it later. The problem is, too many people don’t improve it later. The If it isn’t broken, don’t fix it syndrome starts instead. Liker explains how Toyota does it:

Because Toyota learned long ago that solving quality problems at the source saves time and money downstream. By continually surfacing problems and fixing them as they occur, you eliminate waste, your productivity soars and competitors who are running assembly lines flat-out and letting problems accumulate get left in the dust.

The issue of letting quality problems accumulate isn’t exclusive to the auto industry. In the software industry it results in poorly written systems being built on top of other poorly written systems that, while completed sooner than a higher quality system might have been, require increasing amounts of human attention as the accumulation of quality problems becomes too big to ignore; too big to be considered working. Needless to say, the cost of running these systems starts to increase too.

So from now on, if it isn’t broken, don’t fix it is banned. Stop using it. It makes you sound like you don’t care even enough to look for improvement. Things are not broken or working; they are broken or working to a certain degree and may be exposing opportunities to be improved and have their business value increased. It’s also a mistake to assume that business value can’t be increased from existing work (or processes) rather than business value just coming from new work.

You can be the one who thoughtfully creates work to a high standard, always looking to improve yourself and increase the business value in suboptimal existing work. Alternatively, be the one who doesn’t care enough to even look for improvement opportunities and would rather just churn out first versions and move on – leaving a legacy of low quality behind you. It’s your choice.

If it isn’t broken, fix it anyway.

Well, it started out fun. Pretty quickly you’d realise that using sockets for IPC sucks much more quickly than you expected. For starters, you didn’t have any kind of protocol between the two processes so you’d invent your own. You would do horrible things like receiving a length-prefixed string over the socket and doing a switch statement to determine which method should be called.

It’s likely that designing a socket protocol so that one process can effectively call a method in another process is not the kind of problem you intended to spend your time solving. Fortunately we now have solid frameworks that handle this lower level stuff for us and let us focus on defining what the methods we’ll be calling across process (or indeed across the internet) actually do.

Enter WCF

The Windows Communication Foundation is Microsoft’s offering to us .NET folks for building service-oriented applications. For those of you who aren’t familiar with the concept of service-oriented architecture, think of it like this: instead of building your business logic as a set of classes in an assembly, we build them as a set of independent services that we make available as an API (just like a twitter client does its work via the twitter API).

The first time I heard about SOA, I thought it was just a big grand enterprise-only thing and never considered it relevant to the tiny little applications I was building. However, it turns out that thinking of your classes as services is a powerful concept that is applicable in lots of situations. I now use a service architecture to allow javascript to talk to the web application and to allow the web application to talk to windows services.

Some even suggest that every class should be a WCF service, and indeed why shouldn’t a class have a platform-independent endpoint that allows anyone to call it?

WCF Basics

A WCF service is primarily made up of two parts. First is the service contract, which is just an interface that specifies which methods are available in the service. Second is the service implementation class that implements the service contract interface. Talk is cheap. Show me the code.

Let’s create a WCF service for telling jokes. First we’ll create the service contract (the interface).

[ServiceContract]
public interface IJokeService
{
    [OperationContract]
    string GetLawyerJoke();

    [OperationContract]
    string GetRandomJoke();
}

Notice the [ServiceContract] attribute denoting that the interface is a WCF service contract and the [OperationContract] attributes on each method indicating that the method will be available to clients. If you leave out an [OperationContract] attribute, the method won’t be available over the service.

So let’s create an implementation of the service.

public class JokeService : IJokeService
{
    public string GetLawyerJoke()
    {
        return "Why did God make snakes before lawyers? To practice.";
    }

    public string GetRandomJoke()
    {
        return "Where do you find a one legged dog? Where you left it.";
    }
}

You loled, admit it. We’ve now created a service contract and implemented that contract with our JokeService. But how does someone actually use the service?

Hosting WCF Services

The next step in building our WCF service is to make it available to clients by hosting it. There are various options for hosting WCF services, including hosting them in IIS and self-hosting them within the application domain (which is particularly useful for things like IPC). For the purpose of this simple example, we’ll see how to self-host the service in a basic console application.

First let’s create a new console application and add our WCF service to it.

Self-hosting the service is made possible by the ServiceHost class. The theory goes like this: create an instance of the ServiceHost class, add an endpoint to it and finally open it. Let’s see how that’s done.

class Program
{
    static void Main(string[] args)
    {
        ServiceHost serviceHost = new ServiceHost(typeof(JokeService), new Uri[] { new Uri("http://localhost:4242") });
        serviceHost.AddServiceEndpoint(typeof(IJokeService), new BasicHttpBinding(), "JokeService");
        serviceHost.Open();

        Console.ReadKey();
        serviceHost.Close();
    }
}

On line 5 we create a ServiceHost for the JokeService and specify that the base address of the service will be located at http://localhost:4242. On line 6 we add an HTTP endpoint to the ServiceHost which makes the IJokeService contract available over HTTP at the address http://localhost:4242/JokeService. Finally, on line 7 the service is opened and available to clients.

Consuming WCF Services

Now that we have a self-hosted WCF service, let’s see how a client can interact with it. There are two situations worth considering in terms of the client. The client may be an external third party and have access to nothing more than the URL of the service. On the other hand, the client may be another process that has access to the service contract interface.

In the case of a local client (one with access to the contract interface), the service can be called without consuming the metadata and automatically building calling code via the svcutil.exe utility. We’ll see how to do this in a second. Where the client is an external third party, the service must expose its metadata so that the third party knows how to interact with the service. We’ll see how to achieve this too.

Consuming Local WCF Services

Let’s build another console application for consuming the JokeService. For the sake of simplicity, we’ll also copy the WCF service contract into this project (in reality it’s more likely the contract would be built into some shared assembly that you’d reference instead).

Because we have access to the IJokeService contract, we can ask the lovely ChannelFactory class to create a channel that lets us access the service by its known endpoint address and binding.

class Program
{
    static void Main(string[] args)
    {
        ChannelFactory<IJokeService> factory = new ChannelFactory<IJokeService>();
        factory.Endpoint.Binding = new BasicHttpBinding();
        factory.Endpoint.Address = new EndpointAddress("http://localhost:4242/JokeService");

        IJokeService jokeService = factory.CreateChannel();

        Console.WriteLine(jokeService.GetLawyerJoke());
        Console.WriteLine(jokeService.GetRandomJoke());
    }
}

And as long as our WCF service host application is running, we get the following output.

I don’t know about you, but I certainly prefer this to writing my own socket protocol. So, what if we don’t have access to the service contract?

Consuming Remote WCF Services

It may be the case that we’re offering our service to a third party and they don’t have access to our code in order to use the ChannelFactory approach. In these situations we have to make available the service metadata so that third parties can use utilities such as svcutil.exe to query it and scaffold client code.

Unlike ASMX web services, WCF services don’t make their metadata available by default. Fortunately, it’s pretty easy to add an additional endpoint that offers metadata and that’s what we’re going to do now. As a quick reminder, here’s our service hosting code from earlier.

class Program
{
    static void Main(string[] args)
    {
        ServiceHost serviceHost = new ServiceHost(typeof(JokeService), new Uri[] { new Uri("http://localhost:4242") });
        serviceHost.AddServiceEndpoint(typeof(IJokeService), new BasicHttpBinding(), "JokeService");
        serviceHost.Open();

        Console.ReadKey();
        serviceHost.Close();
    }
}

Between lines 6 and 7 we’re going to add a new endpoint for mex (metadata exchange). But before we can add a mex endpoint we also need to add a service behaviour so that clients can issue an HTTP GET to request the service metadata.

class Program
{
    static void Main(string[] args)
    {
        ServiceHost serviceHost = new ServiceHost(typeof(JokeService), new Uri[] { new Uri("http://localhost:4242") });
        serviceHost.AddServiceEndpoint(typeof(IJokeService), new BasicHttpBinding(), "JokeService");

        serviceHost.Description.Behaviors.Add(new ServiceMetadataBehavior()
        {
            HttpGetEnabled = true
        });

        serviceHost.AddServiceEndpoint(ServiceMetadataBehavior.MexContractName, MetadataExchangeBindings.CreateMexHttpBinding(), "mex");
        serviceHost.Open();

        Console.ReadKey();
        serviceHost.Close();
    }
}

The WCF service is now configured to allow its metadata to be retrieved by clients. If we browse to the service URL in a web browser we see the following:

WCF is helpfully telling us that clients may use the svcutil.exe utility to generate calling code. So let’s modify our original console application to use the metadata to generate code rather than using the ChannelFactory. Firstly we’ll delete the reference to the service contract (as we should get everything from the service metadata now) and we’ll delete all the ChannelFactory code too.

While we can use svcutil.exe to generate the client code, we can also use the Add Service Reference option from Visual Studio too. Both do the same thing.

I’m not sure it could get much easier than this without Visual Studio having some kind of mind reading functionality in the next release. Anyway, we’re now asked where the service is located.

Don’t forget, the service host application must still be running for Visual Studio to find it and generate the client code. It looks like the service was found, so let’s add that to the project. In whichever namespace you chose, you should now have a JokeServiceClient that was built from the service’s metadata. Here’s what the new client looks like.

class Program
{
    static void Main(string[] args)
    {
        JokeServiceClient jokeService = new JokeServiceClient();

        Console.WriteLine(jokeService.GetLawyerJoke());
        Console.WriteLine(jokeService.GetRandomJoke());
    }
}

The Recapitulation

In this simple introduction we’ve seen how to create a WCF service and self-host it in a console application. WCF services can also be hosted in IIS as well as within other application types (WPF/Windows Services/WinForms) making them ideal for IPC.

Consuming a WCF service is also relatively easy, even if you’re a third party without access to the binary service contract. We saw how to manually call the service with the help of the WCF ChannelFactory. We also saw how to enable metadata exchange (mex) to allow third parties to interface with our service.

WCF goes much deeper than this simple overview demonstrates, allowing you to control fine-grained aspects of your service such instancing, security, concurrency and transactions and in that regard WCF is a much better solution for service-oriented applications than something like ASMX.

It’s worth noting that the configuration of a WCF service can also be specified in the application’s configuration file. Examples in this post have configured the service programmatically in an attempt to better explain what’s involved in creating and consuming WCF services.