Skip to content

Nancy style Modules in Asp.Net Web API with Superscribe

September 20, 2013

After months of work I can finally announce that the first Graph based routing framework for asp.net is pretty much complete. I’ll be writing another ‘Introducing’ post for this project shortly, but in the meantime I hope you’ll find this little taster intriguing.

UPDATEYou can now use Superscribe Modules with OWIN too.

Inspired by NancyFX

If you don’t know much about Nancy (shame on you) then take a quick look at their site and you’ll quickly get the lay of the land. Nancy is built on the ‘Super Duper Happy Path’ principle which put simply is a fourfold philosophy – “It just works”, “Easily customisable”, “Low ceremony” & “Low friction”.

Hello world in Nancy looks like this:

Couldn’t be much simpler if it tried… particularly when it comes to defining routes and the code that handles them. I can’t stress how much I would like to thank the Nancy team for inspiring the approach covered in this post so if you are reading this, keep up the good work guys and I hope you understand that imitation is the greatest form of flattery!

Ask anyone who uses Web API on a daily basis and they’ll generally tell you that the default MVC style routing is a bag of balls. Wouldn’t it be nice if we could use this module style within Web API?

Leading question much?

With release of Superscribe.WebAPI 0.2.2 we can now do just that, and here’s how.

Fire up Visual Studio and create a new MVC 4 project:

Create Project

Choose to create an empty web application when prompted:

Empty web application

Once your solution loads, go ahead and delete the App_Data, Controllers, Models and Views folders as we won’t be needing them.

Delete crap
You can also remove the RouteConfig.cs file in App_Start. Don’t forget to remove the reference to this in Global.asax too.

Hello, Superscribe

Next, use the package manager to install the Superscribe.WebApi package. This will also install the Superscribe core library.

Install Superscribe

Once that’s complete, we can add our module. Create a new class called HelloWorldModule, and make it implement Superscribe.WebApi.Modules.SuperscribeModule.

Just like in the Nancy sample, all we need to do is add our GET handler to the module. When finished we should have something like this:

Finally, we need to tell Asp.Net that we want to route using Superscribe. We can do this in WebApiConfig.cs by removing the default routing logic and replacing it with the following. I’ve also removed the xml formatter for good measure.

That’s it we’re done, go ahead and hit start. Super Duper Happy Path, have you met Asp.Net Web API?

Hello world

Parameter Capture

At this point I should point out that Superscribe routes are defined fundamentally differently to routes in Nancy, or indeed Web Api’s attribute routing. Superscribe is a graph based routing framework, so route definitions consist of strongly typed segments.

There’s plenty of syntactic sugar to help us out along the way of course. The best way of demonstrating how this affects us is by extending our example to include a parameter. The following is equivalent to a route /Hello/{Name} where name is a string parameter:

As the documentation matures I’ll be filling in the gaps, but in brief Superscribe uses a DSL for defining graph nodes and the edges between them. In this example, the Get assignment attaches a very simple two node graph to the base node where all routes originate. Here’s the result:

Hello Roysvork

Funky interlude

Using the DSL and strongly typed segment definitions, we can harness the full power of graph based routing. As I mentioned in my previous post, all route nodes can have an Activation function, and Action function, and a Final function defined. Superscribe is doing a whole bunch of stuff for us setting these up:

  • The “Hello” node is created with an the Activation function of segment == “Hello”, and there is no Action function.
  • In the case the the (ʃString)”Name” node, the Activation function is set as a Regex matching any string, and the Action function to capture the segment value as a named parameter.
  • In this mode of usage (there are others) the final function is defined by the assigment to Get[...]

In this module mode, Superscribe also allows us to specify activation functions through the DSL. Remember, an activation function dictates whether or not the current segment is a match for this node. For example, we can do the following:

So now the behavior is the same for the first 45 seconds in every minute. For the last 15 seconds, you get insulted. The order of the routes is of course important here, otherwise the regular route will match all the time and the time dependent one won’t get a look in. It’s a pretty useless example but a nice demonstration nonetheless!

One more thing worthy of note here… the DSL relies on operator overloads and implicit casts to do it’s thing. Sometimes it needs a helping hand though… if it doesn’t have a node of the correct type to ‘anchor’ itself on as in the example, we need to add a leading ʅ / to get our route to compile.

Model binding and other Methods

Back to serious mode now and to some more mundane features but nonetheless important features. Our modules would be pretty useless without support for DELETE, PUT, POST, and their stingy friend PATCH. And with some way of making sense of the Http content we’ve received as part of the body of the request.

As you may expect, you can use indexers to handle other methods just like with Get. The model binding again borrows from Nancy, so a POST implementation works using the Bind method like so:

Returning just a status code is not very RESTful of course, but given that this is just Web API underneath, you can still use HttpResponseMessage to do whatever you like:

Dependency Injection

Finally for this post, we’ll have a look at how dependency injection works in a Superscribe module. Unlike a Web API controller or a Nancy module, Superscribe modules are static for all intents and purposes, being instantiated once at application startup for the purposes of registering routes with the framework.

As a consequence, we can’t inject dependencies straight into our module. We can however call the Require function which leverages the dependency resolver in MVC 4. Here I’m using Ninject, but of course you could use any framework of your choice.

Summary

I hope you enjoy having a play around with Modules in Web API… this is just one way you can use Superscribe. One of the design goals of the project was to support different approaches to routing, and I will cover more of these in future posts.

Superscribe has many features already implemented that aren’t discussed in this post… such as regex matching and optional nodes, which I’ll also cover in the near future. If you’re thinking of trying stuff out, just bear in mind that the following things won’t or might not work so well just yet, but are on my list of things to do:

  • HttpMessageHandlers \ Global Filters
  • Co-existing with normal controllers
  • Co-existing with attribute routing
  • Co-existing with just about anything

For now, please take this framework for what it is… it’s under development, quite possibly buggy, and changing all the time. Probably don’t use it in a production app just yet, but *do* let me know if you try to do things and they don’t work, via the Github project at https://github.com/Roysvork/Superscribe. Things will become stable real soon!

You can find all the source from the examples in this post here: https://github.com/Roysvork/WebApiModuleHelloWorld

Once again, a big shout out to the folks involved with Nancy Fx who inspired this approach!

Pete

References

http://roysvork.wordpress.com/2013/08/20/graph-based-routing/

http://nancyfx.org/

https://github.com/NancyFx/Nancy#the-super-duper-happy-path

https://www.nuget.org/packages/Superscribe.WebAPI

http://attributerouting.net/

https://github.com/Roysvork/Superscribe

https://github.com/Roysvork/WebApiModuleHelloWorld

From → REST, Web API

6 Comments
  1. Awesome post and concept – thanks for putting it together!

    On a related note, what’s the key combination for the ʃ character? Trying to figure that one out since I’ve never used it.

  2. Coolness! I was wondering why you didn’t use a plain Empty Web Application project but I then saw you using the App_Start stuff. Nifty!

    Thanks for a great post!

  3. codescribler permalink

    Reblogged this on Daniel Whittaker and commented:
    Roysvork is working on a really interesting project to bring NancyFX style routing to Web API.

  4. codescribler permalink

    Thats a really great concept. I will be watching the progress of this project with interest.

  5. Is there any importance in using the ʃ (Esh) character? I also have never come across it!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: