Processing Messages in a Self-Hosted Web API Service

In an earlier post, I showed how to host an ASP.NET Web API service on a server without IIS. In that post, I suggested that the most interesting object used in the self-hosting process is the HttpSelfHostConfiguration object–that’s the object that allows you to configure your service. In that last post, for instance, I used the HttpSelfHostConfiguration object to specify the service’s URL and routing rules. But that’s just a taste of the configuration object’s power: you can also use the HttpSelfHostConfiguration object to insert handlers into the Web API’s processing pipeline to centralize  pre- or post-processing on messages sent to and from your service (you can insert message handlers when hosting a Web API service in IIS, also).

You can add as many handlers as you want to the Web API processing pipeline: each handler’s output is automatically passed to the next handler in the pipeline. The handlers are processed in reverse order to the way that you add them to the pipeline (i.e. the handler you add first is the handler “closest” to your service and gets inbound messages after all the other handlers you add have processed the message; for the same reason, the first handler you add will see any outbound messages as soon as they leave the service and before any of the handlers you’ve added to the pipeline see the message).

As an example, let’s say that you don’t want the services your hosting to process any messages with the HTTP Delete verb because you don’t allow deletes: you simply mark records as deleted and stop returning those records to the client. All requests to delete records should, you’ve decided, be sent with the HTTP Put verb because they’re actually updates to the record’s Deleted field. You could, of course, simply not provide a Delete method in your service–that would generate a return error message of “The requested resource does not support http method ‘GET’.” should someone send your service a Delete request. However, you may want to send a response that’s more informative to any client using the Delete verb (alternatively, you might want to log these Delete requests). You could add a Delete method to each of your services that performed those actions but it would be a better practice to centralize that site-wide utility code in one place: a message handler.

Adding Handlers

The first step is to add your message handler to the configuration object’s Handlers collection before passing the configuration object to the host. This code assumes that the handler is called PHVHandler:

hcfg = new HttpSelfHostConfiguration("");
PHVHandler hndlr = new PHVHandler();

If you want, you can limit a handler to processing only those requests for a single route. In that case, you pass the handler as the fifth parameter to the MapHttpRoute method (right after specifying any constraints on the route). This example adds a handler that will be used only for requests with “Customers” in the URL:

hcfg = new HttpSelfHostConfiguration("");
PHVHandler hndlr = new PHVHandler();
                         new { controller = "CustomerManagement" },

Creating a Handler

A handler is a class that inherits from DelegatingHandler (you’ll need using statements for  System.Net and System.Net.Http for the following code to work). Once you’ve added the class you must override its SendAsync method. The SendAsync method is called automatically by the Web API for every request to your service. The method is passed an HttpRequestMessage that holds all the data related to the request to your service (and a CancellationToken, which I’ll ignore in this post):

class PHVHandler: DelegatingHandler
 protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)

If the PHVHandler is the last one added to the pipeline, it will get the HttpRequestMessage before any other handler has modified it; if other handlers were add to the configuration object after this handler, then the HttpRequestMessage will show the results of any modifications that handlers earlier in the pipeline have made. If you’re doing test driven development, by the way, you can test your handler by instantiating an HttpRequestMessage object, setting its properties, and passing it your method–something that’s virtually impossible to do with the ASP.NET HttpContext object.

Your message processing code goes in the SendAsync method. The following code checks to see if the Method (the HTTP verb) associated with this request is a Delete and, if so, stops the message from proceeding up the pipeline. To short-circuit processing and return a message to the client you need to create two objects: an HttpResponseMessage object, specifying a return value with some content (Forbidden and a string, , in this case) and a TaskCompletionSource (because these are asynchronous methods, Task-related objects are used to wrap most of the method’s inputs and outputs). With the two objects created, use the TaskCompletionSource object’s SetResult method to pass the HttpResponseMessage to the TaskCompletionSource. Once the TaskCompletionSource is configured, you can return it which is what this code does:

if (request.Method == HttpMethod.Delete)
  HttpResponseMessage rsp = new HttpResponseMessage(HttpStatusCode.Forbidden);
  rsp.Content =new StringContent("Deletes not accepted--use Put"); 
  TaskCompletionSource<HttpResponseMessage> tkc = new TaskCompletionSource<HttpResponseMessage>();
  return tkc.Task;

However, if the message sent to your service isn’t using the Delete verb, it should be passed on to your service (or the next handler in the pipeline) for processing. To pass the message on up the pipeline, call the base version of the SendAsync method, passing the parameters you originally received in your version of the method:

return base.SendAsync(request, cancellationToken);

Calling the SendAsync method puts the message in the pipeline to go to the service. When your service finishes processing the message, the service will create a response message and send that back down through the pipeline. The object returned by the SendAsync method  in the previous code is the outbound response message created by the service (and, possibly, modified by any message handlers that the message has already passed through). You must return the result of the SendAsync method from your method to allow the message to continue through the pipeline back to the client. While it’s not obvious in this code, the SendAsync method is returning a Task object holding an HttpResponseMessage containing the service’s output message (again, the Task object is required to support asynchronous processing).

