One (more) ASP.NET

Visual Studio 2012 shipped last week, so I'm working on a branch in Octopus Deploy to upgrade the ASP.NET frontend of Octopus to ASP.NET MVC 4.0. My main reason for upgrading was the inbuilt bundling and minification support, which is awesome.

Octopus provides a RESTful API (browse to /api on your Octopus server), which serves up documents in JSON like this:

    "Id": "DeploymentEnvironments-1",
    "Name": "Production",
    "Description": "A production environment",
    "SortOrder": 0,
    "Links": {
      "Self": "/api/environments/DeploymentEnvironments-1",
      "Machines": "/api/environments/DeploymentEnvironments-1/machines"

Web API wasn't stable when I first built it, so I implemented it on top of ASP.NET MVC 3.0 using a custom ActionResult that used Json.NET. It doesn't support content negotiation, so everything is JSON-only. So when it came time to upgrade, I was also excited to try and convert my REST API to use ASP.NET Web API.

The ASP.NET team has been focussed on "one ASP.NET" for a while. Scott Hanselman sums it up with a nice image, which I'll shamelessly hotlink:

One ASP.NET to bring them all and in the darkness bind them

ASP.NET MVC and Web Forms have definitely done a lot of work to integrate, but ASP.NET Web API, I think, has a long way to go.

For instance, you'll be familiar with routing in ASP.NET:

  new { controller = "Dashboard", action = "Index", id = UrlParameter.Optional }

You can also do routing in ASP.NET Web Forms:


Of course, as one would expect, both of these build on top of a shared routing system provided by the green ASP.NET box at the bottom of the diagram.

Naturally, you can also do routing in ASP.NET Web API:

  new { id = RouteParameter.Optional }

You would expect this to be built on top of the same routing framework. Right? Right? Wrong!

ASP.NET MVC and Web Forms use classes like RouteCollection and the RouteBase abstract class. ASP.NET Web API on the other hand makes use of HttpRouteCollection and IHttpRoute. Of course, the reason they need a second copy becomes clear when you see the vast differences between the two.

For example, IHttpRoute has methods like:

public interface IHttpRoute
    IHttpRouteData GetRouteData(string virtualPathRoot, HttpRequestMessage request);  
    IHttpVirtualPathData GetVirtualPath(HttpRequestMessage request, IDictionary<string, object> values);

While ASP.NET's routing RouteBase class has completely different methods like:

public abstract class RouteBase 
    public abstract RouteData GetRouteData(HttpContextBase httpContext); 
    public abstract VirtualPathData GetVirtualPath(RequestContext requestContext, RouteValueDictionary values);

My guess is that this duplication exists because ASP.NET Web API is designed to also operate outside of IIS. But if we're serious about "One ASP.NET", why not do it properly and make the whole stack run outside of IIS? (It can be done now actually, but it is very painful and breaks a lot).

The madness doesn't stop here. ASP.NET Web API ApiController classes don't inherit from the ASP.NET MVC Controller class. ASP.NET gives you a UrlHelper class to generate URI's from the route table, while ASP.NET Web API has its own completely separate (and less nice) UrlHelper class. ASP.NET provides some well known basic types like HttpRequest and HttpContext. Web API has its own alternatives. Filters are the same but different. Both stacks have their own dependency resolver. Both have their own model binders. Both have their own model state/validation. The list goes on and on.

Here's a more correct image:

One more ASP.NET

While both frameworks work, it's hard to say they "work together". I'm finding myself creating a bunch of wrapper classes and adapters so that I can do basic things like generate URL's when I'm in either context. It all feels very messy.

Right now, the only reason I can think of moving to ASP.NET Web API is content negotiation, but making ASP.NET Web API generate nice looking XML and JavaScript off the same model also seems to be a lot of work, so I'm not sure there's much to gain there.

(Part of me wonders whether content negotiation and a few REST idioms should just have been implemented in ASP.NET MVC, which would really obsolete the whole Web API project.)

If I could have one wish for ASP.NET 5.0, it would be to stop having "one ASP.NET", and instead to have one ASP.NET.

A picture of me

Welcome, my name is Paul Stovell. I live in Brisbane and work on Octopus Deploy, an automated deployment tool for .NET applications.

Prior to founding Octopus Deploy, I worked for an investment bank in London building WPF applications, and before that I worked for Readify, an Australian .NET consulting firm. I also worked on a number of open source projects and was an active user group presenter. I was a Microsoft MVP for WPF from 2006 to 2013.

Michael Noonan
Michael Noonan
19 Aug 2012

I played around a few months ago and came to a similar conclusion/confusion.

I recently heard Hadi Hariri talking about some of these issues. He mentions using some a combination of fairly simple filters and routes to achieve content negotiation in plain old MVC. I haven't tried/had-the-need, but it makes a lot of sense.

With HTTP, your application is your API

19 Aug 2012

inbuilt bundling and minification support,

Have you used this stuff in anger yet? If not, I'll be interested to see what you think of this when you have :)

20 Aug 2012


I've been using it on (a custom micro-CMS) for a few months now:

e.g., from view-source on that page:

<link href="/Content/css?v=lcdaclGmmilyuo7zc_Tvw26HixlfWpMcxZFLvSxBfSY1" rel="stylesheet" type="text/css" />

<script src="/bundles/jquery?v=ed9YR1wjc1ipRaM4Hoxsg6F3a12KHeS8fNcpzmCjzhk1" type="text/javascript"></script>


20 Aug 2012

In my comment above the link href points to - that's actually an artefact of this blog engine auto-adding the host name rather than what it actually says in view-source.

20 Aug 2012

Cool! And you're happy with it?

I got the same outcome when I implemented it, but found it clunky to use compared with other libs that I had tried (e.g. ClientDependency).

I wish I'd kept a list of all the things that I didn't like about it - perhaps I should have blogged it? :)

