Before I go into any details I thought it would be valuable to give some basic examples of how to use the HTTPClient.

Retrieve some HTTP content from an URL

var client = new HttpClient();
var response = client.Get("http://example.org");

Post some content to an Url

var client = new HttpClient();
var content = HttpContent.Create("This is some string content");
var response = client.Post("http://example.com", content);

Authenticated get

var client = new HttpClient();
client.DefaultHeaders.Authorization = Credential.CreateBasic("user", "password");
var response = client.Get("http://example.org");

and if you need to provide some kind of custom authentication scheme you can simply create credential like this

client.DefaultHeaders.Authorization = new Credential(“My secure authentication header”);
 

Interestingly, the methods Get and Post are not actually members of the HttpClient class.  They are extension methods that simply call one of the Send methods on the HttpClient class.  If it is more appropriate you can also call the Send methods directly. As you will see, there are plenty of overloads to suit your needs:

 
public HttpResponseMessage Send(HttpMethod method)
public HttpResponseMessage Send(HttpMethod method, Uri uri)
public HttpResponseMessage Send(HttpMethod method, Uri uri, RequestHeaders headers)
public HttpResponseMessage Send(HttpMethod method, Uri uri, HttpContent content)
public HttpResponseMessage Send(HttpMethod method, string uri)
public HttpResponseMessage Send(HttpMethod method, string uri, RequestHeaders headers)
public HttpResponseMessage Send(HttpMethod method, string uri, HttpContent content)
public HttpResponseMessage Send(HttpMethod method, string uri, RequestHeaders headers, HttpContent content)
public HttpResponseMessage Send(HttpMethod method, Uri uri, RequestHeaders headers, HttpContent content)
 

I like this approach because it provides a host of easy to call helper methods that are all routed through one of these Send methods. 

Another major advantage of the HttpClient library over the HttpWebRequest class is related to the RequestHeaders class.  All of the Http header values have been wrapped with some kind of helper class that significantly eases the process of setthing header values.

Here are a few random examples of setting header information that pulled from the unit tests:

var req = new RequestHeaders();
req.Accept.Add(StringWithOptionalQuality.Parse("audio/*; q=0.2"));

req.Allow.Add("GET");
req.Allow.Add("POST"); 

var cc = new CacheControl();
cc.MaxAge = TimeSpan.FromSeconds(1);
cc.MaxStale = true;
cc.MaxStaleLimit = TimeSpan.FromSeconds(2);
cc.MinFresh = TimeSpan.FromSeconds(3);
cc.MustRevalidate = true;
cc.NoCache = true;

req.CacheControl = cc;

In addition to these headers that have strongly typed classes there is also the nifty Parse() function that is on both the request and response header collections.

var h = RequestHeaders.Parse("Pragma: LinkBW=2147483647, AccelBW=1048576, AccelDuration=5000"); 

var resp = ResponseHeaders.Parse(
                @"Set-Cookie: mkt1=norm=US; domain=.live.com; path=/
                    Set-Cookie: AFORM=NOFORM; expires=Mon, 20-Jul-2015 23:59:59 GMT; path=/".Trim());

var h = RequestHeaders.Parse(
               @"Accept-Charset: iso-8859-5, unicode-1-1;q=0.8
           Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0
           Accept-Language: da, en-gb;q=0.8, en;q=0.7");

var h = ResponseHeaders.Parse(@"WWW-Authenticate: Digest realm=""testrealm@host.com"",
                qop=""auth,auth-int"",
                nonce=""dcd98b7102dd2f0e8b11d0f600bfb0c093"",
                opaque=""5ccc069c403ebaf9f0171e9517f40e41""");

Who wants to write and test the code necessary to parse this stuff?  Not me, that’s for sure. Hopefully this has provided a taste for what this library is capable of and over the next few weeks I plan on writing a number of other posts that cover other interesting areas of the Microsoft.Http namespace.  To see where I am up to, see the summary page here