Windows.Web.Http Namespace

Reference

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Provides a modern HTTP client API for UWP app.

Classes

HttpBufferContent	Provides HTTP content that uses a buffer.
HttpClient	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.
HttpCookie	Provides a set of properties and methods to manage an HTTP cookie.
HttpCookieCollection	Provides a collection container for instances of the HttpCookie class.
HttpCookieManager	Add or delete an HttpCookie or view the cookies associated with an app.
HttpFormUrlEncodedContent	Provides HTTP content that uses name/value data encoded with the application/x-www-form-urlencoded MIME type.
HttpGetBufferResult	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.
HttpGetInputStreamResult	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.
HttpGetStringResult	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.
HttpMethod	Retrieves standard HTTP methods such as GET and POST and creates new HTTP methods.
HttpMultipartContent	Provides HTTP content that uses the multipart/* MIME type.
HttpMultipartFormDataContent	Provides HTTP content that uses the multipart/form-data MIME type.
HttpRequestMessage	Represents an HTTP request message including headers.
HttpRequestResult	Combines the original HTTP request along with the following: the resulting HTTP response (if any), an extended error value, and a succeeded indication.
HttpResponseMessage	Represents an HTTP response message including headers, the status code, and data.
HttpStreamContent	Provides HTTP content that uses a stream.
HttpStringContent	Provides HTTP content that uses a string.
HttpTransportInformation	Provides information about the underlying transport used by the HTTP connection.

Structs

HttpProgress

Contains status information on the progress of an HttpClient operation.

Interfaces

IHttpContent

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

Enums

HttpCompletionOption	Indicates whether asynchronous HttpClient operations are considered completed when all of the response is read, or when just the headers are read.
HttpProgressStage	Indicates the step in the progress for an HTTP connection.
HttpResponseMessageSource	Indicates the source of the data received in the HttpResponseMessage.
HttpStatusCode	Contains the values of status codes defined for HTTP in the response to an HTTP request.
HttpVersion	Represents the HTTP protocol version.

Examples

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

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

// Note: the URI constructor will throw an exception
// if the string passed is not a valid URI
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 (Exception ex)
{
    // 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();

#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;

// Note: the URI constructor will throw an exception
// if the string passed is not a valid URI
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 (Exception ^ ex) 
{
    // 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).

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.

WinJS.xhr for JavaScript
HttpClient in the System.Net.Http namespace for C# and VB.
IXMLHTTPRequest2 for C++

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.

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.

Dela via