Class QueryOData

Namespace

Utils.OData

Assembly

Utils.OData.dll

Provides an HTTP-based client for executing OData queries and converting the responses to usable shapes.

public class QueryOData : IDisposable

Inheritance

object

QueryOData

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

DataUtils.ToDbValue(object?)

MathEx.Clamp<T>(T, T, T, IComparer<T>)

FluentExtensions.Failure<T>(T)

FluentExtensions.IsEqualTo<T, CT>(T, CT)

FluentExtensions.IsGreaterOrEqualsThan<T, CT>(T, CT)

FluentExtensions.IsGreaterThan<T, CT>(T, CT)

FluentExtensions.IsIn<T>(T, params T[])

FluentExtensions.IsLowerOrEqualsThan<T, CT>(T, CT)

FluentExtensions.IsLowerThan<T, CT>(T, CT)

FluentExtensions.IsNotIn<T>(T, params T[])

FluentExtensions.IsNotNull<T>(T)

FluentExtensions.IsNull<T>(T)

FluentExtensions.Success<T>(T)

FluentExtensions.Test<T>(T, Func<T, bool>)

ObjectUtils.Between<T>(T, IComparer<T>, T, T)

ObjectUtils.Between<T>(T, IComparer<T>, T, T, bool, bool)

ObjectUtils.DoAsync<T, Result>(T, Func<T, Task<Result>>, Func<Task<Result>>)

ObjectUtils.DoAsync<T, Result>(T, Func<T, Task<Result>>, Result)

ObjectUtils.DoAsync<T, Result>(T, Func<T, Result>, Func<Result>)

ObjectUtils.DoAsync<T, Result>(T, Func<T, Result>, Result)

ObjectUtils.Do<T, Result>(T, Func<T, Result>, Func<Result>)

ObjectUtils.Do<T, Result>(T, Func<T, Result>, Result)

ObjectUtils.In<T>(T, params T[])

ObjectUtils.NotIn<T>(T, params T[])

Validations.ArgMustBe<T>(T, Func<T, bool>, string, string)

Validations.ArgMustNotBe<T>(T, Func<T, bool>, string, string)

Validations.Arg<T>(T, string)

Validations.ValueMustNotBeNull<T>(T, string)

Validations.Variable<T>(T, string)

Constructors

QueryOData(string)

Initializes a new instance of the QueryOData class with the specified base URL.

public QueryOData(string baseUrl)

Parameters

baseUrl string

The base URL for the OData service. Must be a valid absolute HTTP or HTTPS URI.

Remarks

This constructor sets up an HttpClient with default credentials and a timeout of 600 seconds.

Exceptions

ArgumentNullException

Thrown if baseUrl is null.

ArgumentException

Thrown if baseUrl is not a valid absolute HTTP or HTTPS URI.

QueryOData(string, HttpClient)

Initializes a new instance of the QueryOData class with the specified base URL and HTTP client.

public QueryOData(string baseUrl, HttpClient httpClient)

Parameters

baseUrl string

The base URL for the OData service. Must be a valid absolute HTTP or HTTPS URI.

httpClient HttpClient

The HTTP client used to send requests. Cannot be null.

Exceptions

ArgumentNullException

Thrown if baseUrl or httpClient is null.

ArgumentException

Thrown if baseUrl is not a valid absolute HTTP or HTTPS URI.

Properties

BaseUrl

Gets the base URL used for oData requests.

public string BaseUrl { get; }

Property Value

string

CookieContainer

Gets the CookieContainer used by the internal handler when the instance manages its own client. This allows callers to propagate cookies from an incoming HTTP request.

public CookieContainer? CookieContainer { get; }

Property Value

CookieContainer

Credentials

If provided, credentials used by the internal handler. If an external HttpClient is provided in the ctor, those credentials won't be applied to that external client.

public NetworkCredential? Credentials { get; set; }

Property Value

NetworkCredential

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

GetColumns(IQuery, JsonArray)

Retrieves the column names from the specified query and JSON array.

public static string[] GetColumns(IQuery parameter, JsonArray array)

Parameters

parameter IQuery

The query parameter containing the selection criteria. If the Select property is null or whitespace, all columns from the first JSON object in the array are returned.

array JsonArray

The JSON array from which to extract column names. The array must contain at least one JSON object.

Returns

string[]

An array of strings representing the column names. If parameter has a non-empty Select property, the specified columns are returned; otherwise, all columns from the first JSON object are returned.

GetMetadataFromBaseAsync(CancellationToken)

Retrieves the service metadata using the instance BaseUrl.

public Task<ReturnValue<Edmx>> GetMetadataFromBaseAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Token used to cancel the retrieval operation.

