Skip to main content
HttpClient class

Applies to Windows and Windows Phone

Sends HTTP requests and receives HTTP responses from a resource identified by a URI.

Syntax


var httpClient = new Windows.Web.Http.HttpClient(iHttpFilter);
var httpClient = new Windows.Web.Http.HttpClient();

public sealed class HttpClient : IDisposable,
    IStringable

Public NotInheritable Class HttpClient
    Implements IDisposable, _
    IStringable

public ref class HttpClient sealed : IClosable,
    IStringable

Attributes

[ DualApiPartition()]
[ MarshalingBehavior(Agile)]
[ Threading(Both)]
[ Version(0x06030000)]

Members

The HttpClient class has these types of members:

Constructors

The HttpClient class has these constructors.

ConstructorDescription
HttpClient() Initializes a new instance of the HttpClient class.
HttpClient(IHttpFilter) Initializes a new instance of the HttpClient class with a specific filter for handling HTTP response messages.

 

Methods

The HttpClient class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

MethodDescription
Close [C++, JavaScript]Closes the HttpClient instance and releases allocated resources.
DeleteAsync Send a DELETE request to the specified Uri as an asynchronous operation.
Dispose [C#, VB]Performs tasks associated with freeing, releasing, or resetting unmanaged resources.
GetAsync(Uri) Send a GET request to the specified Uri as an asynchronous operation.
GetAsync(Uri, HttpCompletionOption) Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.
GetBufferAsync Send a GET request to the specified Uri and return the response body as a buffer in an asynchronous operation.
GetInputStreamAsync Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.
GetStringAsync Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.
PostAsync Send a POST request to the specified Uri as an asynchronous operation.
PutAsync Send a PUT request to the specified Uri as an asynchronous operation.
SendRequestAsync(HttpRequestMessage) Send an HTTP request as an asynchronous operation.
SendRequestAsync(HttpRequestMessage, HttpCompletionOption) Send an HTTP request with an HTTP completion option as an asynchronous operation.
ToString Returns a string that represents the current HttpClient object.

 

Properties

The HttpClient class has these properties.

PropertyAccess typeDescription

DefaultRequestHeaders

Read-onlyGets a collection of headers that should be sent with each request.

 

Remarks

The HttpClient class instance acts as a session to send HTTP requests and receive responses. An HttpClient instance is a collection of settings that apply to all requests executed by that instance. In addition, every HttpClient instance uses its own connection pool, isolating its requests from requests executed by other HttpClient instances.

The HttpClient also acts as a class to use with filters for more specific HTTP clients. An example would be an HttpClientFilter that provides additional methods specific to a social network service (a GetFriends method, for instance).

If an app using HttpClient and related classes in the Windows.Web.Http namespace downloads large amounts of data (50 megabytes or more), then the app should stream those downloads and not use the default buffering. If the default buffering is used the client memory usage will get very large, potentially resulting in reduced performance.

For sample code in C#/VB/C++ and XAML that shows how to use HttpClient to connect to an HTTP server, see Connecting to an HTTP server using Windows.Web.Http.HttpClient (XAML).

For sample code in JavaScript and HTML that shows how to use HttpClient to connect to an HTTP server, see Connecting to an HTTP server using Windows.Web.Http(HTML).

Examples

The following sample code shows how to GET content from a Web server as a string.

var uri = new Uri("http://example.com/datalist.aspx");
var httpClient = new HttpClient();

// Always catch network exceptions for async methods
httpClient.GetStringAsync(uri).done(function () {
    // get completed
    }, onError);


function onError(reason) {
    // Details in reason.Message and ex.HResult.       
}

// Once your app is done using the HttpClient object call close to 
// free up system resources (the underlying socket and memory used for the object)
// httpClient.close();

using System;
using Windows.Foundation;
using Windows.Web.Http;

var uri = new Uri("http://example.com/datalist.aspx");
var httpClient = new HttpClient();

// Always catch network exceptions for async methods
try 
{
    var result = await httpClient.GetStringAsync(uri);
}
catch 
{
    // Details in ex.Message and ex.HResult.       
}

// Once your app is done using the HttpClient object call dispose to 
// free up system resources (the underlying socket and memory used for the object)
httpclient.Dispose();


using namespace Windows::Foundation;
using namespace Windows::Web::Http;

uri = ref new Uri("http://example.com/datalist.aspx");
httpClient = ref new HttpClient();

// Always catch network exceptions for async methods
try 
{
    httpClient->GetStringAsync(uri);
}
catch 
{
    // Details in ex.Message and ex.HResult.       
}

// In C++ and CX, the system resources used by httpClient object are released 
// when the object falls out of scope or by the destructor (delete operator)

The HttpClient class is often used by an app to download and then parse text. It is possible that the character encoding specified in the Content-Type header by an HTTP server does not match the character encoding of the HTTP response body (the XML encoding in an XML document, for example). One way to use HttpClient with text is to call the GetStringAsync method and pass the returned string to the text parser. However, this can result in errors if the Content-Type is not a type expressible as a string. A reliable way to use HttpClient with an XML parser is to call the GetBufferAsync method and parse the buffer for the "<?xml>" element. Then use the character encoding specified ("<xmlversion="1.0" encoding="UTF-8"?>", for example) to parse the HTTP response body. For other text formats, similar methods can be used where the app scans the initial part of the HTTP response body to determine the character encoding used.

Requirements

Minimum supported client

Windows 8.1 [Windows Store apps, desktop apps]

Minimum supported server

Windows Server 2012 R2 [Windows Store apps, desktop apps]

Minimum supported phone

Windows Phone 8.1 [Windows Phone Silverlight 8.1 and Windows Runtime apps]

Namespace

Windows.Web.Http
Windows::Web::Http [C++]

Metadata

Windows.winmd

See also

Other resources
Connecting to an HTTP server using Windows.Web.Http.HttpClient (XAML)
Connecting to an HTTP server using Windows.Web.Http(HTML)
Handling exceptions in network apps
Reference
IClosable
IStringable
Object
System.Uri
Windows.Foundation.Uri
Windows.Web.Http
Windows.Web.Http.Filters
Windows.Web.Http.Headers
Samples
HttpClient Sample