Portable HttpClient for .NET Framework and Windows Phone

Many of you told us you want HttpClient for Windows Phone. In this post, Alok Shriram, a Program Manager on the .NET Framework team , will talk about an important announcement of ours. –Immo

Today we are announcing our Beta release of the portable version of HttpClient, the modern networking API. The HttpClient library is a set of APIs for .NET which provide a flexible and extensible way to access all things exposed through HTTP.

This release of HttpClient adds support for the following platforms:

  • .NET framework 4.0
  • Windows Phone 7.5 and higher
  • Portable class libraries

What does HttpClient do?

HttpClient is a part of .NET Framework 4.5 and Windows Store apps that provides developers an extremely easy way to connect with services across the internet including REST-based services. In fact, the methods exposed by HttpClient are the same verbs the HTTP protocol uses to communicate like GET/PUT/POST/DELETE.

In order to get some content from a web server say www.contoso.com we can write the following simple lines of code

 HttpClient httpClient = new HttpClient();
string responseBodyAsText = await httpClient.GetStringAsync(“www.contoso.com”);

…and get a response back from a web service. Obviously this is the simplest example, and the HttpClient library has many more feature and functions.

Why a portable HttpClient?

Before releasing this package, the HttpClient class was not available on all platforms. This complicated the experience for developers trying to share code across Microsoft platforms. For instance, a developer who wanted to target both the Windows Phone and Windows Store app platforms would need to write networking logic using the HttpWebRequest and HttpWebResponse classes for networking, since it was the networking abstraction available in portable. However HttpClient is a much simpler programming interface to code against, in addition to being very close to HTTP semantics, which makes it more intuitive. In addition HttpClient exposes the new Task based asynchronous methods, which makes writing responsive and performant UI applications across all platforms a lot simpler.

In order to bridge this gap we have created a portable class library for HttpClient that will allow developers to consume HttpClient on Windows Phone 7.5 and higher, Windows Store apps, and .NET Framework 4.0 and higher. In addition it also enables other portable library developers who require networking support to use HttpClient while targeting all or a subset of the supported platforms.

What do I need?

In order to use this release of HttpClient you need to ensure that you have two things.

  • Visual Studio 2010 (for .NET 4.0 Windows Phone 7.1) or Visual Studio 2012 (required for .NET 4.5, Windows Store and Windows Phone 8).
  • The NuGet package manager version 2.1 or higher.

To use the HttpClient package, right click on your solution, go to the Manage Nuget Packages dialog, search for Id Microsoft.Net.Http, and make sure “Include Prerelease” is turned on.

 

Accept the license terms and agreements and NuGet will install the right packages to your folder.

Writing a Cross platform App

The full surface area for HttpClient as shipped in .NET Framework 4.5 is documented here. This package includes support for that surface area, and introduces a few new methods that are not currently in the documentation above.These new APIs are used to help determine which networking capabilities are supported on the platform on which you’re running, since not all platforms support all capabilities. The new APIs added are:

 public static bool SupportsPreAuthenticate(this HttpClientHandler handler);
public static bool SupportsProtocolVersion(this HttpClientHandler handler);
public static bool SupportsTransferEncodingChunked(this HttpClientHandler handler);

In order to write a portable piece of code which would work across all the supported platforms, code that would have previously been

 HttpClientHandler handler = new HttpClientHandler();
httpClient = new HttpClient(handler);
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, resourceAddress);
request.Content = streamContent;
request.Headers.TransferEncodingChunked = true;
HttpResponseMessage response = await httpClient.SendAsync(request);

Will now change to

 HttpClientHandler handler = new HttpClientHandler();
httpClient = new HttpClient(handler);
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, resourceAddress);
request.Content = streamContent;
if (handler.SupportsTransferEncodingChunked())
{
 request.Headers.TransferEncodingChunked = true;
}
HttpResponseMessage response = await httpClient.SendAsync(request);

Using HttpClient on .NET Framework 4.0 or Windows Phone 7.5

If you are writing a cross platform app targeting .Net 4.0 or the windows phone and write the code that you had written above you will get a compile error.

“Cannot await System.Threading.Task<HttpRequestMessage>”

This is because .Net 4.0 and Windows Phone 7.5 did not support the async/await keywords.In order to fix this add a reference to the Microsoft.Bcl.Async nuget package, which adds the support for Async and Await in down level platforms.To read more about this release go here.

 

This was one of the higher rated user voice requests, so thanks for taking the time to engage with us. Please note this package is marked as prerelease software – that is, there are some rough edges to be expected. We’ve published the known issues here. As usual, we’d like to know if you run into any issues when using it. Simply use the comment section under this blog post.

Happy “Get”ting!