Programski vmesnik

Velja za odjemalca 0.2.1 s paketom specifikacije vmesnika Wkl.Data.Gateway.Contracts 0.6.0. Tipi odjemalca so v imenskem prostoru Wkl.Data.Gateway.Client, tipi specifikacije vmesnika v Wkl.Data.Gateway.Contracts.

Registracija

Metoda	Učinek
`services.AddGatewayClient(IConfiguration section)`	Poveže konfiguracijo s podanim razdelkom, običajno `configuration.GetSection(GatewayClientOptions.SectionName)`
`services.AddGatewayClient(Action<GatewayClientOptions> configure)`	Enako, z nastavitvami iz kode

Obe registrirata IGatewayClient (izvedba GatewayHttpClient, ena na aplikacijo), preverjanje nastavitev ob zagonu in dva poimenovana odjemalca HTTP za branje in klicanje, vsakega s svojo časovno omejitvijo. Če želite privzeti vir korelacije zamenjati, pred klicem registrirajte lasten IGatewayCorrelationSource; privzeti vir uporabi identifikator sledi (TraceId) trenutne Activity v obliki W3C, pri Activity v starejši hierarhični obliki njen Id, brez Activity pa nov GUID.

IGatewayClient

Metoda	Namen	Rezultat
`ReadAsync<TRow>(GatewayQuery query, IReadOnlyDictionary<string, string>? arguments = null, CancellationToken ct = default)`	Prebere okno iz tabele, pogleda ali funkcije. `arguments` samo pri funkciji: ime in vrednost vsakega parametra kot besedilo	`GatewayPage<TRow>`
`InvokeAsync<TRow>(GatewayRoutineRequest request, CancellationToken ct = default)`	Pokliče proceduro	`GatewayRoutineResult<TRow>`

Vsaka metoda pošlje natanko eno zahtevo. Če ne uspe, vrže GatewayRequestException (glejte Zahteva ne uspe z `GatewayRequestException`); preklic prek CancellationToken klicatelja prispe kot OperationCanceledException.

Tip vrstice TRow. Vrstice se berejo s System.Text.Json. Imena stolpcev se brez upoštevanja velikih in malih črk primerjajo z obliko snake_case imen lastnosti (ZadnjaSprememba bere zadnja_sprememba). Stolpec, katerega ime se od tega razlikuje, potrebuje [JsonPropertyName("…")] z imenom, ki ga uporablja podatkovna zbirka. Z JsonElement kot TRow se vsaka vrstica prebere nespremenjena.

Kaj se bere

GatewayResource

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

Parameter	Pomen
`databaseAlias`	Ime vira podatkov v prehodu, ne ime podatkovne zbirke
`kind`	`Table`, `View`, `Function` ali `Procedure`
`name`	`objekt` ali `shema.objekt`

GatewayQuery

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

Parameter	Pomen
`resource`	Tabela, pogled ali funkcija. Procedura se zavrne (`ArgumentException`)
`select`	Stolpci, ki se preberejo. Prazno: vsi, ki jih prehod ponuja
`filter`	Pogoj, glejte spodaj
`orderBy`	Zaporedje `GatewaySortField(string field, GatewaySortDirection direction)` z `Ascending` ali `Descending`
`skip`	Vrstice, ki se preskočijo. Ne sme biti negativno
`top`	Želena velikost okna, večja od nič. Prehod jo omeji na svojo zgornjo mejo; brez navedbe uporabi svojo privzeto vrednost
`includeTotalCount`	Prehod naj dodatno prešteje, koliko vrstic filter zadene skupaj

Filtri (GatewayFilter)

Vrsta	Ustvarjanje	Pomen
Primerjava	`new GatewayFilter.Comparison(field, op, value)`	`op` je `Equal`, `NotEqual`, `LessThan`, `LessThanOrEqual`, `GreaterThan`, `GreaterThanOrEqual`, `Contains`, `StartsWith` ali `EndsWith`. Tri iskanja po besedilu zahtevajo niz. `value` ne sme biti `null` – manjkajoče vrednosti preverja preverjanje prazne vrednosti
Primerjava polj	`new GatewayFilter.FieldComparison(field, op, otherField)`	Primerja dva stolpca iste vrstice; samo enakost in vrstni red
Preverjanje prazne vrednosti	`new GatewayFilter.NullCheck(field, expectNull)`	`true`: stolpec je prazen; `false`: stolpec ima vrednost
Pripadnost množici	`new GatewayFilter.Membership(field, values)`	Stolpec je enak eni od vrednosti; od 1 do 20.000 vrednosti (`MaxValues`)
Povezava	`new GatewayFilter.Logical(GatewayLogicalConnective.And` ali `Or, operands)`	Vsaj en operand
Zanikanje	`new GatewayFilter.Negation(operand)`	Obrne pogoj

Filter je lahko ugnezden največ deset ravni globoko (GatewayFilter.MaxDepth).

Vrednosti. Prenašajo se bool, string, char, cela števila do 64 bitov, decimal, double, float, DateTime (brez časovnega pasu), DateTimeOffset, DateOnly, TimeOnly in Guid. Vsak drug tip – naštevanja, zaporedja bajtov, lastni razredi – se zavrne z MalformedRequest, še preden zahteva zapusti računalnik. Naštevanje podajte izrecno kot število ali kot ime, odvisno od tega, kaj hrani stolpec.

Identifikatorji

Imena aliasov, objektov, stolpcev in parametrov se začnejo s črko ali _, sledijo jim črke, števke, _, @, # ali $; največ 128 znakov na del. Neveljavno ime vrže ArgumentException že ob ustvarjanju objekta, neveljavno ime argumenta pa ob klicu ReadAsync. Prehod ohrani nespremenjene samo črke, števke in _, vse druge znake kodira, tudi @, # in $. Če ime stolpca v podatkovni zbirki vsebuje take znake (na primer Vrednost$, Teža (kg) ali A&B), ga v select, filter in orderBy navedite v kodirani obliki, na primer Vrednost_x0024_ ali A_x0026_B; pravilo je opisano v dokumentaciji podatkovnega prehoda, „Časovne točke, števila in imena“. Odgovor vsebuje ime, ki ga uporablja podatkovna zbirka.

Kaj se kliče

GatewayRoutineRequest

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

resource mora biti procedura, sicer ArgumentException. Argumenti se pošljejo kot JSON v telesu; dovoljeni so null in vrednosti iz razdelka „Vrednosti“.

Kaj se vrne

GatewayPage<TRow>

Lastnost	Pomen
`Rows`	Prebrane vrstice
`RequestedWindowSize`	Velikost okna, s katero je prehod bral
`TotalCount`	Skupno število zadetkov; `null`, če ni nihče štel – ni isto kot `0`
`HasMorePotentially`	`true`, če je okno polno; tedaj je morda še nadaljevanje, naslednje okno pa preberete s `skip`

GatewayRoutineResult<TRow>

Lastnost	Pomen
`Rows`	Vrstice prvega niza rezultatov procedure
`AffectedRowCount`	Spremenjene vrstice, če procedura ni vrnila niza rezultatov; sicer `null`
`ReturnedRows`	`true`, če je procedura vrnila niz rezultatov

GatewayRequestException

V Problem vsebuje GatewayProblem z Kind, Message, CorrelationId, EngineMessages, HttpStatusCode in IsTransient. Kaj pomeni posamezna vrsta in kako jo obravnavati, je opisano v Zahteva ne uspe z `GatewayRequestException`.