Getting Started

Overview

The following steps you through the process of installing and configuring Command Routing in a shinny new ASP.NET 5 web application.

Currently Command Routing only supports the dnx451 framework. Support for dnxcore50 will be added once it's stable. For the time being, before starting you'll need to edit your project.json file and make sure you only have dnx451 in the list of frameworks to deploy to:

// blah blah blah
"frameworks": {
  "dnx451": { }
},
// blah blah blah

Install from Nuget

You can add the CommandRouting NuGet Package to your project from the Package Manager Console:

PM> Install-Package CommandRouting -Pre

Configure Services

Next, you'll need to configure the command routing service in the ConfigureServices method of your Startup.cs file.

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    // Enable command routing
    services.AddRouting();
    services.AddCommandRouting();
}

Command Routing uses MVC 6 template routes under the hood, so you'll also have to add MVC 6 routing first.

Also note that the AddCommandRouting() extension method is in the CommandRouting.Config namespace (so you'll want to add a using directive for this assembly at the top of your Startup.cs).

Define a Request

Command Routing can interpret HTTP requests as any strongly typed C# classes that you define. To see how this works, create a folder in your project called Hello and create a class in that folder called HelloRequest:

public class HelloRequest
{
    public string Name { get; set; }
}

Add a Request Handler

Next we need to define a request handler that is capable of handling such requests. In the same folder, create another class called SayHello and make sure this inherits from QueryHandler<HelloRequest, string>:

public class SayHello: QueryHandler<HelloRequest, string>
{
    public override HandlerResult Dispatch(HelloRequest request)
    {
        return Handled($"Hello {request.Name}");
    }
}

A QueryHandler is a request handler that returns a result... in this case a string (the second generic type parameter to the abstract QueryHandler base class that we inherited from). That means that we can only pass a parameter of type string to the Handled method when we return a result. We could also, of course, return a more complex C# object. The only real requirement is that the return type be serializable since Command Routing will need to convert it to a JSON object when it builds the HTTP response that gets sent back to the client.

Wire up your first Command Route

The next thing we need to do is route one or more requests to the route handler. There are various ways to do this. The simplest is to configure a route in the Configure method of the Startup class. This can be done in three statements:

        public void Configure(IApplicationBuilder app)
        {
            app.UseIISPlatformHandler();

            CommandRouteBuilder routeBuilder = new CommandRouteBuilder(app.ApplicationServices);

            routeBuilder
                .Get("hello/{name}")
                .As<HelloRequest>()
                .RoutesTo<SayHello>();

            app.UseRouter(routeBuilder.Build());

            app.Run(async (context) =>
            {
                await context.Response.WriteAsync("Hello World!");
            });
        }

The first line we added creates a CommandRouteBuilder that we can use to configure one or more routes.

CommandRouteBuilder routeBuilder = new CommandRouteBuilder(app.ApplicationServices);

The second line configures a route for all HTTP GET requests matching the route template "hello/{name}". A HelloRequest request object will be created from any such requests and that request object will then be passed to the SayHello request handler, which will do the dog work to actually handle the request.

routeBuilder
    .Get("hello/{name}")
    .As<HelloRequest>()
    .RoutesTo<SayHello>();

Finally, once we've finished building routes (in this simple example we only built one route but we could easily add more), we can build the routes and tell MVC to use these.

app.UseRouter(routeBuilder.Build());

The rest of that Configure method is just boiler plate from the empty ASP.NET 5 web application template.

At this point, you should be able to run the application and make a get request to "hello/bob" and you should see a JSON encoded string saying "Hello bob".

If you made it this far then you have just created your first command routing application!

Next steps

Whilst creating routes individually is feasible, for larger applications that might have hundreds of routes configured, it's a bit painful to maintain... so at this point you might like to look into Route Sets, which you can use to compose hierarchical routes recursively.

You might also like to read through the docs on request activation and request handlers to get a better understanding of what you can do with Command Routing.

Finally, the Sample Project in the source code on GitHub demonstrates various other features such as how to return files from your request handlers or how one request handler can share information or results with other handlers.