HttpRestClientExtensions Class

Namespace

Assembly

Kampute.HttpClient.dll

Definition

Provides extension methods for HttpRestClient that send requests with the common HTTP methods.

public static class HttpRestClientExtensions

Inheritance

object
HttpRestClientExtensions

Remarks

The generic methods read the response body into the requested type with the content formatters of the client. The other methods read the response body as a string, a byte array, or a stream, or not at all.

Methods

DeleteAsync(this HttpRestClient, string, CancellationToken)

Sends an asynchronous DELETE request to the specified URI without processing the response body.

public static Task DeleteAsync(this HttpRestClient client, string uri, CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task: A task that represents the asynchronous operation.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

DeleteAsync<T>(this HttpRestClient, string, CancellationToken)

Sends an asynchronous DELETE request to the specified URI and returns the response body deserialized as the specified type.

public static Task<T> DeleteAsync<T>(this HttpRestClient client, string uri, CancellationToken cancellationToken = default)

Type Parameters

T: The type of the response object.

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<T>: A task representing the asynchronous operation, returning a deserialized object of type T.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
HttpContentException: Thrown if the response body is empty or its media type is not supported.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

DownloadAsync(this HttpRestClient, HttpMethod, string, HttpContent, Func<HttpContentHeaders, Stream>, CancellationToken)

Sends an asynchronous HTTP request with the specified method, URI, and payload, returning the response content as a stream.

public static Task<Stream> DownloadAsync(this 
	HttpRestClient client,
	HttpMethod method,
	string uri,
	HttpContent payload,
	Func<HttpContentHeaders, Stream> streamProvider,
	CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
method HttpMethod: The HTTP method to use for the request.
uri string: The URI to which the request is sent.
payload HttpContent: The HTTP request payload content.
streamProvider Func<HttpContentHeaders, Stream>: A function that returns a Stream based on the HTTP content headers.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<Stream>: A task that represents the asynchronous operation. The task result contains a Stream that represents the response content.

Exceptions

ArgumentNullException: Thrown if method, uri, or streamProvider is null.
InvalidOperationException: Thrown if streamProvider returns null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
IOException: Thrown if transferring the response body fails, or writing to the stream from streamProvider fails.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

Remarks

The response body is not buffered: it is copied from the network into the stream returned by streamProvider as it arrives, and the cancellation token can stop the copy. If the copy fails or is canceled, that stream is disposed before the exception is rethrown.

HttpClient.Timeout covers only the time until the response headers arrive. Because the body is not buffered, an HttpRestClient.AfterReceivingResponse handler that reads the response content consumes it, and nothing is copied.

GetAsByteArrayAsync(this HttpRestClient, string, CancellationToken)

Sends an asynchronous GET request to the specified URI and returns the response body as an array of bytes.

public static Task<byte[]> GetAsByteArrayAsync(this HttpRestClient client, string uri, CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<byte[]>: A task representing the asynchronous operation, returning an array of bytes.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

GetAsStreamAsync(this HttpRestClient, string, CancellationToken)

Sends an asynchronous GET request to the specified URI and returns the response body as a Stream.

public static Task<Stream> GetAsStreamAsync(this HttpRestClient client, string uri, CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<Stream>: A task that represents the asynchronous operation, returning a Stream.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

Remarks

The task completes as soon as the response headers arrive. The response body is not buffered: the returned stream reads it from the network, so the caller must dispose the stream to release the connection. Reading the stream can fail with an IOException if the transfer fails.

GetAsStringAsync(this HttpRestClient, string, CancellationToken)

Sends an asynchronous GET request to the specified URI and returns the response body as a string.

public static Task<string> GetAsStringAsync(this HttpRestClient client, string uri, CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<string>: A task representing the asynchronous operation, returning a string.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

GetAsync<T>(this HttpRestClient, string, CancellationToken)

Sends an asynchronous GET request to the specified URI and returns the response body deserialized as the specified type.

public static Task<T> GetAsync<T>(this HttpRestClient client, string uri, CancellationToken cancellationToken = default)

Type Parameters

T: The type of the response object.

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<T>: A task representing the asynchronous operation, returning a deserialized object of type T.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
HttpContentException: Thrown if the response body is empty or its media type is not supported.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

GetToStreamAsync(this HttpRestClient, string, Stream, CancellationToken)

Sends an asynchronous GET request to the specified URI and writes the response body into the provided Stream.

public static Task GetToStreamAsync(this 
	HttpRestClient client,
	string uri,
	Stream stream,
	CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
stream Stream: The Stream where the response body is written.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task: A task that represents the asynchronous operation.

Exceptions

ArgumentNullException: Thrown if uri or stream is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
IOException: Thrown if transferring the response body fails, or writing to stream fails.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

Remarks

The response body is not buffered: it is copied from the network into stream as it arrives, and the cancellation token can stop the copy.

HeadAsync(this HttpRestClient, string, CancellationToken)

Sends an asynchronous HEAD request to the specified URI and returns the response headers.

public static Task<HttpResponseHeaders> HeadAsync(this HttpRestClient client, string uri, CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<HttpResponseHeaders>: A task representing the asynchronous operation, returning the response headers.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

OptionsAsync(this HttpRestClient, string, CancellationToken)

Sends an asynchronous OPTIONS request to the specified URI and returns the response headers.

public static Task<HttpResponseHeaders> OptionsAsync(this HttpRestClient client, string uri, CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<HttpResponseHeaders>: A task representing the asynchronous operation, returning the response headers.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

PatchAsync(this HttpRestClient, string, HttpContent, CancellationToken)

Sends an asynchronous PATCH request to the specified URI without processing the response body.

public static Task PatchAsync(this 
	HttpRestClient client,
	string uri,
	HttpContent payload,
	CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
payload HttpContent: The HTTP request payload content.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task: A task that represents the asynchronous operation.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

PatchAsync<T>(this HttpRestClient, string, HttpContent, CancellationToken)

Sends an asynchronous PATCH request to the specified URI and returns the response body deserialized as the specified type.

public static Task<T> PatchAsync<T>(this 
	HttpRestClient client,
	string uri,
	HttpContent payload,
	CancellationToken cancellationToken = default)

Type Parameters

T: The type of the response object.

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
payload HttpContent: The HTTP request payload content.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<T>: A task representing the asynchronous operation, returning a deserialized object of type T.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
HttpContentException: Thrown if the response body is empty or its media type is not supported.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

PostAsync(this HttpRestClient, string, HttpContent, CancellationToken)

Sends an asynchronous POST request to the specified URI without processing the response body.

public static Task PostAsync(this 
	HttpRestClient client,
	string uri,
	HttpContent payload,
	CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
payload HttpContent: The HTTP request payload content.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task: A task that represents the asynchronous operation.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

PostAsync<T>(this HttpRestClient, string, HttpContent, CancellationToken)

Sends an asynchronous POST request to the specified URI and returns the response body deserialized as the specified type.

public static Task<T> PostAsync<T>(this 
	HttpRestClient client,
	string uri,
	HttpContent payload,
	CancellationToken cancellationToken = default)

Type Parameters

T: The type of the response object.

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
payload HttpContent: The HTTP request payload content.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<T>: A task representing the asynchronous operation, returning a deserialized object of type T.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
HttpContentException: Thrown if the response body is empty or its media type is not supported.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

PutAsync(this HttpRestClient, string, HttpContent, CancellationToken)

Sends an asynchronous PUT request to the specified URI without processing the response body.

public static Task PutAsync(this 
	HttpRestClient client,
	string uri,
	HttpContent payload,
	CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
payload HttpContent: The HTTP request payload content.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task: A task that represents the asynchronous operation.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

PutAsync<T>(this HttpRestClient, string, HttpContent, CancellationToken)

Sends an asynchronous PUT request to the specified URI and returns the response body deserialized as the specified type.

public static Task<T> PutAsync<T>(this 
	HttpRestClient client,
	string uri,
	HttpContent payload,
	CancellationToken cancellationToken = default)

Type Parameters

T: The type of the response object.

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
uri string: The URI to which the request is sent.
payload HttpContent: The HTTP request payload content.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<T>: A task representing the asynchronous operation, returning a deserialized object of type T.

Exceptions

ArgumentNullException: Thrown if uri is null.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
HttpContentException: Thrown if the response body is empty or its media type is not supported.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

SendObjectAsync(this HttpRestClient, HttpMethod, string, object, string, CancellationToken)

Sends an asynchronous request whose payload is written in the specified media type by a registered content formatter, without processing the response body.

public static Task SendObjectAsync(this 
	HttpRestClient client,
	HttpMethod method,
	string uri,
	object payload,
	string mediaType,
	CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
method HttpMethod: The HTTP method to use for the request.
uri string: The URI to which the request is sent.
payload object: The object to send as the request payload. An HttpContent is sent as it is.
mediaType string: The media type in which to write payload.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task: A task that represents the asynchronous operation.

Exceptions

ArgumentNullException: Thrown if client, method, uri, payload or mediaType is null.
InvalidOperationException: Thrown if no formatter in HttpRestClient.ContentFormatters can write payload in mediaType.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

Remarks

The payload is written by the first formatter in HttpRestClient.ContentFormatters that can write its type in mediaType. The argument exceptions and the InvalidOperationException are thrown when the method is called, before anything is sent.

SendObjectAsync(this HttpRestClient, HttpMethod, string, object, IHttpContentFormatter, CancellationToken)

Sends an asynchronous request whose payload is written by the specified content formatter, without processing the response body.

public static Task SendObjectAsync(this 
	HttpRestClient client,
	HttpMethod method,
	string uri,
	object payload,
	IHttpContentFormatter formatter,
	CancellationToken cancellationToken = default)

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
method HttpMethod: The HTTP method to use for the request.
uri string: The URI to which the request is sent.
payload object: The object to send as the request payload. An HttpContent is sent as it is.
formatter IHttpContentFormatter: The formatter that writes payload, in the first media type it can write for the type of the payload.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task: A task that represents the asynchronous operation.

Exceptions

ArgumentNullException: Thrown if client, method, uri, payload or formatter is null.
InvalidOperationException: Thrown if formatter cannot write the type of payload.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

Remarks

The formatters in HttpRestClient.ContentFormatters are not consulted, so the payload is written by formatter even when another formatter is registered for the same media type. The argument exceptions and the InvalidOperationException are thrown when the method is called, before anything is sent.

SendObjectAsync<T>(this HttpRestClient, HttpMethod, string, object, string, CancellationToken)

Sends an asynchronous request whose payload is written in the specified media type by a registered content formatter, and returns the response body deserialized as the specified type.

public static Task<T> SendObjectAsync<T>(this 
	HttpRestClient client,
	HttpMethod method,
	string uri,
	object payload,
	string mediaType,
	CancellationToken cancellationToken = default)

Type Parameters

T: The type of the response object.

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
method HttpMethod: The HTTP method to use for the request.
uri string: The URI to which the request is sent.
payload object: The object to send as the request payload. An HttpContent is sent as it is.
mediaType string: The media type in which to write payload.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<T>: A task representing the asynchronous operation, returning a deserialized object of type T.

Exceptions

ArgumentNullException: Thrown if client, method, uri, payload or mediaType is null.
InvalidOperationException: Thrown if no formatter in HttpRestClient.ContentFormatters can write payload in mediaType.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
HttpContentException: Thrown if the response body is empty or its media type is not supported.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

Remarks

SendObjectAsync<T>(this HttpRestClient, HttpMethod, string, object, IHttpContentFormatter, CancellationToken)

Sends an asynchronous request whose payload is written by the specified content formatter, and returns the response body deserialized as the specified type.

public static Task<T> SendObjectAsync<T>(this 
	HttpRestClient client,
	HttpMethod method,
	string uri,
	object payload,
	IHttpContentFormatter formatter,
	CancellationToken cancellationToken = default)

Type Parameters

T: The type of the response object.

Parameters

client HttpRestClient: The HttpRestClient instance to be used for sending the request.
method HttpMethod: The HTTP method to use for the request.
uri string: The URI to which the request is sent.
payload object: The object to send as the request payload. An HttpContent is sent as it is.
formatter IHttpContentFormatter: The formatter that writes payload, in the first media type it can write for the type of the payload.
cancellationToken CancellationToken optional: A token for canceling the request (optional).

Returns

Task<T>: A task representing the asynchronous operation, returning a deserialized object of type T.

Exceptions

ArgumentNullException: Thrown if client, method, uri, payload or formatter is null.
InvalidOperationException: Thrown if formatter cannot write the type of payload.
HttpResponseException: Thrown if the response status code indicates a failure.
HttpRequestException: Thrown if the request fails due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.
HttpContentException: Thrown if the response body is empty or its media type is not supported.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token, or if the timeout of the underlying HttpClient elapses.

Remarks

The formatters in HttpRestClient.ContentFormatters are not consulted to write the payload, so the payload is written by formatter even when another formatter is registered for the same media type. The response is still read by the registered formatters. The argument exceptions and the InvalidOperationException are thrown when the method is called, before anything is sent.

WithScope(this HttpRestClient)

Starts a fluent definition of headers and request properties that apply to the requests of one operation.

public static HttpRequestScope WithScope(this HttpRestClient client)

Parameters

client HttpRestClient: The HttpRestClient instance for which the scope is created.

Returns

HttpRequestScope: A new HttpRequestScope for client.

Exceptions

ArgumentNullException: Thrown if the client argument is null.