No further development on Simple.Web

I’ve let this little fact out on Twitter, so here’s a little more detail on why I’m not going to be working on Simple.Web any more.

Original motivation

Whenever people asked why I wrote Simple.Web, I would reply “because Microsoft broke Web API”. Eventually, at an MVP Summit, Scott Hanselman had me stand in front of the Web API development team and explain what it was that they had broken, which was… awkward.

I started writing Zudio when Web API was still “WCF Web API”, being developed by Glenn Block. I think I was using version 0.6. The project had gone quiet, then suddenly re-emerged as ASP.NET Web API 1.0 beta. I switched to the new framework, and everything broke. They’d changed the way IoC/DI worked, they’d added an ApiController base class, and they’d taken out the attribute-based routing, which I’d been a huge fan of.

Here’s the thing about routing. When I create an API, web or otherwise, it is rarely of the type popularised by Ruby on Rails, ASP.NET MVC and most other MVC frameworks. These tend to think of an API as simple resources with HTTP methods – two GETs, a POST, a PUT and a DELETE. That’s not an API. That’s just a basic Data Access Layer over HTTP. Sure, I’ve written code where that is a valid pattern for certain resources, but it’s not an API. An API provides high-level commands and operations, such as “activate this user” or “complete this order”.

The ASP.NET Web API 1.0 release offered the same routing as ASP.NET MVC – “{controller}/{action}/{id}” – and if you wanted anything more complicated, you had to manipulate the routing table directly.

So, I took all the things that I had liked about WCF Web API and put them into Simple.Web. I also added a feature of my own, inspired by a talk I’d seen that week about “Hypermedia As The Engine Of Application State”, where the serialization process would include collections of links so that API consumers didn’t have to hard-code URLs.

Simple.Web also removed the distinction between Views and other types of result, honoured Accept headers, promoted a “Single-Action Controller” pattern, and had a completely asynchronous pipeline.

What’s changed?

Well for a start, Web API 2 has attribute based routing. And it’s got a class-level RoutePrefix attribute that lets you apply routing to a controller; if you then just have a single method (say, “Get”) with an empty Route parameter, you’ve essentially got Simple.Web’s Single-Action Controller pattern.

Web API also has a comprehensive set of hooks and providers and what-have-you that mean you can extend or modify any functionality you like (or don’t like). So the couple of tricks that Simple.Web did, like the link generation, are easy to add in.

And then there’s OWIN, which allows you to integrate functionality into your Web API application at the pipeline level without faffing around with System.Web HttpModules and the like.

Also, Microsoft have changed. Certainly DevDiv. There’s a bunch of awesome people working there, who have been pushing hard for open source ideals across the entire stack, and it’s working. Most of the ASP.NET stack – certainly all the bits I care about – are now developed in the open, and ASP.NET vNext is on GitHub, and accepting pull requests.

ASP.NET vNext was the real trigger, in the end. I am incredibly excited about what’s going on there. A completely new, very lightweight CLR, a modularised base class library distributed via NuGet (just like I asked for), and MVC and Web API combined into a single, cohesive framework. With, incidentally, a fully asynchronous pipeline.

(David Fowler and Damien Edwards were in my Simple.Web talk at NDC London last year. Just sayin’.)

Simple.Web scratched an itch that I had. There is fundamentally no point continuing to scratch an itch that doesn’t itch any more, especially when there’s an over-the-counter cream [metaphor terminated due to potential taste boundary violation].

Seriously, though, I’ve got limited time, and when a mainstream product does everything I need, the way I want it, then I should spend that time creating value instead of replicating other people’s efforts*.

What now, then?

Well, I’m migrating Zudio over to MVC 5.2 & Web API 2.2, which is actually much easier than I expected, and I’ll upgrade that to vNext as soon as there’s a stable release with good performance that I can confidently run on Azure Web Sites.

My AngularJS client-side code relies heavily on the hypermedia links that Simple.Web generates, so I’ve implemented that part of Simple.Web as a Web API extension called Linky, which is on GitHub now and NuGet soon. As and when I find other gaps in Web API or MVC, I will fill them with more extensions. It is my fond hope that simple extensions to the canonical frameworks might be more useful to the wider community than full-blown alternatives.

I will also be doing some blogging (on my coming-soon new blog) about Web API extensions I’ve written that are specific to my project, but where the patterns are broadly applicable.

Finally, I can get back to working on Simple.Data v2 (assuming that Entity Framework v7 isn’t going to add dynamic method-name-based operations).

*PostScript

