HttpClient HttpClient HttpClient HttpClient Class

Definition

Provides a base class for sending HTTP requests and receiving HTTP responses from a resource identified by a URI.

public ref class HttpClient : System::Net::Http::HttpMessageInvoker
public class HttpClient : System.Net.Http.HttpMessageInvoker
type HttpClient = class
    inherit HttpMessageInvoker
Public Class HttpClient
Inherits HttpMessageInvoker
Inheritance

Examples

static async Task Main()
{
   // Create a New HttpClient object.
   HttpClient client = new HttpClient();
 
   // Call asynchronous network methods in a try/catch block to handle exceptions
   try	
   {
      HttpResponseMessage response = await client.GetAsync("http://www.contoso.com/");
      response.EnsureSuccessStatusCode();
      string responseBody = await response.Content.ReadAsStringAsync();
      // Above three lines can be replaced with new helper method below
      // string responseBody = await client.GetStringAsync(uri);

      Console.WriteLine(responseBody);
   }  
   catch(HttpRequestException e)
   {
      Console.WriteLine("\nException Caught!");	
      Console.WriteLine("Message :{0} ",e.Message);
   }

   // Need to call dispose on the HttpClient object
   // when done using it, so the app doesn't leak resources
   client.Dispose(true);
}

The preceding code example uses an async Task Main() entry point. That feature requires C# 7.1 or later.

Remarks

The HttpClient class instance acts as a session to send HTTP requests. An HttpClient instance is a collection of settings applied 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 base class for more specific HTTP clients. An example would be a FacebookHttpClient providing additional methods specific to a Facebook web service (a GetFriends method, for instance). Derived classes should not override the virtual methods on the class. Instead, use a constructor overload that accepts HttpMessageHandler to configure any pre- or post-request processing instead.

By default on .NET Framework and Mono, HttpWebRequest is used to send requests to the server. This behavior can be modified by specifying a different channel in one of the constructor overloads taking a HttpMessageHandler instance as parameter. If features like authentication or caching are required, WebRequestHandler can be used to configure settings and the instance can be passed to the constructor. The returned handler can be passed to one of the constructor overloads taking a HttpMessageHandler parameter.

If an app using HttpClient and related classes in the System.Net.Http namespace intends to download 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 substantially reduced performance.

The following methods are thread safe:

  1. CancelPendingRequests

  2. DeleteAsync

  3. GetAsync

  4. GetByteArrayAsync

  5. GetStreamAsync

  6. GetStringAsync

  7. PostAsync

  8. PutAsync

  9. SendAsync

HttpClient is intended to be instantiated once and re-used throughout the life of an application. Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. This will result in SocketException errors. Below is an example using HttpClient correctly.

public class GoodController : ApiController
{
    // OK
    private static readonly HttpClient HttpClient;

    static GoodController()
    {
        HttpClient = new HttpClient();
    }
}

The HttpClient is a high-level API that wraps the lower-level functionality available on each platform where it runs.

On each platform, HttpClient tries to use the best available transport:

Host/Runtime Backend
Windows/.NET Framework HttpWebRequest
Windows/Mono HttpWebRequest
Windows/UWP Windows native WinHttpHandler (HTTP 2.0 capable)
Windows/.NET Core Windows native WinHttpHandler (HTTP 2.0 capable)
Android/Xamarin Selected at build-time. Can either use HttpWebRequest or be configured to use Android's native HttpURLConnection
iOS, tvOS, watchOS/Xamarin Selected at build-time. Can either use HttpWebRequest or be configured to use Apple's NSUrlSession (HTTP 2.0 capable)
macOS/Xamarin Selected at build-time. Can either use HttpWebRequest or be configured to use Apple's NSUrlSession (HTTP 2.0 capable)
macOS/Mono HttpWebRequest
macOS/.NET Core libcurl-based HTTP transport (HTTP 2.0 capable)
Linux/Mono HttpWebRequest
Linux/.NET Core libcurl-based HTTP transport (HTTP 2.0 capable)

Users can also configure a specific transport for HttpClient by invoking the HttpClient constructor that takes an HttpMessageHandler.

HttpClient and .NET Core

Starting with .NET Core 2.1, the System.Net.Http.SocketsHttpHandler class instead of HttpClientHandler provides the implementation used by higher-level HTTP networking classes such as HttpClient. You can configure your application to use the older System.Net.Http.HttpClientHandler instead by calling the SetSwitch method as follows:

AppContext.SetSwitch("System.Net.Http.useSocketsHttpHandler", false);
AppContext.SetSwitch("System.Net.Http.useSocketsHttpHandler", False)

Constructors

