Http Client 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.

Windows 10 requirements

Examples

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

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 » » element. Then use the character encoding specified (» «, 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

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

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

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

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Windows. Web. Http Namespace

Provides a modern HTTP client API for UWP app.

Classes

Provides HTTP content that uses a buffer.

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.

Provides a set of properties and methods to manage an HTTP cookie.

Provides a collection container for instances of the HttpCookie class.

Add or delete an HttpCookie or view the cookies associated with an app.

Provides HTTP content that uses name/value data encoded with the application/x-www-form-urlencoded MIME type.

Combines the final buffer result along with the following: the original HTTP request, the resulting HTTP response (if any), an extended error value, and a succeeded indication.

Combines the final input stream result along with following: the original HTTP request, the resulting HTTP response (if any), an extended error value, and a succeeded indication.

Combines the final string result along with the following: the original HTTP request, the resulting HTTP response (if any), an extended error value, and a succeeded indication.

Retrieves standard HTTP methods such as GET and POST and creates new HTTP methods.

Provides HTTP content that uses the multipart/* MIME type.

Provides HTTP content that uses the multipart/form-data MIME type.

Represents an HTTP request message including headers.

Combines the original HTTP request along with the following: the resulting HTTP response (if any), an extended error value, and a succeeded indication.

Represents an HTTP response message including headers, the status code, and data.

Provides HTTP content that uses a stream.

Provides HTTP content that uses a string.

Provides information about the underlying transport used by the HTTP connection.

Structs

Contains status information on the progress of an HttpClient operation.

Interfaces

Provides a base interface for an HTTP entity body and content headers.

Enums

Indicates whether asynchronous HttpClient operations are considered completed when all of the response is read, or when just the headers are read.

Indicates the step in the progress for an HTTP connection.

Indicates the source of the data received in the HttpResponseMessage.

Contains the values of status codes defined for HTTP in the response to an HTTP request.

Represents the HTTP protocol version.

Examples

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

Remarks

The Windows.Web.Http namespace and the related Windows.Web.Http.Headers and Windows.Web.Http.Filters namespaces provide a programming interface for UWP app that target HTTP and REST services. This features of this new HTTP API are designed to be in compliance with HTTP as defined in RFC 2616 by the IETF. The new HTTP API provides consistent support in JavaScript, C#, VB.NET, and C++ for developers.

This new API replaces the use of three different APIs with differing features that previously were needed for each language projection in WindowsВ 8.

Classes in the Windows.Web.Http and related namespaces are targeted at all levels of HTTP and REST development:

• Basic HTTP developers
• Site-specific HTTP library developers
• Advanced HTTP developers

For basic HTTP developers, the new API has a simple interface to handle the most common tasks and sensible defaults for authentication that should work in most environments. For library developers, the consistent object model and multiple language support means you can write a library once for developers in all languages. For advanced HTTP developers, the new API includes a rich set of capabilities.

The Windows.Web.Http namespace and the related namespaces provide these components:

• HttpClient — the main class that sends and receives requests over HTTP.
• HttpRequestMessage — HTTP request messages defined in RFC 2616.
• HttpResponseMessage — HTTP response messages defined in RFC 2616.

The contents of an HTTP message corresponds to the entity body defined in RFC 2616. Several classes and an interface in the Windows.Web.Http namespace can be used for HTTP content, including:

• IHttpContent — A base interface for developers to create their own content objects. It represents an HTTP entity body and content headers. This interface has methods that get and set the actual content data. It also provides properties that get and set content related headers.
• HttpBufferContent — HTTP content that uses a buffer.
• HttpFormUrlEncodedContent — HTTP content that uses name/value tuples encoded with the application/x-www-form-urlencoded MIME type.
• HttpMultipartContent — HTTP content that uses multipart/* MIME type.
• HttpMultipartFormDataContent — HTTP content that uses the encoded multipart/form-data MIME type.
• HttpStreamContent — HTTP content that uses a stream. This content type is used by the HTTP GET method to receive data and the HTTP POST method to upload data.
• HttpStringContent — HTTP content that uses a string.

Classes in the Windows.Web.Http.Headers namespace represent HTTP headers defined in RFC 2616. HTTP headers are associated with HttpRequestMessage and HttpResponseMessage as properties that are retrieved or set.

Classes in the Windows.Web.Http namespace can use filters based on the classes in the Windows.Web.Http.Filters namespace. Filters provide handlers to help with common HTTP service issues. Filters can be chained together in a sequence to address more complex HTTP service issues. Several ready-to-use filters are included with WindowsВ 8.1 to help library developers fix common HTTP service issues. These filters include handlers for monitored network connections and retry. Library developers can write their own filters for site-specific issues (for example, a site might use the 503 (Server Unavailable) response to indicate the request should be retried).

If an app that uses the Windows.Web.Http namespace and the related Windows.Web.Http.Headers and Windows.Web.Http.Filters namespaces 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 gets 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 HttpClient.