Lately I’ve been delving into the ASP.NET MVC framework, the timing of which has been interesting as I am about to finish reading RESTful Web Services by Leonard Richardson and Sam Ruby. It’s an excellent book that I’d highly recommend to anybody designing and creating services for the web, or just interested in it.

This quote from the book description on Amazon.com succinctly describes what’s been floating around in my head for a while:

You’ve built web sites that can be used by humans. But can you also build web sites that are usable by machines? That’s where the future lies, and that’s what RESTful Web Services shows you how to do.
[Emphasis mine]

Why do we have to build web "sites" for humans and different web services for machines? I can create an ASP.NET site, a SOAP-based ASMX web service, or a SOAP or REST (with .NET 3.5) WCF service and while they can share business logic, there’s still a lot of "endpoint code" (for lack of a better term) that has to be implemented, and if I want a human friendly front end + a web API, I have to build a site that essentially wraps another service, since the site itself really is a service.

With the ASP.NET MVC Framework, though, I see the opportunity to unify services and "sites" (human-readable services). Imagine visiting http://www.example.com/books/ and being able to receive back HTML, POX, or JSON, depending on what you asked for–with no additional code required outside of following a convention or two. Web browsers ask for HTML, returning a human consumable page that gets rendered. AJAX or custom clients can request JSON or XML, whatever they know how to interpret best.

The separation of concerns and extensibility that the ASP.NET MVC framework exposes lets us accomplish this with surprisingly little code. At least for read-only services (which is as far as I took it for now.) If you’re not familiar with how the ASP.NET MVC framework works, check out Eilon’s excellent ASP.NET MVC design philosophy post (he also includes many good reference links).

Approach

Outside of the ASP.NET MVC framework itself, from an HTTP perspective I simply want to alter my response format depending on what the incoming request asked for. I decided to keep it simple and only support the "text/html", "application/xml", and "application/json" media types.

I started off trying to use the "Accept" HTTP header as an indicator for what response format the client preferred. After all, that’s what the Accept header is for: "The Accept request-header field can be used to specify certain media types which are acceptable for the response." But I quickly ran into a snafu when I found that Firefox prefers XML over HTML.

That means that every request Firefox makes would result in the uber-friendly XML view.

And because of that snafu, I read up some more on the Accept header – namely what they had to say about it in an appendix of RESTful Web Services:

Hiding this information inside the HTTP headers is a good idea for web browsers, but it shouldn’t be the only solution for web service clients. I recommend exposing different representations using different URIs. … If you want to support Accept on top of this, that’s great (Rails does this too).

There was also some pragmatic advice in the chapter on Representations.

It’s RESTful to keep this information [file format types] in the HTTP headers, and it’s RESTful to put it in the URI. I recommend keeping as much of this information as possible in the URI, and as little as possible in request metadata. I think URIs are more useful than metadata. URIs get passed around from person to person, and from program to program. The request metadata almost always gets lost in translation.

I tend to agree with that. To make it easy and somewhat intuitive, I chose to base the response format on the existence of a querystring parameter named "format". It can specify "xml" or "json", for example http://www.example.com/books/?format=json. But really, you can use any method you want to allow format specification.

Implementation

Formatting the response is the responsibility of the View in the MVC architecture. Since processing requests for HTML content didn’t need to change from the default ASP.NET MVC behavior, all I need to do is override the default WebFormViewFactory functionality and return my own "SerializedView" if the URI indicated xml or json formatting. SerializedView is an abstract base class that encapsulates common functionality and allows sub-classes to perform the serialization, or handle custom error reporting.

When a Controller passes control to a View, it calls the "RenderView" method on the Controller base class, passing in the view name and some optional data – including something called "ViewData" – an object that represents the content the view should render.

Here’s the best part: creating an ASP.NET MVC site+service using my approach means passing a serializable object as ViewData. It’s as simple as that, nothing else needs to change (ok, you need one additional line of code in your Application_Start handler – more on that later). In your ASPX view, you can access the object via ViewData and use all the HTML helpers, UserControls, etc. that you want to build out your HTML, javascript, and who-knows-what.

