API reference

Applies to client 0.2.1 with the contract package Wkl.Data.Gateway.Contracts 0.6.0. The client's types are in the namespace Wkl.Data.Gateway.Client, the contract's in Wkl.Data.Gateway.Contracts.

Registration

Method	Effect
`services.AddGatewayClient(IConfiguration section)`	Binds the configuration to the section you pass, usually `configuration.GetSection(GatewayClientOptions.SectionName)`
`services.AddGatewayClient(Action<GatewayClientOptions> configure)`	The same, with settings from code

Both register IGatewayClient (implementation GatewayHttpClient, one per application), the validation of the settings at startup, and two named HTTP clients for reading and calling, each with its own time limit. To replace the default correlation source, register your own IGatewayCorrelationSource before the call; the default uses the trace ID (TraceId) of the current Activity in W3C format, the Id of an Activity in the older hierarchical format, or a new GUID if there's no Activity.

IGatewayClient

Method	Purpose	Result
`ReadAsync<TRow>(GatewayQuery query, IReadOnlyDictionary<string, string>? arguments = null, CancellationToken ct = default)`	Reads a window from a table, view, or function. Use `arguments` only for a function: name and value of each parameter, as text	`GatewayPage<TRow>`
`InvokeAsync<TRow>(GatewayRoutineRequest request, CancellationToken ct = default)`	Calls a procedure	`GatewayRoutineResult<TRow>`

Each method sends exactly one request. If it fails, the method throws GatewayRequestException (see A request fails with `GatewayRequestException`); a cancellation through the caller's CancellationToken arrives as OperationCanceledException.

Row type TRow. Rows are read with System.Text.Json. Column names are matched, case-insensitively, against the snake_case form of the property names (LastChangedUtc reads last_changed_utc). A column whose name differs needs [JsonPropertyName("…")] with the name the database uses. With JsonElement as TRow, each row is read unchanged.

What is read

GatewayResource

new GatewayResource(string databaseAlias, GatewayResourceKind kind, string name)

Parameter	Meaning
`databaseAlias`	Name of the data source in the service, not the name of the database
`kind`	`Table`, `View`, `Function`, or `Procedure`
`name`	`object` or `schema.object`

GatewayQuery

new GatewayQuery(resource, select = null, filter = null, orderBy = null, skip = 0, top = null, includeTotalCount = false)

Parameter	Meaning
`resource`	Table, view, or function. A procedure is rejected (`ArgumentException`)
`select`	Columns to read. Empty: all columns the service offers
`filter`	Condition, see below
`orderBy`	Sequence of `GatewaySortField(string field, GatewaySortDirection direction)` with `Ascending` or `Descending`
`skip`	Rows to skip. Not negative
`top`	Requested window size, greater than zero. The service caps it at its maximum; without it, the service uses its default
`includeTotalCount`	Also asks the service to count how many rows the filter matches in total

Filters (GatewayFilter)

Kind	Construction	Meaning
Comparison	`new GatewayFilter.Comparison(field, op, value)`	`op` is `Equal`, `NotEqual`, `LessThan`, `LessThanOrEqual`, `GreaterThan`, `GreaterThanOrEqual`, `Contains`, `StartsWith`, or `EndsWith`. The three text searches require a string. `value` must not be `null`—use the null check for missing values
Field comparison	`new GatewayFilter.FieldComparison(field, op, otherField)`	Compares two columns of the same row; equality and ordering only
Null check	`new GatewayFilter.NullCheck(field, expectNull)`	`true`: the column is empty; `false`: the column has a value
Membership	`new GatewayFilter.Membership(field, values)`	The column equals one of the values; 1 to 20,000 values (`MaxValues`)
Logical	`new GatewayFilter.Logical(GatewayLogicalConnective.And` or `Or, operands)`	At least one operand
Negation	`new GatewayFilter.Negation(operand)`	Inverts the condition

A filter can be nested at most ten levels deep (GatewayFilter.MaxDepth).

Values. The client transmits bool, string, char, integers up to 64 bits, decimal, double, float, DateTime (without a time zone), DateTimeOffset, DateOnly, TimeOnly, and Guid. Any other type—enumerations, byte arrays, your own classes—is rejected with MalformedRequest before a request leaves the machine. Pass an enumeration explicitly as a number or as a name, depending on what the column stores.

Identifiers

Alias, object, column, and parameter names start with a letter or _, followed by letters, digits, _, @, #, or $; at most 128 characters per part. An invalid name throws ArgumentException when the object is created; an invalid argument name throws it when you call ReadAsync. The service keeps only letters, digits, and _ unchanged and encodes every other character, including @, #, and $. If a column's name in the database contains such characters (such as Value$, Weight (kg), or A&B), use the encoded form in select, filter, and orderBy, for example Value_x0024_ or A_x0026_B; the rule is described in the data service documentation under “Timestamps, numbers, and names.” The response carries the name the database uses.

What is called

GatewayRoutineRequest

new GatewayRoutineRequest(GatewayResource resource, IReadOnlyDictionary<string, object?>? arguments = null)

resource must be a procedure; otherwise ArgumentException. The arguments travel as JSON in the body; null and the values listed under “Values” are allowed.

What comes back

GatewayPage<TRow>

Property	Meaning
`Rows`	The rows that were read
`RequestedWindowSize`	The window size the service read with
`TotalCount`	Total number of matches; `null` if nobody counted—not the same as `0`
`HasMorePotentially`	`true` if the window is full; then there may be more, and you read the next window with `skip`

GatewayRoutineResult<TRow>

Property	Meaning
`Rows`	Rows of the procedure's first result set
`AffectedRowCount`	Rows changed, if the procedure returned no result set; otherwise `null`
`ReturnedRows`	`true` if the procedure returned a result set

GatewayRequestException

Carries a GatewayProblem in Problem with Kind, Message, CorrelationId, EngineMessages, HttpStatusCode, and IsTransient. What each kind means and how to handle it is described in A request fails with `GatewayRequestException`.