HttpClient Class

Definition

Sends HTTP requests and receives HTTP responses from a resource identified by a URI. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

public ref class HttpClient sealed : IClosable, IStringable
/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.Activatable(Windows.Web.Http.IHttpClientFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class HttpClient final : IClosable, IStringable
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(Windows.Web.Http.IHttpClientFactory, 65536, "Windows.Foundation.UniversalApiContract")]
class HttpClient final : IClosable, IStringable
[Windows.Foundation.Metadata.Activatable(65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Web.Http.IHttpClientFactory), 65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class HttpClient : System.IDisposable, IStringable
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Web.Http.IHttpClientFactory), 65536, "Windows.Foundation.UniversalApiContract")]
public sealed class HttpClient : System.IDisposable, IStringable
function HttpClient(filter)
Public NotInheritable Class HttpClient
Implements IDisposable, IStringable
Inheritance
Object Platform::Object IInspectable HttpClient
Attributes
Implements

Windows requirements

Device family
Windows 10 (introduced in 10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v1.0)

Examples

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

using System;

var uri = new System.Uri("http://www.bing.com");
using (var httpClient = new Windows.Web.Http.HttpClient())
{
    // Always catch network exceptions for async methods
    try
    {
        string result = await httpClient.GetStringAsync(uri);
    }
    catch (Exception ex)
    {
        // Details in ex.Message and ex.HResult.
    }
}
// Having exited the scope of the using statement, httpClient.Dispose() will be called
// automatically, thus freeing up system resources (the underlying socket, and memory
// used for the object).
#include "winrt/Windows.Foundation.h"
#include "winrt/Windows.Web.Http.h"
using namespace winrt;

Windows::Foundation::IAsyncAction HttpClientExample()
{
    Windows::Foundation::Uri uri{ L"http://www.bing.com" };
    Windows::Web::Http::HttpClient httpClient{};

    // Always catch network exceptions for async methods
    try
    {
        auto response{ co_await httpClient.GetStringAsync(uri) };
    }
    catch (winrt::hresult_error const& ex)
    {
        // Details in ex.message() and ex.to_abi().
    }

    // The destructor of HttpClient frees system resources
    // (the underlying socket, and memory used for the object).
}
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++/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.

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# and C++/WinRT that shows how to use HttpClient to connect to an HTTP server, see HttpClient.

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.

Version history

Windows version SDK version Value added
1903 18362 TryDeleteAsync
1903 18362 TryGetAsync(Uri)
1903 18362 TryGetAsync(Uri,HttpCompletionOption)
1903 18362 TryGetBufferAsync
1903 18362 TryGetInputStreamAsync
1903 18362 TryGetStringAsync
1903 18362 TryPostAsync
1903 18362 TryPutAsync
1903 18362 TrySendRequestAsync(HttpRequestMessage)
1903 18362 TrySendRequestAsync(HttpRequestMessage,HttpCompletionOption)

Constructors

HttpClient()

Initializes a new instance of the HttpClient class. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

HttpClient(IHttpFilter)

Initializes a new instance of the HttpClient class with a specific filter for handling HTTP response messages. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

Properties

DefaultPrivacyAnnotation
DefaultRequestHeaders

Gets a collection of headers that should be sent with each request. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

Methods

Close()

Closes the HttpClient instance and releases allocated resources. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

DeleteAsync(Uri)

Send a DELETE request to the specified Uri as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

GetAsync(Uri)

Send a GET request to the specified Uri as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

GetAsync(Uri, HttpCompletionOption)

Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

GetBufferAsync(Uri)

Send a GET request to the specified Uri and return the response body as a buffer in an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

GetInputStreamAsync(Uri)

Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

GetStringAsync(Uri)

Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

PostAsync(Uri, IHttpContent)

Send a POST request to the specified URI as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

PutAsync(Uri, IHttpContent)

Send a PUT request to the specified Uri as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

SendRequestAsync(HttpRequestMessage)

Send an HTTP request as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

SendRequestAsync(HttpRequestMessage, HttpCompletionOption)

Send an HTTP request with an HTTP completion option as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

ToString()

Returns a string that represents the current HttpClient object. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

TryDeleteAsync(Uri)

Send a DELETE request to the specified Uri as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

TryGetAsync(Uri)

Sends a GET request to the specified Uri as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

TryGetAsync(Uri, HttpCompletionOption)

Sends a GET request to the specified Uri as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

TryGetBufferAsync(Uri)

Send a GET request to the specified Uri and return the response body as HttpGetBufferResult with an IBuffer value in an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

TryGetInputStreamAsync(Uri)

Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

TryGetStringAsync(Uri)

Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

TryPostAsync(Uri, IHttpContent)

Sends a POST request to the specified Uri as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

TryPutAsync(Uri, IHttpContent)

Sends a PUT request to the specified Uri as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

TrySendRequestAsync(HttpRequestMessage)

Sends an HTTP request to the specified Uri as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

TrySendRequestAsync(HttpRequestMessage, HttpCompletionOption)

Sends an HTTP request with a completion option to the specified Uri as an asynchronous operation. For programming guidance for the HttpClient class, and code examples, see the HttpClient conceptual topic.

Applies to

See also