Just to be clear, this doesn’t mean that I think all alternative web frameworks are a waste of time. Those that offer a completely different approach and philosophy, such as Nancy, obviously bring much-needed innovation and value to the .NET ecosystem. It’s just that Simple.Web doesn’t any more.

Hidden Complexity

This coming Monday at Skills Matter in London, I’ll be giving my new talk, Hidden Complexity: Inside Simple.Data and Simple.Web for the first time. In October, I’ll be presenting it at Dev Day in Krakow and Leetspeak in Malmo as well.

Simple.Data and Simple.Web are like the proverbial duck: on the surface, everything is clean and calm and simple, but underneath, there’s a whole lot going on. There’s some runtime code generation using System.Linq.Expressions; in the case of Simple.Data, there’s a lot of dynamic stuff going on; in Simple.Web, I’ve built a whole asynchronous pipeline on top of Tasks; and there are some downright abuses of the C# language in there for good measure.

In the course of writing these things, I’ve learned a hell of a lot, sometimes from trial and error, and sometimes from gurus like Jon Skeet (mainly abuses of C#) and Bill Wagner (mainly code generation), so this talk is my attempt to share some of that acquired knowledge. It might not be that useful in day-to-day programming – I certainly don’t use most of it on a regular basis – but I hope at the very least it will be an interesting and entertaining look at how fun code can get when you step off the well-trodden paths and into the backwoods of C# and .NET programming.

I’m on the look-out for more opportunities to present this one, so if you run a user group or have an event planned where this might fit in, please get in touch.

Simple.Web and Nancy

Several people have asked me what the difference is between Simple.Web and Nancy, so I’m going to try and outline it here, and share some more of my motivation for writing Simple.Web in the first place.

Incentive

To start with, I don’t think there’s anything wrong with Nancy; I have a huge amount of respect for what Andreas and Steven have done and continue to do. It’s a great framework, and I’m really not setting out to compete with it. The thing is, they have their own roadmap and priorities, and I needed some things right away for my new project (which will be launching in the next couple of days; watch this space). Those things are not trivial, and I wouldn’t know where to start contributing them to that project.

With Nancy out of the running, my plan was to use ASP.NET MVC 4 and what was, at the time, WCF Web API. Those supported the two key features I want: async support in both, and content negotiation in WCF Web API. But in the transition from the WCF moniker to ASP.NET, Web API changed drastically. Suddenly, we had an ApiController base class, and worse, an opinionated focus on a distorted view of what constitutes REST, with an emphasis on HTTP methods (e.g. GET, POST) and a loss of flexibility around URIs. When I migrated my code to the new ASP.NET packages, everything broke and I couldn’t see a straight-forward way to fix it.

I also looked at FubuMVC and OpenRasta, but I’ll be completely honest: they confused the hell out of me.

Meanwhile, I’d been going to a lot of conferences and sitting in a lot of talks about designing proper RESTful APIs, using hypermedia and discoverability and suchlike, and I had some ideas rattling around my head for things to make that easier. When I read a blog post (which I have since been unable to find again) about Rails-style MVC being a violation of the Single Responsibility Principle, the final piece clicked into place and I went from some loose ideas to a fully-fledged concept, and suddenly I needed to write it to see if it worked.

Nancy in a nutshell

Nancy started out as a .NET implementation of the Ruby Sinatra gem. Sinatra is the anti-Rails: it’s incredibly small and light, really more of a DSL than a framework. Fundamentally, it’s a very efficient way of attaching behaviour to URIs. Despite having to work within the constraints of a strictly object-oriented language, Nancy manages the same thing. Applications are defined in modules, and anonymous functions are assigned to URIs within the constructors of module classes. If C# allowed code to exist outside of methods, or methods to exist outside of classes, I have no doubt that Nancy would be even more like Sinatra. (There is an F# package called Frank which gets closer.) Much of my involvement with Nancy stemmed from the fact that it went beautifully with Simple.Data, which has a similar “low-ceremony” solution to the ORM problem. Like Simple.Data, Nancy makes use of the dynamic type support in C# 4.0 to allow easy handling of things like query string parameters. There is an emphasis on your code, which is a thing I may often be heard saying is important.

Simple.Web in a nutshell

Simple.Web is a ground-up implementation of the single-action controller pattern, which already has some currency in the MVC world. Many developers will create a separate controller for each URI, with a single action, and all the supporting methods and so on contained in that controller. But with a framework like ASP.NET MVC, you still have an Action method which returns an ActionResult, and the only other things which may be inferred about the action are the parameters, and anything you can specify in a method attribute. By enforcing the one-class-per-URI pattern (I call it “Model-View-Handler”), Simple.Web allows interfaces to be used as part of the equation, and that opens up far more possibilities than I had realised when I started writing it. So Simple.Web doesn’t use dynamic types at all (except for dealing with a design-time glitch in Razor that I haven’t worked out yet). Instead, it uses a ton of reflection and code-generation to work within a statically-typed paradigm.

Differences

With all that said, let’s look at the key differences between the two frameworks. I’m not making any value judgements about anything here, and as I’ve already said, the two things I needed which are in Simple.Web are in the roadmap for Nancy.

  • Nancy is driven by a diverse community who want different things, and Andreas and Steven work hard to supply them. Simple.Web, at the moment, is mainly driven by what I need for the thing I’m making. Some examples:
    • Nancy supports a load of different view engines. Simple.Web supports Razor.
    • Nancy makes an effort to run on Mono. Simple.Web happens to, and I do want it to, but it’s not the primary concern for me at present.
    • Nancy has high-level support for things like different types of authentication and validation. Simple.Web provides one low-level hook for authentication, and has no built-in support for validation.
    • Nancy supports multiple hosts, including self-hosting. Simple.Web is only fully tested on ASP.NET and IIS, although it is OWIN-compliant, and seems to run OK on my little Flux server.
    • Both frameworks support multiple IoC containers, but in my case this is because people have already contributed Autofac and StructureMap plug-ins to Simple.Web. Nancy also has an in-the-box IoC container, which Simple.Web doesn’t.
  • Nancy gives you access to an HTTP context object for dealing with things like headers. Simple.Web tries to abstract that away into an extensible pipeline system, which is a complicated subject and will be the subject of a future blog post. The short version is, you get what you want out of the HTTP request context and into properties before your application code is called.
  • Both frameworks are written with testability in mind. In the case of Nancy, there is a Testing package, which gives you a Browser class that you can use to set headers and so on. With Simple.Web, because the context is hidden away from your application code, you can instantiate a handler class and just set all the properties directly, so you don’t need to build query strings or headers or anything. Again, that will be covered in more detail in a future post.
  • Nancy is much more terse than Simple.Web. If you want to, you can write your entire Nancy application in a single class, which need only derive from NancyModule. You can write a Nancy app in a tweet. In Simple.Web, you have to write a separate class for every URI, and although there is no base class, it has to implement interfaces for each thing it might do or need. You can declare your own base classes, though. You can’t write a Simple.Web app in a tweet.
  • Conversely, Simple.Web is much more structured than Nancy. The static typing provides more information in the code, and enforcing a separate class for each URI can make team-working easier, since people are less likely to be editing the same file at the same time.
  • Simple.Web supports Task-based asynchrony. The primary methods and the Output properties can all return Tasks, and the entire pipeline is asynchronous. If you’re using C# 5 (with .NET 4.5 or 4.0) you can use the async and await keywords. Nancy has this on the roadmap; I don’t know the current status.
  • Simple.Web supports content negotiation. This means that handlers return objects, and Simple.Web determines how to render them based on the client’s request (in particular, the Accept header). This includes deciding whether to render HTML for a browser or a data format like JSON or XML for an API call. (A side-effect of this is that the View declares which handler it is for, instead of the other way around.) Again, Nancy has content negotiation on the roadmap, but at the moment, you return a specific content type from your method.
  • Simple.Web has some features designed to make it easier to build proper RESTful APIs, with links automatically included in JSON and XML data based on metadata in attributes. You absolutely can build a proper RESTful API in Nancy, but it’s not quite first-class in the same way.
  • Nancy has much, much more documentation and community support than Simple.Web (although there is some documentation).

Summary

Simple.Web and Nancy are two very different solutions to similar, but not identical, problems. Nancy is brilliant for getting a web site up and running quickly, with a minimal amount of code, and with a lot of choice, particularly around view engines. Simple.Web is great for building RESTful APIs and services, and supports content negotiation and async.

I have not set out to compete with Nancy, or with any of the other open-source frameworks in this space. We’re all competing with ASP.NET MVC, WebForms and Web API, and I think that’s a good thing to be doing. Choice is good.

Simple.Web

So on Wednesday at the Skills Matter Progressive .NET Tutorials, I gave a session offering an introduction to this new thing I’ve been working on, Simple.Web. The session was recorded, and you can watch it here if you like (it’s just over 3 hours), but I’m going to try and give a rough idea of what it’s all about in this post. I’ll be following this up with some more detail on specific areas in the coming days.

Why?

Obvious question, really. There are lots of web frameworks out there for .NET already, which all offer different things, so why build a new one? The primary answer is: none of them worked quite the way I wanted. There were things I liked about some of them, but not all in the same package. I loved WCF Web API while it was still called that, when Glenn Block was working on it, but by the time it became ASP.NET Web API it wasn’t the same thing any more. It’s had a Controller base class foisted upon it, for a start, and the routing was all completely different, and it broke my (current, start-up, commercial) project, which soured the relationship. I needed something else for my project, and nothing I knew of did the things I really needed right away.

The other thing was that I read a couple of blog posts around the theme that the MVC pattern breaks the rules of SOLID, most notably the Single Responsibility Principle. In a traditional MVC application, a Controller represents a resource type, and has Actions for all the possible operations against that type of resource: Create, Read, Update, Delete and so on. That’s multiple responsibilities right there. And this impacts on performance as well as maintainability, because you have to inject the dependencies for all the possible actions in the constructor, even though none of them may be needed. Search for “single action controller” and you’ll find dozens of posts warming to this theme and offering that workaround, but it got me thinking, what if all the controllers were single action? What if, instead of using a method to represent an action (or a URI), you used a class? How would a framework like that look?

Design goals

I decided to try building a framework like this in tandem with the commercial project, primarily focusing on getting it to do the things I needed it to do for that. My primary goals for the initial version were:

  • Keep it simple;
  • It should be ridiculously easy to do TDD and/or BDD;
  • Support asynchronous, non-blocking handling of requests;
  • Make it easy to build a proper RESTful, hypermedia-driven application and services, including supporting content-type negotiation for all requests, including HTML;
  • Be really open and extensible, because if people can write plug-ins and add-ons easily, I don’t have to build all that stuff in.

To that end, the framework has been built to be extensible, but currently provides a limited set of options. The only hosting option at the moment is on top of ASP.NET. The only view engine supported is Razor. It uses JsonFx for handling JSON, and a very rough system built on the WCF DataContractSerializer for XML. And the only IoC container I’ve built support for is Ninject. These are all personal preferences, and while I’ve tried to make sure they’re all abstracted in a way that will make it very easy for additional plug-ins to be built, I fully expect to have to make at least a few core changes if and when people want to build them. In particular, the work I did on refactoring out the hosting code into a separate project for ASP.NET probably took too much code with it.

Keeping it simple

I’ve tried to make everything obvious, and cut out boilerplate as much as possible. In particular, there are no base classes for handlers, although you are free to create your own if you want to. Everything is done through interfaces. Lots and lots of interfaces, each one very small, in accordance with the Interface Segregation Principle. Also, everything gets put together automatically, with no complex routing tables and brittle dependencies.

Facilitating TDD

The biggest barrier to automated testing of web apps is the need to fake, mock or stub the accoutrements of HTTP in order to fool the object under test into thinking that it’s running in a web server. In Simple.Web, handler objects know nothing about HTTP. They implement interfaces to tell the framework what information they need from the request, and what information they provide for the response. The framework takes care of mapping the various properties and methods to HTTP. This means a handler can be created and have those properties set in very simple “arrange” code, and you never need to mock another Request object in order to set a header or a cookie or a request body. Handlers can stick to implementing application and business logic, and you can stick to testing that logic, which is how it should be.

Building the handlers in this way has had other positive effects on the system and the code. It’s made for some very small, modular types; it’s made the HTTP<->handler mapping into an extension point which developers can hook into really easily; and it’s meant that the runtime system can be highly optimised, since all the information about what a handler needs and does is right there in its type declaration.

Supporting asynchrony

This is as important on a web server as it is on a client machine. In general, web servers spend most of their time waiting on I/O operations, pointlessly blocking on threads while a database or another web service does its thing. If this time spent waiting can instead be spent processing other requests, we can service more clients with fewer servers. This is, of course, the principle behind Node.js, but it turns out it works just as well in .NET, thanks to the Task Parallel Library and Windows’ kernel-level evented I/O. ASP.NET MVC 4 allows you to return a Task<ActionResult>, and when combined with the awesome new async/await features in C# 5, it’s really easy to write non-blocking web code.

In Simple.Web, the primary method on each handler is taken from the HTTP method represented by the handler interface. For example, a GET operation is handled by a type which implements the IGet interface, and that declares a Get method which returns a Status. It’s all very getty. Like this:

[UriTemplate("/")]
public class GetIndex : IGet
{
    public Status Get()
    {
        return Status.OK;
    }
}

Don’t worry about where the output comes from, we’ll come to that. The important thing at this stage is that for every HTTP method interface, there is an asynchronous variant, where the relevant method returns a Task<Status> instead, and that would look like this:

[UriTemplate("/")]
public class GetIndex : IGetAsync
{
    public Task<Status> Get()
    {
        return DoLongRunningThing()
            .ContinueWith(t => Status.OK);
    }
}

Except of course you’d have some error checking and stuff in there. That’s where you want to be using C# 5 and async/await, otherwise it’ll bake your brain.

The point is, the decision to make something asynchronous is not a big one, and you’re free to mix and match synchronous and asynchronous handlers in a project; it’s up to you.

REST and hypermedia

The most important feature for implementing good, flexible, robust web apps and APIs is proper content-type handling. This is one of the biggest problems with ASP.NET MVC: actions do not return resources; they return specific representations of resources. The action decides whether to render a view or some XML or some JSON, when in fact it should be the client telling the action what representation it’s after. To do this, you need a content-type negotiation system, so Simple.Web has one, although it’s in a fairly embryonic state at this point.

A Simple.Web handler outputs an object, or a collection of objects, and lets the content-type negotiation system work out what to do with it. If the client is a browser asking for HTML, then the view-engine system kicks in, and tries to find a view. It can do this using the @model directive if only one view in the application declares that model type:

@model Sandbox.Form
<!DOCTYPE html>
<html>
    <body>
        <div>
            <h1>@Model.Text</h1>
        </div>
    </body>
</html>

or, if that is not specific enough, or if there is no model type for a given handler, there is a new @handler directive to support directly linking between view and handler:

@handler Sandbox.GetForm
<!DOCTYPE html>
<html>
<body>
<h1>@Handler.Title</h1>
<form action="/submit" method="POST"><input type="text" name="Text" /><input type="submit" /></form>
</body>
</html>

This also results in the handler being a property in the view, with all its public variables available; no more need for ViewBags.

The other aspect to HTTP and hypermedia-based apps and APIs is that all resources should come with a complete, human- and machine-readable set of the available state transitions for the resource, represented as links. There is a system for building these links within Simple.Web, and I’ll be covering that in an upcoming post.

Be open and extensible

Over the last year and a half of maintaining Simple.Data, I’ve been really impressed by the can-do attitude of people who have built and maintained their own adapters and providers, and submitted code back to the core project when they needed something. There’s an astonishing number of databases, both SQL and NoSQL supported, and mostly that support is nothing to do with me.

I want to let the same kind of people do that with Simple.Web too, whether it’s for view engines, or hosting systems, or content-type handlers. And with a web framework, there’s an additional driver for being open and extensible, because there are plenty of points within a specific project where you might want to change the way something works.

So the framework comes out of the box with some plug-ins, which are included in the Simple.Web package for the time being for convenience, but I’m hoping that fans of other hosts/view-engines/serializers will pop up with their own alternatives, at which point I’ll separate out the JsonFx and the Razor, for instance.

But Simple.Web is extensible in smaller ways, too. For example, there are interfaces for GET, PUT, POST, PATCH, etc., but I haven’t created an interface for MERGE, which some systems use. What I have done is make it easy for you to add your own HTTP method interfaces, which will get picked up by the framework and integrated just like the built in ones. So you can add MERGE, or TRACE, or make up your own methods, like SMITE and BESTOW.

And then there’s all those interfaces which map information between the HTTP infrastructure and your handlers. Those are all built on a very simple pattern, using public types and attributes, and you can create your own interfaces which will get integrated into the pipeline in exactly the same way that the built-in ones do. If you have a custom header called X-User-Mood, you can create a “behavior” interface and some “implementation” code, and it will get hooked in for you, so you never need to pollute your handler code with HTTP contexts and requests and responses.

Getting started

OK, that’s enough waffle for now. If it sounds interesting, then the Skills Matter video has a lot more of me blathering on about it and doing some demos, many of which fail spectacularly. You can install the package from NuGet, or download the source from Github, where there is also a demo application which demonstrates some of the main features. There’s a Google Group for people who want to use the framework to build applications, and another one for people who want to build plug-ins or add-ons or contribute to the core in some way (hint: Razor needs some love).

Also, because this one is all statically-typed, with no dynamic oddness, IntellSense is your friend, and there are documentation comments all over the place so it should be reasonably easy to pick up. I’m looking into something that generates actual help from the comments and isn’t Sandcastle, so hopefully there’ll be a manual soon.

Finally, I’ll be putting up some more detailed posts about various features over the next few days and weeks, so watch this space.