Returns

Task<ReturnValue<Edmx>>

A ReturnValue<T> containing the metadata document when successful.

GetMetadataFromJsonAsync(JsonNode, CancellationToken)

Retrieves the service metadata by extracting the metadata URL from the provided JSON payload.

public Task<ReturnValue<Edmx>> GetMetadataFromJsonAsync(JsonNode jsonResult, CancellationToken cancellationToken = default)

Parameters

jsonResult JsonNode

The JSON payload returned by an OData service.

cancellationToken CancellationToken

Token used to cancel the retrieval operation.

Returns

Task<ReturnValue<Edmx>>

A ReturnValue<T> containing the metadata document when successful.

Exceptions

ArgumentNullException

Thrown when jsonResult is null.

GetMetadataFromUrlAsync(string, CancellationToken)

Retrieves the service metadata using the provided metadata document URL.

public Task<ReturnValue<Edmx>> GetMetadataFromUrlAsync(string metadataUrl, CancellationToken cancellationToken = default)

Parameters

metadataUrl string

Absolute or relative URL pointing to the metadata document.

cancellationToken CancellationToken

Token used to cancel the retrieval operation.

Returns

Task<ReturnValue<Edmx>>

A ReturnValue<T> containing the metadata document when successful.

Exceptions

ArgumentException

Thrown when metadataUrl is null or whitespace.

QueryToDataReader(IQuery, int, int?, CancellationToken)

Executes the specified query and returns an IDataReader that streams rows as they are downloaded.

public Task<ReturnValue<IDataReader>> QueryToDataReader(IQuery parameter, int skip = 0, int? maxPerRequest = null, CancellationToken cancellationToken = default)

Parameters

parameter IQuery

Query definition describing the requested dataset. Cannot be null.

skip int

Number of rows to skip before starting to stream results.

maxPerRequest int?

Optional maximum number of rows to fetch per HTTP request.

cancellationToken CancellationToken

Token used to cancel the asynchronous operation.

Returns

Task<ReturnValue<IDataReader>>

A ReturnValue<T> containing the streaming reader when successful; otherwise an error.

Remarks

The returned reader downloads additional pages in the background until the data source stops returning results or the configured limit is reached.

QueryToJSon(IQuery, int, int?, CancellationToken)

Executes a query and converts the result to JSON, transparently downloading subsequent pages when required.

public Task<ReturnValue<(JsonArray? Datas, Dictionary<string, string>? Metadatas)>> QueryToJSon(IQuery parameter, int skip = 0, int? maxPerRequest = null, CancellationToken cancellationToken = default)

Parameters

parameter IQuery

The query parameter that defines the data retrieval criteria.

skip int

The number of records to skip in the query result. Must be non-negative.

maxPerRequest int?

Optional maximum number of records to request per HTTP call.

cancellationToken CancellationToken

Token used to cancel the asynchronous processing pipeline.

Returns

Task<ReturnValue<(JsonArray Datas, Dictionary<string, string> Metadatas)>>

A task that represents the asynchronous operation. The task result contains a tuple with a JsonArray of data and a dictionary of metadata. Returns an error if the query or conversion fails.

Remarks

This method performs one or more HTTP requests until the requested number of items is retrieved or the service no longer returns results. Returned payloads are aggregated into a single JSON array while preserving metadata from the first successful response.

SimpleQuery(IQuery, int, CancellationToken)

Executes a query using the internal HTTP client and returns the raw response.

public Task<HttpResponseMessage> SimpleQuery(IQuery parameter, int skip = 0, CancellationToken cancellationToken = default)

Parameters

parameter IQuery

Parameters used to build the query URL.

skip int

Number of records to skip in addition to Skip.

cancellationToken CancellationToken

Token used to cancel the HTTP request.

Returns

Task<HttpResponseMessage>

The HTTP response message. The caller owns the returned response and is responsible for disposing it. The method never returns null; it throws on transport failure.

SimpleQuery(IQuery, HttpRequestMessage?, int, CancellationToken)

Executes a query while copying headers and cookies from an existing HTTP request to preserve the context.

public Task<HttpResponseMessage> SimpleQuery(IQuery parameter, HttpRequestMessage? sourceRequest = null, int skip = 0, CancellationToken cancellationToken = default)

Parameters

parameter IQuery

Parameters used to build the query URL.

sourceRequest HttpRequestMessage

Optional request providing HTTP headers to forward.

skip int

Number of records to skip in addition to Skip.

cancellationToken CancellationToken

Token used to cancel the HTTP request.

Returns

Task<HttpResponseMessage>

The HTTP response message. The caller owns the returned response and is responsible for disposing it. The method never returns null; it throws on transport failure.