Class ApiClientBase

Namespace

VpnHood.Net.Toolkit.ApiClients

Assembly

VpnHood.Net.Toolkit.dll

Provides the base of a hand-written API client: it sends JSON requests through an HttpClient, reads JSON responses, and turns an error response into an exception.

public class ApiClientBase : ApiClientCommon

Inheritance

object

ApiClientCommon

ApiClientBase

Derived

HttpAccessManager

Inherited Members

ApiClientCommon.DefaultBaseAddress

ApiClientCommon.DefaultAuthorization

ApiClientCommon.DefaultHeaders

ApiClientCommon.PrepareRequestAsync(HttpClient, HttpRequestMessage, StringBuilder, CancellationToken)

ApiClientCommon.PrepareRequestAsync(HttpClient, HttpRequestMessage, string, CancellationToken)

ApiClientCommon.ProcessResponseAsync(HttpClient, HttpResponseMessage, CancellationToken)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A status outside 2xx throws: for an RFC 9457 problem or an ApiError body, the exception ToException(ApiError) makes, which is none by default; otherwise, an ApiException. Each call sent is logged.

Constructors

ApiClientBase()

Initializes a new instance of the ApiClientBase class whose derived class sets HttpClient.

protected ApiClientBase()

ApiClientBase(HttpClient)

Initializes a new instance of the ApiClientBase class.

public ApiClientBase(HttpClient httpClient)

Parameters

httpClient HttpClient

The HTTP client the requests go through; the caller keeps owning it.

Fields

HttpClient

The HTTP client the requests go through, or null until a derived class sets it.

protected HttpClient? HttpClient

Field Value

HttpClient

Properties

JsonSerializerSettings

Gets the JSON settings the requests and responses use, made once by CreateSerializerSettings().

protected JsonSerializerOptions JsonSerializerSettings { get; }

Property Value

JsonSerializerOptions

Logger

Gets or sets the logger of the calls. The default logs nothing.

public ILogger Logger { get; set; }

Property Value

ILogger

LoggerEventId

Gets or sets the event ID the log lines carry.

public EventId LoggerEventId { get; set; }

Property Value

EventId

ReadResponseAsString

Gets or sets a value indicating whether a JSON response is read as text first, so the text shows in an error; otherwise, it is read as a stream.

public bool ReadResponseAsString { get; set; }

Property Value

bool

Methods

ConvertToString(object?, CultureInfo)

Writes a query parameter's value as text: an enum by its EnumMemberAttribute value where reflection is on, else its number, and a combination of flags as .NET writes it; a bool in lower case; bytes in Base64; an array's items separated by commas.

protected string ConvertToString(object? value, CultureInfo cultureInfo)

Parameters

value object

The value, or null for an empty text.

cultureInfo CultureInfo

The culture the value is written in.

Returns

string

The text.

CreateSerializerSettings()

Creates the JSON settings, once. Without a resolver of its own, the settings read by reflection where it is on.

protected virtual JsonSerializerOptions CreateSerializerSettings()

Returns

JsonSerializerOptions

The settings. The default is .NET's defaults.

HttpClientSendAsync(HttpClient, HttpRequestMessage, HttpCompletionOption, CancellationToken)

Sends a request through the HTTP client; a derived class may send it otherwise.

protected virtual Task<HttpResponseMessage> HttpClientSendAsync(HttpClient client, HttpRequestMessage request, HttpCompletionOption responseHeadersRead, CancellationToken cancellationToken)

Parameters

client HttpClient

The HTTP client.

request HttpRequestMessage

The request.

responseHeadersRead HttpCompletionOption

When the send completes: once the headers are read, or the whole response.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<HttpResponseMessage>

A task whose result is the response.

Exceptions

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpDeleteAsync(string, Dictionary<string, object?>?, CancellationToken)

Sends a DELETE request.

protected Task HttpDeleteAsync(string urlPart, Dictionary<string, object?>? parameters, CancellationToken cancellationToken)

Parameters

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task

A task that represents the asynchronous operation.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpGetAsync<T>(string, Dictionary<string, object?>?, CancellationToken)

Sends a GET request and reads its response as an object.

protected Task<T> HttpGetAsync<T>(string urlPart, Dictionary<string, object?>? parameters, CancellationToken cancellationToken)

Parameters

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<T>

A task whose result is the object; the default for status 204.

Type Parameters

T

The object's type.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpPatchAsync(string, Dictionary<string, object?>?, object?, CancellationToken)

Sends a PATCH request.

protected Task HttpPatchAsync(string urlPart, Dictionary<string, object?>? parameters, object? data, CancellationToken cancellationToken)

Parameters

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

data object

The body, sent as JSON, or null for none.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task

A task that represents the asynchronous operation.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpPatchAsync<T>(string, Dictionary<string, object?>?, object?, CancellationToken)

Sends a PATCH request and reads its response as an object.

protected Task<T> HttpPatchAsync<T>(string urlPart, Dictionary<string, object?>? parameters, object? data, CancellationToken cancellationToken)

Parameters

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

data object

The body, sent as JSON, or null for none.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<T>

A task whose result is the object; the default for status 204.

Type Parameters

T

The object's type.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpPostAsync(string, Dictionary<string, object?>?, object?, CancellationToken)

Sends a POST request.

protected Task HttpPostAsync(string urlPart, Dictionary<string, object?>? parameters, object? data, CancellationToken cancellationToken)

Parameters

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

data object

The body, sent as JSON, or null for none.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task