HttpClient() HttpClient() HttpClient() HttpClient()

Initializes a new instance of the HttpClient class.

HttpClient(HttpMessageHandler) HttpClient(HttpMessageHandler) HttpClient(HttpMessageHandler) HttpClient(HttpMessageHandler)

Initializes a new instance of the HttpClient class with a specific handler.

HttpClient(HttpMessageHandler, Boolean) HttpClient(HttpMessageHandler, Boolean) HttpClient(HttpMessageHandler, Boolean) HttpClient(HttpMessageHandler, Boolean)

Initializes a new instance of the HttpClient class with a specific handler.

Properties

BaseAddress BaseAddress BaseAddress BaseAddress

Gets or sets the base address of Uniform Resource Identifier (URI) of the Internet resource used when sending requests.

DefaultRequestHeaders DefaultRequestHeaders DefaultRequestHeaders DefaultRequestHeaders

Gets the headers which should be sent with each request.

MaxResponseContentBufferSize MaxResponseContentBufferSize MaxResponseContentBufferSize MaxResponseContentBufferSize

Gets or sets the maximum number of bytes to buffer when reading the response content.

Timeout Timeout Timeout Timeout

Gets or sets the timespan to wait before the request times out.

Methods

CancelPendingRequests() CancelPendingRequests() CancelPendingRequests() CancelPendingRequests()

Cancel all pending requests on this instance.

DeleteAsync(String) DeleteAsync(String) DeleteAsync(String) DeleteAsync(String)

Send a DELETE request to the specified Uri as an asynchronous operation.

DeleteAsync(String, CancellationToken) DeleteAsync(String, CancellationToken) DeleteAsync(String, CancellationToken) DeleteAsync(String, CancellationToken)

Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation.

DeleteAsync(Uri) DeleteAsync(Uri) DeleteAsync(Uri) DeleteAsync(Uri)

Send a DELETE request to the specified Uri as an asynchronous operation.

DeleteAsync(Uri, CancellationToken) DeleteAsync(Uri, CancellationToken) DeleteAsync(Uri, CancellationToken) DeleteAsync(Uri, CancellationToken)

Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation.

Dispose() Dispose() Dispose() Dispose()

Releases the unmanaged resources and disposes of the managed resources used by the HttpMessageInvoker.

(Inherited from HttpMessageInvoker)
Dispose(Boolean) Dispose(Boolean) Dispose(Boolean) Dispose(Boolean)

Releases the unmanaged resources used by the HttpClient and optionally disposes of the managed resources.

Equals(Object) Equals(Object) Equals(Object) Equals(Object)

Determines whether the specified object is equal to the current object.

(Inherited from Object)
GetAsync(String) GetAsync(String) GetAsync(String) GetAsync(String)

Send a GET request to the specified Uri as an asynchronous operation.

GetAsync(String, CancellationToken) GetAsync(String, CancellationToken) GetAsync(String, CancellationToken) GetAsync(String, CancellationToken)

Send a GET request to the specified Uri with a cancellation token as an asynchronous operation.

GetAsync(String, HttpCompletionOption) GetAsync(String, HttpCompletionOption) GetAsync(String, HttpCompletionOption) GetAsync(String, HttpCompletionOption)

Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.

GetAsync(String, HttpCompletionOption, CancellationToken) GetAsync(String, HttpCompletionOption, CancellationToken) GetAsync(String, HttpCompletionOption, CancellationToken) GetAsync(String, HttpCompletionOption, CancellationToken)

Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation.

GetAsync(Uri) GetAsync(Uri) GetAsync(Uri) GetAsync(Uri)

Send a GET request to the specified Uri as an asynchronous operation.

GetAsync(Uri, CancellationToken) GetAsync(Uri, CancellationToken) GetAsync(Uri, CancellationToken) GetAsync(Uri, CancellationToken)

Send a GET request to the specified Uri with a cancellation token as an asynchronous operation.

GetAsync(Uri, HttpCompletionOption) GetAsync(Uri, HttpCompletionOption) GetAsync(Uri, HttpCompletionOption) GetAsync(Uri, HttpCompletionOption)

Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.

GetAsync(Uri, HttpCompletionOption, CancellationToken) GetAsync(Uri, HttpCompletionOption, CancellationToken) GetAsync(Uri, HttpCompletionOption, CancellationToken) GetAsync(Uri, HttpCompletionOption, CancellationToken)

Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation.

GetByteArrayAsync(String) GetByteArrayAsync(String) GetByteArrayAsync(String) GetByteArrayAsync(String)

Send a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation.

