HttpClient is a modern HTTP client for .NET. It provides a flexible and extensible API for accessing all things exposed through HTTP. HttpClient has been available for a while as part of WCF Web API preview 6 but is now shipping as part of ASP.NET Web API and directly in .NET 4.5. You can also download it using NuGet – we just use the following three NuGet packages in this blog:
- System.Net.Http: The main NuGet package providing the basic HttpClient and related classes
- System.Net.Http.Formatting: Adds support for serialization, deserialization as well as for many additional features building on top of System.Net.Http
- System.Json: Adds support for JsonVaue which is a mechanism for reading and manipulating JSON documents
In case you haven’t played with HttpClient before, here is a quick overview of how it works:
HttpClient is the main class for sending and receiving HttpRequestMessages and HttpResponseMessages. If you are used to using WebClient or HttpWebRequest then it is worth noting that HttpClient differs in some interesting ways – here’s how to think about an HttpClient:
- An HttpClient instance is the place to configure extensions, set default headers, cancel outstanding requests and more.
- You can issue as many requests as you like through a single HttpClient instance.
- HttpClients are not tied to particular HTTP server or host; you can submit any HTTP request using the same HttpClient instance.
- You can derive from HttpClient to create specialized clients for particular sites or patterns
- HttpClient uses the new Task-oriented pattern for handling asynchronous requests making it dramatically easier to manage and coordinate multiple outstanding requests.
Kicking the Tires
We will be diving into lots of details in the near-future around features, extensibility, serialization, and more but let’s first kick the tires by sending a request to the World Bank Data Web API. Please see List of ASP.NET Web API and HttpClient Samples for the complete sample solution. The service provides all kinds of information about countries around the world. It exposes the data both as XML and as JSON but in this sample we download it as JSON and use JsonValue to traverse the request for interesting information without having to create a CLR type on the client side:
The HttpResponseMessage contains information about the response including the status code, headers, and any entity body. The entity body is encapsulated in HttpContent which captures content headers such as Content-Type, Content-Encoding, etc. as well as the actual content. The content can be read using any number of ReadAs* methods depending on how you would like to consume the data. In the sample above, we read the content as JsonArray so that we can navigate the data and get the information we want.
Trying out .Net 4.5
An exciting feature in .NET 4.5 is the language support for asynchronous programming that makes programming Tasks even easier. Using the new async and await language keywords, we can replace the “ContinueWith” pattern in the sample above and get something that looks very clean like this: