Table of Contents

Class HttpClient

Namespace
System.Net.Http
Assembly
System.Net.Http.dll

Initializes a new instance of the HttpClient class.

public class HttpClient : HttpMessageInvoker, IDisposable
Inheritance
HttpClient
Implements
Inherited Members
Extension Methods

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.

HttpClient is intended to be instantiated once and reused throughout the life of an application.

Constructors

HttpClient()

Initializes a new instance of the HttpClient class using a HttpClientHandler that is disposed when this instance is disposed.

public HttpClient()

Properties

BaseAddress

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

public Uri BaseAddress { get; set; }

Property Value

Uri

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

Exceptions

ArgumentException

Value is null or it not an absolute Uniform Resource Identifier (URI).

InvalidOperationException

An operation has already been started on the current instance.

ObjectDisposedException

The current instance has been disposed.

DefaultRequestHeaders

Gets the headers which should be sent with each request.

public HttpRequestHeaders DefaultRequestHeaders { get; }

Property Value

HttpRequestHeaders

The headers which should be sent with each request.

Remarks

Headers set on this property don't need to be set on request messages again. DefaultRequestHeaders should not be modified while there are outstanding requests, because it is not thread-safe.

HttpsAuthentCert

Gets or sets the root CA certificate used to authenticate with https servers. This certificate is used only for https connections; http connections do not require this.

public X509Certificate HttpsAuthentCert { get; set; }

Property Value

X509Certificate

Remarks

This property is an extension from the full .NET required by nanoFramework.

SslProtocols

Gets or sets the TLS/SSL protocol used by the HttpClient class.

public SslProtocols SslProtocols { get; set; }

Property Value

SslProtocols

One of the values defined in the SslProtocols enumeration. Default value is Tls12.

Remarks

This property is an extension from the full .NET required by nanoFramework.

SslVerification

Gets or sets the TLS/SSL verification mode used by the HttpClient class.

public SslVerification SslVerification { get; set; }

Property Value

SslVerification

Remarks

Default value is CertificateRequired.

Timeout

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

public TimeSpan Timeout { get; set; }

Property Value

TimeSpan

The timespan to wait before the request times out.

Remarks

The default value is 100,000 milliseconds (100 seconds).

To set an infinite timeout, set the property value to InfiniteTimeSpan.

A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set Timeout to a value less than 15 seconds, it may take 15 seconds or more before a WebException is thrown to indicate a timeout on your request.

The same timeout will apply for all requests using this HttpClient instance. You may also set different timeouts for individual requests using a CancellationTokenSource on a task.Note that only the shorter of the two timeouts will apply.

Exceptions

ArgumentException

Value is null or it not an absolute Uniform Resource Identifier (URI).

InvalidOperationException

An operation has already been started on the current instance.

ObjectDisposedException

The current instance has been disposed.

Methods

Delete(string)

Send a DELETE request to the specified Uri as a synchronous operation.

public HttpResponseMessage Delete(string requestUri)

Parameters

requestUri string

The Uri the request is sent to.

Returns

HttpResponseMessage

The HttpResponseMessage object resulting from the HTTP request.

Remarks

This operation will block.

This is the .NET nanoFramework equivalent of DeleteAsync.

Exceptions

ArgumentNullException

The request is null.

InvalidOperationException

The request message was already sent by the HttpClient instance.

HttpRequestException

The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.

Get(string)

Sends a GET request to the specified Uri.

public HttpResponseMessage Get(string requestUri)

Parameters

requestUri string

The Uri the request is sent to.

Returns

HttpResponseMessage

The HttpResponseMessage object resulting from the HTTP request.

Remarks

This operation will block.

This is the .NET nanoFramework equivalent of GetAsync.

Exceptions

InvalidOperationException

Request operation has already started.

ArgumentNullException

The request is null.

InvalidOperationException

The request message was already sent by the HttpClient instance.

HttpRequestException

The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.

Get(string, HttpCompletionOption)

Send a GET request to the specified Uri.

public HttpResponseMessage Get(string requestUri, HttpCompletionOption completionOption)

Parameters

requestUri string

The Uri the request is sent to.

completionOption HttpCompletionOption

Returns

HttpResponseMessage

The HttpResponseMessage object resulting from the HTTP request.

Remarks

This operation will block.

This is the .NET nanoFramework equivalent of GetAsync.

Exceptions

InvalidOperationException

Request operation has already started.

ArgumentNullException

The request is null.

InvalidOperationException