A task that represents the asynchronous operation.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpPostAsync<T>(string, Dictionary<string, object?>?, object?, CancellationToken)

Sends a POST request and reads its response as an object.

protected Task<T> HttpPostAsync<T>(string urlPart, Dictionary<string, object?>? parameters, object? data, CancellationToken cancellationToken)

Parameters

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

data object

The body, sent as JSON, or null for none.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<T>

A task whose result is the object; the default for status 204.

Type Parameters

T

The object's type.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpPutAsync(string, Dictionary<string, object?>?, object?, CancellationToken)

Sends a PUT request.

protected Task HttpPutAsync(string urlPart, Dictionary<string, object?>? parameters, object? data, CancellationToken cancellationToken)

Parameters

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

data object

The body, sent as JSON, or null for none.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task

A task that represents the asynchronous operation.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpPutAsync<T>(string, Dictionary<string, object?>?, object?, CancellationToken)

Sends a PUT request and reads its response as an object.

protected Task<T> HttpPutAsync<T>(string urlPart, Dictionary<string, object?>? parameters, object? data, CancellationToken cancellationToken)

Parameters

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

data object

The body, sent as JSON, or null for none.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<T>

A task whose result is the object; the default for status 204.

Type Parameters

T

The object's type.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpSendAsync(HttpMethod, string, Dictionary<string, object?>?, object?, CancellationToken)

Sends a request and reads its response as text, not as an object.

protected Task<string> HttpSendAsync(HttpMethod httpMethod, string urlPart, Dictionary<string, object?>? parameters, object? data, CancellationToken cancellationToken)

Parameters

httpMethod HttpMethod

The method.

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

data object

The body, sent as JSON, or null for none.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<string>

A task whose result is the response's text; empty for status 204.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpSendAsync(string, Dictionary<string, object?>?, HttpRequestMessage, CancellationToken)

Sends a request the caller made, and reads its response as text, not as an object.

protected Task<string> HttpSendAsync(string urlPart, Dictionary<string, object?>? parameters, HttpRequestMessage request, CancellationToken cancellationToken)

Parameters

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

request HttpRequestMessage

The request, which the caller keeps owning.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<string>

A task whose result is the response's text; empty for status 204.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpSendAsync<T>(HttpMethod, string, Dictionary<string, object?>?, object?, CancellationToken)

Sends a request and reads its response as an object.

protected Task<T> HttpSendAsync<T>(HttpMethod httpMethod, string urlPart, Dictionary<string, object?>? parameters, object? data, CancellationToken cancellationToken)

Parameters

httpMethod HttpMethod

The method.

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

data object

The body, sent as JSON, or null for none.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<T>

A task whose result is the object; the default for status 204.

Type Parameters

T

The object's type.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpSendAsync<T>(string, Dictionary<string, object?>?, HttpRequestMessage, CancellationToken)

Sends a request the caller made, and reads its response as an object, with the response.

protected virtual Task<ApiClientBase.HttpResult<T>> HttpSendAsync<T>(string urlPart, Dictionary<string, object?>? parameters, HttpRequestMessage request, CancellationToken cancellationToken)

Parameters

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

request HttpRequestMessage

The request, which the caller keeps owning.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<ApiClientBase.HttpResult<T>>

A task whose result is the object with the response.

Type Parameters

T

The object's type.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

HttpSendExAsync<T>(HttpMethod, string, Dictionary<string, object?>?, object?, CancellationToken)

Sends a request and reads its response as an object, with the response.

protected Task<ApiClientBase.HttpResult<T>> HttpSendExAsync<T>(HttpMethod httpMethod, string urlPart, Dictionary<string, object?>? parameters, object? data, CancellationToken cancellationToken)

Parameters

httpMethod HttpMethod

The method.

urlPart string

The URL, relative to DefaultBaseAddress or absolute.

parameters Dictionary<string, object>

The query's parameters, or null for none.

data object

The body, sent as JSON, or null for none.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<ApiClientBase.HttpResult<T>>

A task whose result is the object with the response.

Type Parameters

T

The object's type.

Exceptions

ApiException

The status is not a success, or the response cannot be read.

Exception

The exception ToException(ApiError) makes for an error response, or the client has no HttpClient.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

ReadObjectResponseAsync<T>(HttpResponseMessage, IReadOnlyDictionary<string, IEnumerable<string>>, CancellationToken)

Reads a success response as an object: as JSON, or a response that is not JSON as text into a string or as bytes into a byte array.

protected virtual Task<ApiClientBase.HttpResult<T?>> ReadObjectResponseAsync<T>(HttpResponseMessage response, IReadOnlyDictionary<string, IEnumerable<string>> headers, CancellationToken cancellationToken)

Parameters

response HttpResponseMessage

The response.

headers IReadOnlyDictionary<string, IEnumerable<string>>

The response's headers, for an error.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<ApiClientBase.HttpResult<T>>

A task whose result is the object with the response.

Type Parameters

T

The object's type.

Exceptions

ApiException

The JSON cannot be read as the type.

OperationCanceledException

cancellationToken was canceled, or the HTTP client timed out.

ToException(ApiError)

Makes the exception an error response names, so a caller catches the same type it would have caught in process.

protected virtual Exception? ToException(ApiError apiError)

Parameters

apiError ApiError

The error.

Returns

Exception

The exception, or null for an ApiException.

Remarks

null, the default, leaves the failure as an ApiException, which carries the name in ExceptionTypeName either way. An override can return ToException()'s, which covers the common types, or its own.