GetByteArrayAsync(Uri) GetByteArrayAsync(Uri) GetByteArrayAsync(Uri) GetByteArrayAsync(Uri)

Send a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation.

GetHashCode() GetHashCode() GetHashCode() GetHashCode()

Serves as the default hash function.

(Inherited from Object)
GetStreamAsync(String) GetStreamAsync(String) GetStreamAsync(String) GetStreamAsync(String)

Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.

GetStreamAsync(Uri) GetStreamAsync(Uri) GetStreamAsync(Uri) GetStreamAsync(Uri)

Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.

GetStringAsync(String) GetStringAsync(String) GetStringAsync(String) GetStringAsync(String)

Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.

GetStringAsync(Uri) GetStringAsync(Uri) GetStringAsync(Uri) GetStringAsync(Uri)

Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.

GetType() GetType() GetType() GetType()

Gets the Type of the current instance.

(Inherited from Object)
MemberwiseClone() MemberwiseClone() MemberwiseClone() MemberwiseClone()

Creates a shallow copy of the current Object.

(Inherited from Object)
PatchAsync(String, HttpContent) PatchAsync(String, HttpContent) PatchAsync(String, HttpContent) PatchAsync(String, HttpContent)
PatchAsync(String, HttpContent, CancellationToken) PatchAsync(String, HttpContent, CancellationToken) PatchAsync(String, HttpContent, CancellationToken) PatchAsync(String, HttpContent, CancellationToken)
PatchAsync(Uri, HttpContent) PatchAsync(Uri, HttpContent) PatchAsync(Uri, HttpContent) PatchAsync(Uri, HttpContent)
PatchAsync(Uri, HttpContent, CancellationToken) PatchAsync(Uri, HttpContent, CancellationToken) PatchAsync(Uri, HttpContent, CancellationToken) PatchAsync(Uri, HttpContent, CancellationToken)
PostAsync(String, HttpContent) PostAsync(String, HttpContent) PostAsync(String, HttpContent) PostAsync(String, HttpContent)

Send a POST request to the specified Uri as an asynchronous operation.

PostAsync(String, HttpContent, CancellationToken) PostAsync(String, HttpContent, CancellationToken) PostAsync(String, HttpContent, CancellationToken) PostAsync(String, HttpContent, CancellationToken)

Send a POST request with a cancellation token as an asynchronous operation.

PostAsync(Uri, HttpContent) PostAsync(Uri, HttpContent) PostAsync(Uri, HttpContent) PostAsync(Uri, HttpContent)

Send a POST request to the specified Uri as an asynchronous operation.

PostAsync(Uri, HttpContent, CancellationToken) PostAsync(Uri, HttpContent, CancellationToken) PostAsync(Uri, HttpContent, CancellationToken) PostAsync(Uri, HttpContent, CancellationToken)

Send a POST request with a cancellation token as an asynchronous operation.

PutAsync(String, HttpContent) PutAsync(String, HttpContent) PutAsync(String, HttpContent) PutAsync(String, HttpContent)

Send a PUT request to the specified Uri as an asynchronous operation.

PutAsync(String, HttpContent, CancellationToken) PutAsync(String, HttpContent, CancellationToken) PutAsync(String, HttpContent, CancellationToken) PutAsync(String, HttpContent, CancellationToken)

Send a PUT request with a cancellation token as an asynchronous operation.

PutAsync(Uri, HttpContent) PutAsync(Uri, HttpContent) PutAsync(Uri, HttpContent) PutAsync(Uri, HttpContent)

Send a PUT request to the specified Uri as an asynchronous operation.

PutAsync(Uri, HttpContent, CancellationToken) PutAsync(Uri, HttpContent, CancellationToken) PutAsync(Uri, HttpContent, CancellationToken) PutAsync(Uri, HttpContent, CancellationToken)

Send a PUT request with a cancellation token as an asynchronous operation.

SendAsync(HttpRequestMessage) SendAsync(HttpRequestMessage) SendAsync(HttpRequestMessage) SendAsync(HttpRequestMessage)

Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, CancellationToken) SendAsync(HttpRequestMessage, CancellationToken) SendAsync(HttpRequestMessage, CancellationToken) SendAsync(HttpRequestMessage, CancellationToken)

Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, HttpCompletionOption) SendAsync(HttpRequestMessage, HttpCompletionOption) SendAsync(HttpRequestMessage, HttpCompletionOption) SendAsync(HttpRequestMessage, HttpCompletionOption)

Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken) SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken) SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken) SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken)

Send an HTTP request as an asynchronous operation.

ToString() ToString() ToString() ToString()

Returns a string that represents the current object.

(Inherited from Object)

Applies to

See Also