Altering the Inbound Message

However, a message handler can do more than just terminate processing. You can use a message handler to alter the message on its way up the pipeline. Rather than terminate processing when you see a Delete verb, for instance, you could change all Delete requests to Puts and let the messages continue on up the pipeline. As in the previous example, the following code first checks the inbound message to see if it’s a Delete. If it is, the code then alters the message before sending it on through the pipeline using the SendAsync method. The SendAsync method will (eventually, since its an asynchronous method) return the Task object holding the client’s HttpResponseMessage which you must return from your method:

if (request.Method == HttpMethod.Put)
 request.Method = HttpMethod.Put;
 return base.SendAsync(request, cancellationToken);

Altering the Outbound Message

Because the message passes through your handler on the way back to the client, you can also process the outbound message after it leaves the service and before it gets back to the client. This means waiting for your call to the base.SendAsync method to complete so that you can catch the outbound message–not a completely trivial task because SendAsync is an asynchronous method. If you’re working in .NET 4.0 then you’ll need to use the ContinueWith method to wait for the Task object returned from the SendAsync method. The ContinueWith method passes the Task returned from SendAsync to a lamba expression of your design. In that lambda expression you’ll typically want to extract the HttpResponseMessage from the Task and modify the message before letting the message continue through the pipeline. This example sets the StatusCode on the message to indicate that the request needs to be upgraded before returning the response (the Web API will take of wrapping the response in a Task):

return base.SendAsync(request, cancellationToken).ContinueWith((t) =>
  HttpResponseMessage rsp = t.Result;
  rsp.StatusCode = HttpStatusCode.UpgradeRequired;
  return rsp;

In .NET 4.5 you can take advantage of the await keyword which simplifies working with asynchronous methods–your code hardly looks asynchronous at all! First, you must add the async keyword to your method’s declaration:

class PHVHandler: DelegatingHandler
 async protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)

With the async keyword in place, you can use the await keyword to catch the output of the SendAsync method when it’s finally handed back to you. This example, as before, sets the StatusCode on the response message before returning the response:

HttpResponseMessage rsp = await base.SendAsync(request, cancellationToken);
rsp.StatusCode = HttpStatusCode.UpgradeRequired;
return rsp;

As you may have noticed, one of the nice features of self-hosting is that all your configuration code goes in one place: In the Windows Service that you’ll use to host your Web API service–which I find sort of convenient. I referred to Learning Tree’s course on creating .NET services (including the ASP.NET Web API) in my last post but I should also have mentioned Learning Tree’s course on deciding what services you need and how they should work together, Service-Oriented Architecture (SOA): A Comprehensive Hands-On Introduction (especially because I wrote the course).

Peter Vogel

4 Responses to “Processing Messages in a Self-Hosted Web API Service”

  1. 1 kofidad May 28, 2013 at 10:32 pm


    I tried to secure my Self-Hosted Web API Service, and I use the example of WCF Service like below

    public class MyCustomUserNameValidator : UserNamePasswordValidator
    public override void Validate(string userName, string password)
    if (string.Equals(userName, “Nick”, StringComparison.OrdinalIgnoreCase) && password == “Test123”) return;

    throw new FaultException(string.Format(“Wrong username ({0}) or password “, userName));

    class Program
    static void Main(string[] args)
    var config = new HttpSelfHostConfiguration(“http://localhost:8080”);
    config.UserNamePasswordValidator = new MyCustomUserNameValidator();
    “API Default”, “api/{controller}/{id}”,
    new { id = RouteParameter.Optional });

    using (HttpSelfHostServer server = new HttpSelfHostServer(config))
    Console.WriteLine(“Press Enter to quit.”);

    But it’s not worked when user input wrong username or password, the error message told me that Exception was not handled.

    Could you please give me any idea about this?


    Nick Lee

    • 2 Peter Vogel, Learning Tree May 30, 2013 at 12:23 pm

      Nick, I’m not sure that you have a problem: If the validation fails (i.e. if you submit a bad username/password combination) your validator should throw an exception. If your call to the method on the WCF service isn’t wrapped in a Try…Catch block then you’ll get an “Exception not handled” message at your client. Is that, perhaps, the problem?

Comments are currently closed.

Learning Tree International

.NET & Visual Studio Courses

Learning Tree offers over 210 IT training and Management courses, including a full curriculum of .NET training courses.

Free White Papers

Questions on current IT or Management topics? Access our Complete Online Resource Library of over 65 White Papers, Articles and Podcasts

Enter your email address to subscribe to this blog and receive notifications of new posts by e-mail.

Join 29 other followers

Follow Learning Tree on Twitter


Do you need a customized .NET training solution delivered at your facility?

Last year Learning Tree held nearly 2,500 on-site training events worldwide. To find out more about hosting one at your location, click here for a free consultation.
Live, online training

%d bloggers like this: