Programmierschnittstelle (Referenz)

Gilt für den Client 0.2.1 mit dem Vertragspaket Wkl.Data.Gateway.Contracts 0.6.0. Die Typen des Clients liegen im Namensraum Wkl.Data.Gateway.Client, die des Vertrags in Wkl.Data.Gateway.Contracts.

Registrierung

Methode	Wirkung
`services.AddGatewayClient(IConfiguration section)`	Bindet die Konfiguration an den übergebenen Abschnitt, üblicherweise `configuration.GetSection(GatewayClientOptions.SectionName)`
`services.AddGatewayClient(Action<GatewayClientOptions> configure)`	Dasselbe mit Einstellungen aus Code

Beide registrieren IGatewayClient (Implementierung GatewayHttpClient, einmal je Anwendung), die Prüfung der Einstellungen beim Start und zwei benannte HTTP-Clients für Lesen und Aufrufen mit eigenen Zeitgrenzen. Eine eigene IGatewayCorrelationSource, vor dem Aufruf registriert, ersetzt die Vorgabe. Die Vorgabe nimmt die Ablaufkennung (TraceId) der laufenden Activity im W3C-Format, bei einer Activity im älteren hierarchischen Format deren Id, ohne Activity eine neue GUID.

IGatewayClient

Methode	Zweck	Ergebnis
`ReadAsync<TRow>(GatewayQuery query, IReadOnlyDictionary<string, string>? arguments = null, CancellationToken ct = default)`	Liest ein Fenster aus Tabelle, Sicht oder Funktion. `arguments` nur bei einer Funktion: Name und Wert je Parameter als Text	`GatewayPage<TRow>`
`InvokeAsync<TRow>(GatewayRoutineRequest request, CancellationToken ct = default)`	Ruft eine Prozedur auf	`GatewayRoutineResult<TRow>`

Jede Methode setzt genau eine Anfrage ab. Scheitert sie, wirft sie GatewayRequestException (siehe Fehler des Dienstes behandeln); ein Abbruch über das CancellationToken des Aufrufers kommt als OperationCanceledException.

Zeilentyp TRow. Die Zeilen werden mit System.Text.Json gelesen. Spaltennamen werden ohne Rücksicht auf Groß- und Kleinschreibung mit den snake_case-Formen der Eigenschaftsnamen verglichen (ZuletztGeaendertUtc liest zuletzt_geaendert_utc). Eine Spalte, deren Name davon abweicht, braucht [JsonPropertyName("…")] mit dem Namen, den die Datenbank führt. JsonElement als TRow liest jede Zeile unverändert.

Was gelesen wird

GatewayResource

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

Parameter	Bedeutung
`databaseAlias`	Name der Datenquelle im Dienst, nicht der Name der Datenbank
`kind`	`Table`, `View`, `Function` oder `Procedure`
`name`	`objekt` oder `schema.objekt`

GatewayQuery

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

Parameter	Bedeutung
`resource`	Tabelle, Sicht oder Funktion. Eine Prozedur wird abgewiesen (`ArgumentException`)
`select`	Spalten, die gelesen werden. Leer: alle, die der Dienst anbietet
`filter`	Bedingung, siehe unten
`orderBy`	Folge von `GatewaySortField(string field, GatewaySortDirection direction)` mit `Ascending` oder `Descending`
`skip`	Zeilen, die übersprungen werden. Nicht negativ
`top`	Gewünschte Fenstergröße, größer als null. Der Dienst begrenzt sie auf seine Obergrenze; ohne Angabe nimmt er seine Voreinstellung
`includeTotalCount`	Lässt den Dienst zusätzlich zählen, wie viele Zeilen der Filter insgesamt trifft

Filter (GatewayFilter)