The request message was already sent by the HttpClient instance.

HttpRequestException

The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.

GetByteArray(string)

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

public byte[] GetByteArray(string requestUri)

Parameters

requestUri string

The Uri the request is sent to.

Returns

byte[]

A byte array resulting from the HTTP request.

Remarks

This operation will block. It returns after the whole response body is read.

This is the .NET nanoFramework equivalent of GetByteArrayAsync.

Exceptions

ArgumentNullException

The request is null.

InvalidOperationException

The request message was already sent by the HttpClient instance.

HttpRequestException

The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.

GetStream(string)

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

public Stream GetStream(string requestUri)

Parameters

requestUri string

The Uri the request is sent to.

Returns

Stream

A Stream resulting from the HTTP request.

Remarks

This operation will block.

As of now, this method reads and buffers the entire response body (see SerializeToStream(Stream)). If the response needs to be streamed, one of the methods that return Send(HttpRequestMessage, HttpCompletionOption) should be used with ResponseHeadersRead and CopyTo(Stream) instead.

This is the .NET nanoFramework equivalent of GetStreamAsync.

Exceptions

ArgumentNullException

The request is null.

InvalidOperationException

The request message was already sent by the HttpClient instance.

HttpRequestException

The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.

GetString(string)

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

public string GetString(string requestUri)

Parameters

requestUri string

The Uri the request is sent to.

Returns

string

A string resulting from the HTTP request.

Remarks

This operation will block.

This operation will block. It returns after the whole response body is read.

This is the .NET nanoFramework equivalent of GetStringAsync.

Exceptions

ArgumentNullException

The request is null.

InvalidOperationException

The request message was already sent by the HttpClient instance.

HttpRequestException

The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.

Patch(string, HttpContent)

Sends a PATCH request as a synchronous operation.

public HttpResponseMessage Patch(string requestUri, HttpContent content)

Parameters

requestUri string

The Uri the request is sent to.

content HttpContent

The HTTP request content sent to the server.

Returns

HttpResponseMessage

The HttpResponseMessage object resulting from the HTTP request.

Remarks

This operation will block.

This is the .NET nanoFramework equivalent of PatchAsync.

Exceptions

ArgumentNullException

The request is null.

InvalidOperationException

The request message was already sent by the HttpClient instance.

HttpRequestException

The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.

Post(string, HttpContent)

Send a POST request as a synchronous operation.

public HttpResponseMessage Post(string requestUri, HttpContent content)

Parameters

requestUri string

The Uri the request is sent to.

content HttpContent

The HTTP request content sent to the server.

Returns

HttpResponseMessage

The HttpResponseMessage object resulting from the HTTP request.

Remarks

This operation will block.

This is the .NET nanoFramework equivalent of PostAsync.

Exceptions

ArgumentNullException

The request is null.

InvalidOperationException

The request message was already sent by the HttpClient instance.

HttpRequestException

The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.

Put(string, HttpContent)

Send a PUT request as a synchronous operation.

public HttpResponseMessage Put(string requestUri, HttpContent content)

Parameters

requestUri string

The Uri the request is sent to.

content HttpContent

The HTTP request content sent to the server.

Returns

HttpResponseMessage

The HttpResponseMessage object resulting from the HTTP request.

Remarks

This operation will block.

This is the .NET nanoFramework equivalent of PutAsync.

Exceptions

ArgumentNullException

The request is null.

InvalidOperationException

The request message was already sent by the HttpClient instance.

HttpRequestException

The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.

Send(HttpRequestMessage)

Sends an HTTP request with the specified request.

public override HttpResponseMessage Send(HttpRequestMessage request)

Parameters

request HttpRequestMessage

The HTTP request message to send.

Returns

HttpResponseMessage

The HTTP response message.

Exceptions

ArgumentNullException

The request is null.

InvalidOperationException

The request message was already sent by the HttpClient instance.

HttpRequestException

The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.

Send(HttpRequestMessage, HttpCompletionOption)

Sends an HTTP request with the specified request.

public HttpResponseMessage Send(HttpRequestMessage request, HttpCompletionOption completionOption)

Parameters

request HttpRequestMessage

The HTTP request message to send.

completionOption HttpCompletionOption

One of the enumeration values that specifies when the operation should complete (as soon as a response is available or after reading the response content).

Returns

HttpResponseMessage

The HTTP response message.

Exceptions

ArgumentNullException

The request is null.

InvalidOperationException

The request message was already sent by the HttpClient instance.

HttpRequestException

The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.