Lesen und Aufrufen

In dieser Einführung binden Sie den Client in eine .NET-Anwendung ein, lesen Zeilen einer Sicht und rufen eine Prozedur auf.

Voraussetzungen

eine Konsolenanwendung mit Zielframework net10.0 und den Paketen Wkl.Data.Gateway.Client und Microsoft.Extensions.Hosting
ein laufender Datendienst und seine Adresse
eine Datenquelle im Dienst (im Beispiel fachdaten) mit einer Sicht container_typ (Spalten id, bezeichnung) und einer Prozedur stamm.farbe_speichern; die Namen ersetzen Sie durch Ihre eigenen
ein Schlüssel mit einer Regel, die die Sicht lesen und die Prozedur ausführen darf

Schritte

Schlüssel bereitstellen. Der Schlüssel steht in einer Umgebungsvariablen des Prozesses, nie in einer Datei der Anwendung:
```
$env:WKL_GATEWAY_API_KEY = '<Schlüssel>'
```
Adresse eintragen. In appsettings.json der Anwendung:
```
{ "GatewayClient": { "BaseAddress": "https://daten.example.com/" } }
```
Alle Einstellungen stehen in der Konfiguration.

Registrieren, lesen, aufrufen. Program.cs:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Wkl.Data.Gateway.Client;
using Wkl.Data.Gateway.Contracts;
 
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddGatewayClient(builder.Configuration.GetSection(GatewayClientOptions.SectionName));
using var host = builder.Build();
 
// Starting the host validates the settings; a missing BaseAddress stops the application here
await host.StartAsync();
 
var client = host.Services.GetRequiredService<IGatewayClient>();
 
// Read at most 100 rows whose description contains "DV", sorted by id, with the total count
var page = await client.ReadAsync<ContainerTyp>(new GatewayQuery(
    new GatewayResource("fachdaten", GatewayResourceKind.View, "container_typ"),
    select: ["id", "bezeichnung"],
    filter: new GatewayFilter.Comparison("bezeichnung", GatewayComparisonOperator.Contains, "DV"),
    orderBy: [new GatewaySortField("id", GatewaySortDirection.Ascending)],
    top: 100,
    includeTotalCount: true));
 
foreach (var row in page.Rows)
{
    Console.WriteLine($"{row.Id}: {row.Bezeichnung}");
}
 
Console.WriteLine($"{page.Rows.Count} of {page.TotalCount} rows");
 
// Call the procedure with two arguments; null is sent as SQL NULL
var result = await client.InvokeAsync<SpeicherErgebnis>(new GatewayRoutineRequest(
    new GatewayResource("fachdaten", GatewayResourceKind.Procedure, "stamm.farbe_speichern"),
    new Dictionary<string, object?> { ["ral_nummer"] = "RAL 5010", ["name_en"] = null }));
 
Console.WriteLine(result.ReturnedRows && result.Rows.Count > 0
    ? $"Saved as {result.Rows[0].Id}"
    : $"{result.AffectedRowCount} rows changed");
 
public sealed class ContainerTyp
{
    public int Id { get; init; }
 
    public string Bezeichnung { get; init; } = string.Empty;
}
 
public sealed class SpeicherErgebnis
{
    public int Id { get; init; }
}

Spaltennamen werden in snake_case auf gewöhnliche Eigenschaftsnamen abgebildet: ZuletztGeaendertUtc liest zuletzt_geaendert_utc (verglichen ohne Rücksicht auf Groß- und Kleinschreibung). Ein Attribut je Eigenschaft ist dafür nicht nötig – bei einigen hundert Spalten wäre es vor allem eine Stelle, an der man sich vertippt. Die Abbildung trifft aber nur Spalten, die selbst in snake_case heißen. Eine Spalte wie GeändertAm oder A&B braucht eine Eigenschaft mit [JsonPropertyName("…")] und genau diesem Namen; ohne sie bleibt die Eigenschaft still auf ihrem Vorgabewert, ohne Fehler. In select, filter und orderBy nennen Sie eine Spalte mit Zeichen außerhalb von Buchstaben, Ziffern und _ in der kodierten Form des Dienstes, etwa A_x0026_B für A&B (siehe Programmierschnittstelle). Wer die Zeilen unverändert braucht, liest auf JsonElement.

Ergebnis

Die Anwendung gibt die gelesenen Zeilen aus und danach, wie viele der Filter insgesamt trifft (page.TotalCount ist nur gesetzt, weil includeTotalCount gesetzt ist). Liefert die Prozedur eine Ergebniszeile, nennt die letzte Ausgabe deren id, sonst die Zahl der geänderten Zeilen.

Nächste Schritte

Grenzen und Eigenschaften – vor allem: TotalCount darf fehlen
Fehler des Dienstes behandeln
Programmierschnittstelle