Art	Erzeugung	Bedeutung
Vergleich	`new GatewayFilter.Comparison(field, op, value)`	`op` ist `Equal`, `NotEqual`, `LessThan`, `LessThanOrEqual`, `GreaterThan`, `GreaterThanOrEqual`, `Contains`, `StartsWith` oder `EndsWith`. Die drei Textsuchen verlangen eine Zeichenkette. `value` darf nicht `null` sein – fehlende Werte prüft die Leerwertprüfung
Feldvergleich	`new GatewayFilter.FieldComparison(field, op, otherField)`	Vergleicht zwei Spalten derselben Zeile; nur Gleichheit und Reihenfolge
Leerwertprüfung	`new GatewayFilter.NullCheck(field, expectNull)`	`true`: Spalte ist leer; `false`: Spalte hat einen Wert
Mengenprüfung	`new GatewayFilter.Membership(field, values)`	Spalte gleicht einem der Werte; 1 bis 20 000 Werte (`MaxValues`)
Verknüpfung	`new GatewayFilter.Logical(GatewayLogicalConnective.And` oder `Or, operands)`	Mindestens ein Operand
Verneinung	`new GatewayFilter.Negation(operand)`	Kehrt die Bedingung um

Ein Filter darf höchstens zehn Ebenen tief verschachtelt sein (GatewayFilter.MaxDepth).

Werte. Übertragen werden bool, string, char, ganze Zahlen bis 64 Bit, decimal, double, float, DateTime (ohne Zeitzone), DateTimeOffset, DateOnly, TimeOnly und Guid. Jeder andere Typ – Aufzählungen, Bytefolgen, eigene Klassen – wird mit MalformedRequest abgewiesen, ohne dass eine Anfrage den Rechner verlässt. Eine Aufzählung übergeben Sie ausdrücklich als Zahl oder als Namen, je nachdem, was die Spalte speichert.

Bezeichner

Aliasnamen, Objektnamen, Spaltennamen und Parameternamen beginnen mit einem Buchstaben oder _, danach folgen Buchstaben, Ziffern, _, @, # oder $; höchstens 128 Zeichen je Teil. Ein ungültiger Name wirft ArgumentException beim Erzeugen des Objekts, ein ungültiger Argumentname beim Aufruf von ReadAsync. Der Dienst führt Namen nur mit Buchstaben, Ziffern und _ unverändert; jedes andere Zeichen kodiert er, auch @, # und $. Eine Spalte, deren Name in der Datenbank solche Zeichen enthält (etwa Wert$, Menge (kg) oder A&B), nennen Sie in select, filter und orderBy in der kodierten Form, etwa Wert_x0024_ oder A_x0026_B; die Regel steht in der Dokumentation des Datendienstes, „Zeitpunkte, Zahlen und Namen“. Die Antwort trägt den Namen, den die Datenbank führt.

Was aufgerufen wird

GatewayRoutineRequest

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

resource muss eine Prozedur sein, sonst ArgumentException. Die Argumente reisen als JSON im Rumpf; erlaubt sind null und die Werte aus dem Abschnitt „Werte“.

Was zurückkommt

GatewayPage<TRow>

Eigenschaft	Bedeutung
`Rows`	Die gelesenen Zeilen
`RequestedWindowSize`	Die Fenstergröße, mit der der Dienst gelesen hat
`TotalCount`	Gesamtzahl der Treffer; `null`, wenn nicht gezählt wurde – nicht dasselbe wie `0`
`HasMorePotentially`	`true`, wenn das Fenster voll ist; dann kann es eine Fortsetzung geben, und das nächste Fenster lesen Sie mit `skip`

GatewayRoutineResult<TRow>

Eigenschaft	Bedeutung
`Rows`	Zeilen des ersten Ergebnisses der Prozedur
`AffectedRowCount`	Geänderte Zeilen, wenn die Prozedur kein Ergebnis lieferte; sonst `null`
`ReturnedRows`	`true`, wenn die Prozedur ein Ergebnis lieferte

GatewayRequestException

Trägt in Problem ein GatewayProblem mit Kind, Message, CorrelationId, EngineMessages, HttpStatusCode und IsTransient. Bedeutung und Behandlung jeder Art stehen in Fehler des Dienstes behandeln.