20 Aug 2012

The fact that Web API has a pretty no compromises stance to self host, dependency injection, serialization, standards based http stack and async tasks means it's a pretty good thing that it wasn't hindered too much with MVC conventions and code base. They have then made a pragmatic approach to routing and filters, and naming ApiControllers. We've built several Facebook apps for clients mixing MVC and Web API. Adapters are simple to author and quite specific to individual apps. On the client, the glue between them is jQuery! It becomes pretty clear during a build which will provide the lightest weight option for a given scenario, mixing MVC and Web API. And Web API is pretty fun and easy to code with!

20 Aug 2012

That's not a more correct image. There is no copy of Web API is hostable outside. It has roots in WCF. I don't see a controversy here.

20 Aug 2012


It does feel like a lot of ASP.NET MVC was copy-pasted to create the stack for Web API (e.g., routing code, model binding code, model state code, dependency resolver code). It's all much the same, just in a different namespace. Web Pages did a similar thing (it has its own HtmlHelper, etc.)

As a developer building a HTML application that also has an API, I feel like I'm using two completely different frameworks that are just hosted in one process. I wrote a custom route so that my MVC URL's were lowercase. I have to write it again so that I can do the same in Web API.

I think a better solution would have been to refactor the common stuff out of ASP.NET so that it could be shared by both ASP.NET and Web API.

20 Aug 2012

Web applications are constantly evolving, creating new application patterns and interactions all the time. ASP.NET is also continuously evolving and updated to facilitate those new application patterns. The notion of “One ASP” doesn’t mean that nothing ever changes but rather that things play together.

Web API deals with modern Web apps using Web APIs and client side rendering. MVC deal with apps using form data and dynamic HTML. The original ASP.NET model was not particularly designed for any of these yet we have built support to make it do so.

For Web API it is essential to have a great HTTP object model for HTTP concepts such as headers, status codes, content, etc. The existing ASP.NET HttpContext object model is showing its age in terms of size, complexity, and how you program against it. With .NET 4.5 we have a modern HTTP object model (HttpRequestMessage, HttpResponseMessage, HttpContent, and HttpMessageHandler) and it was conscious decision to make that the basis of Web API. At the same time we wanted to leverage the very successful MVC patterns which is why you see a lot of “semantic equivalence” between Web API and MVC. However, as HttpContext was flowing through many of the MVC APIs we had to modify them to support the new HTTP OM instead. We were careful making this still seem as close as possible so that you would recognize the patterns but you are correct that they are not binary compatible.

In this case, though, binary compatibility would have meant not having a modern HTTP OM making the experience significantly less ‘fun’. We can’t ignore that cost. We did design the new model so that we have the option of building MVC on top in the future.

I do disagree with your diagram – there is no “copy” of ASP.NET. Web API, MVC and SignalR all introduce new patterns but there is no copy – they provide support for new applications patterns in a way that is compelling and productive.

20 Aug 2012


We did design the new model so that we have the option of building MVC on top in the future.

I think that if/when this happens, the model will be much nicer. I'm just raising the point that in the interim, it does make using both together difficult. For now I'll continue to use ASP.NET MVC to build my REST API instead of Web API because it means duplicating less of my own code.

20 Aug 2012

And that is perfectly fine, Paul. It all depends on what kind of app you want to build. There a million ways to skin a cat. If we say there's only one way, then it will only work for some. There's nothing "wrong" with still using MVC for your API. It doesn't mean that Web API doesn't make sense for others though.

20 Aug 2012

@Paul, that is great feedback - thanks!

21 Aug 2012

Great post. Good to know the shortcomings before starting a new project.

22 Aug 2012

@eduardo, for a new project, I don't think Web Api has any noteworthy shortcomings vs. MVC controllers. In fact, I think the biggest thing people are missing is how much easier it is to design an application using RESTful design principles.

Since there is so much FUD in that arena, it is not surprising that there is now growing FUD around Web Api. It really helps to understand one before the other.