Blog

ASP.NET Web API: Client-Side Pipeline

Excerpt by Phil Ledgerwood | March 01, 2013

Microsoft .NET Framework technologies that support a request-response pattern typically use a pipeline, which is a sequence of events that fire to process a request and send back an appropriate response.

Pipelines are important because they allow developers to run code at various stages of processing a request.

The ASP.NET Web API has a pipeline and, by taking advantage of how the API processes HTTP messages, you can easily add some very useful functionality. The Web API has a processing pipeline for both the client and >the server, and this article will focus on the Client-Side Pipeline!

Client-Side Pipeline

The Web API pipeline has two "sides" to it: the client-side and the server-side. Understanding the client-side pipeline is useful as virtually any application can harness the client-side objects to make calls to a Web API. The objects available in the client-side pipeline are especially useful when creating applications that need to access Web API services directly from application code and consume the results.

HttpClient

The HttpClient object represents the client making the request. You can instantiate the object in code, use it to generate an HttpRequestMessage, and send it asynchronously to a URL to be handled by a Web API application. The HttpClient then receives an HttpResponseMessage and handles the contentsaccordingly.

The HttpClient only has four properties, and its methods are primarily concerned with various ways to send an HTTP request and receive a response. The HttpClient is somewhat analogous to AJAX frameworks that essentially facilitate sending requests and receiving responses, leaving it to other code to unpack the response and use the data meaningfully. In the same way, the bulk of the logic dealing with a service response will operate on the HttpResponseMessage object, which will contain the actual data that the requestor needed.

NOTE: With the popularity of various AJAX libraries, many applications will make client-side calls to the Web API directly, but if you have a need to make these calls using server-side code, the HttpClient object will beuseful.

HttpMessageHandler

The HttpMessageHandler object sends the HttpRequestMessage generated by the HttpClient to the right place and listens for an HttpResponseMessage. When a response is received, the HttpMessageHandler is the first object to process it before handing it back to the HttpClient.

HttpMessageHandler is actually a base class for all such handlers. The default implementation for the client-side pipeline is the HttpClientHandler, which satisfies most basic usages of the Web API. However, you are free to write your own implementation of the HttpMessageHandler. This might be useful if you want to perform a uniform task for every request or response that comes through, such as adding a security key to the header or examining incoming responses for a correct format.

You must use caution when adding custom code to your HttpMessageHandler on the client-side, however. The idea behind a Web API service is that the functionality can be called by a wide variety of clients. Putting too much logic about the transaction on the client-side may require replicating that code on every client that uses the service. This is something that you should generally avoid, or at the very least, clients should have other ways to provide that information to the service other than requiring a custom HttpMessageHandler on the client-side.

This post is an excerpt from the online courseware for our ASP.NET Web API HTTP Pipeline course written by expert Philip Ledgerwood.