Unfortunately, the current CTP of the ASP.NET MVC framework does not expose a way to "inject" a different IViewFactory (my subclassed version) into the default Controller created by the ControllerBuilder class. So, that means implementing the IControllerFactory interface and duplicating (ouch!) the code that ControllerBuilder executes, with one somewhat nasty addition.

Yuck! The ViewFactory property is specific to the Controller class, not the IController interface, hence the specific processing — and that also means my approach won’t work for other IController implementations. Not without some extra work, anyway.

This is where the only change you need to make comes in. My IControllerFact
ory implementation needs to be registered as the default controller factory, which is done in the Application_Start handler – the same place your routes are configured.

Serializable Types

For various reasons, you should use the WCF [DataContract] and [DataMember] attributes to tag your objects as serializable. For one, you gain all the serialization benefits these attributes offer, plus you can use the same contract types across multiple endpoints if you need to. And for another, serializing to JSON via the System.Runtime.Serialization.Json.DataContractJsonSerializer requires the DataContract attribute. If you use the older [Serializable] attribute, you get some interesting results.

The deprecated System.Web.Script.Serialization.JavaScriptSerializer works correctly for objects tagged with [Serializable] but it’s, well, deprecated.

Example

Using the default ASP.NET MVC Application templates, I registered the default ControllerFactory in my Application_Start handler, defined a Books controller with a default action, and a "List" view that prints out some Author and Title information. I also created the following definition of a book.

My controller implementation is no different than it normally would be. I get a list of books and render the "List" view, explicitly specifying the book list as the ViewData. You might notice that I pass the ControllerContext into the GetBooks method. I am experimenting with returning URIs to related resources as part of the data. I’m still playing around, but for now you get my latest attempt.

Requesting the appropriate URI in Firefox yields the expected result from my List view:

And altering the URI returns the appropriate response types, xml or json.

Summary

This ended up being a longer post than I intended, but I hope it was worth it. I’ve put the full source for the "MvcServiceLibrary" and an example up on my Tools page – but here’s the direct download link. I’ll also be checking if this is worth putting into the MvcContrib open source project.

I think that the ASP.NET MVC framework is a huge step forward in creating RESTful web sites, and hopefully now also RESTful web services! Let me know what you think, I love getting feedback.

I attended the VS 2005 launch event in my hometown today (Indianapolis), and at the “Meet the Experts” session afterwards, I presented a similar problem to the one I mentioned previously to the VS.NET 2005 expert. Well, long story short, Bill Steele found the solution to my problem (thank you!). It was that the disco generated by the web service on the server (a 3rd-party web service) was incorrect, it was redirecting the WS consumer to an invalid URL (hence VS.NET wasn’t able to auto-generate the reference to it). Well, about 10 minutes later, on my way home, it hit me like a smack in the face that the issue I previously had was with the same WS provider, and that I never did test my “issue” in my own controlled environment. Geez. I feel like a moron! I would bet extremely large sums of money that it was the same issue then that I am seeing now. (the old URL is now defunct, so I can’t test it against their server, and I don’t feel like taking the time to prove it since I’m so sure of what the problem was) I will keep my old blog post around just to remind me to always hunt down ALL avenues–I had left one unexplored last time (and this time) and it happened to be the one place the error existed.

So thanks to Bill! You really are the expert!!!

at MSDN

I’ve had the privilege of getting my hands on both of the articles before they were released (the first was recently released, the second is still pending) and used them as a strong resource when developing a Web Service I’ve been working on for the past few months (on the side).

I am going to echo Aaron’s complaint that tool support for contract-first development is limited (regarding Web Services anyway) and while the WSContractFirst tool he mentions is nice as it integrates fully with Visual Studio .NET, it leaves a little to be desired. I found that once I wanted to change my WSDL (my contract) I either had to re-create the entire thing, or make my changes manually and then circumvent the convenience offered by the tool and use the VS.NET-supplied Web Service proxy generator (wsdl.exe).
Admittedly I never tried using a WSDL editor, I just did it by hand (a pain!), so perhaps my frustration is self-generated. Either way I think I would like to try my hand at creating a WSDL generating tool that integrates with VS.NET. But I wouldn’t like to try too hard, for several reasons:
1. Time
2. According to Aaron, Visual Studio 2005 (Whidbey) is going to contain some enhancements in this area already. So do I really want to re-invent the yet-to-be-invented wheel?
3. Did I mention time?

If you read this and have any suggestions, please let me know!

Adding a web service reference that doesn’t use the standard port (80) through Visual Studio .NET 2003’s “Add Web Reference” interface will cause you all kinds of pain. The issue is that although you can include a port number when specifying the URL for the web service, the underlying tools that generate the proxy classes and the .disco file will strip it out without telling you.

So when I add a reference to “http://www.webserviceserver.com:5332/service.asmx”, the end result in the .disco and .cs files is a reference to “http://www.webserviceserver.com/service.asmx” which obviously doesn’t work.

So here’s the fix: (if someone knows a better one, please post it in the comments!)

1. Add the web reference, but when it times out and fails, instruct VS.NET to continue processing the files. This will create the Reference.cs file (which will just contain a namespace), Reference.map, and the .disco file.
2. Edit the .disco file in a text editor (VS.NET will work great), and alter the following:
   1. In the <contractRef> element, edit the “ref” and “docRef” attributes to include the correct port number
   2. In the <soap> element, edit the “address” element to include the correct port number
3. Open a Visual Studio command prompt window (for my default install, I can get to this from “Start -> All Programs -> Microsoft Visual Studio .NET 2003 -> Visual Studio .NET Tools -> Visual Studio .NET 2003 Command Prompt”). This will open a command prompt with all the required paths set to access the Visual Studio .NET command-line tools.
4. Navigate to your project folder, and go into the Web References\[webservice] subfolder. Use wsdl.exe to create the proxy class for use in Visual Studio:
   1. Type “wsdl.exe [full web service URL - with port number]” — This will generate a .cs file that has the same name as your .disco file (hopefully). Regardless, just look for the new .cs file that exists in the folder.
   2. If you’re interested in the wsdl.exe tool, type “wsdl.exe” at the command line to see the options available. If you’re implementing your web service properly, you should be familiar with this tool as you can use it to create your web service “contract-first”. Check out the blogs at pluralsight.com for more info on that important topic.
5. Open Reference.cs and the newly created class file from step 4 in an editor (like VS.NET). You should notice that the Reference.cs file contains only the namespace keyword (along with a namespace identifier) and nothing else. Copy the “using” statements from the wsdl.exe generated class file above the “namespace [namespace id]” line in Reference.cs. Then copy the entire implementation portion of the web service proxy code from the generated class file into Reference.cs, inside the namespace declaration.
6. [ALTERNATE STEP 5] Simply open the generated class file and wrap the entire thing (minus the “using” statements) in a namespace declaration. Then add the new .cs file into your project. Note that this won’t show up under “Web References”, however.
7. Finally, edit the final file (depending if you did step 5 or 6), find the constructor for the main class (the class that derives from System.Web.Services.Protocols.SoapHttpClientProtocol), and change the “this.Url” property assignment line of code to point to the correct URL. This should just mean adding the port number into the URL string.

And there you have it. A pain in the butt? Yes. Which reminds me, attempt to refrain from right-clicking on the web reference and choosing “Update Web Reference” as this will overwrite your files (if you select “Continue” when it times out instead of choosing “Skip”). If you do need to update the web reference, you will have to repeat all these steps. Generate the proxy from the WSDL and copy the code into the Reference.cs file. Blech.

Another note is that using the disco tool doesn’t fare any better than the IDE (probably because the IDE uses the tool indirectly). It will also fail because it attempts to access the web service on port 80.

I apologize for the lack of screenshots, I am still trying to figure out the best way to host pictures on here.