Das Windows-Programm als Client der API

dotnet new classlib -n Brandt.Auftragsbuch.Client -f net10.0
Remove-Item Brandt.Auftragsbuch.Client/Class1.cs
dotnet sln Brandt.Auftragsbuch.sln add Brandt.Auftragsbuch.Client/Brandt.Auftragsbuch.Client.csproj
dotnet add Brandt.Auftragsbuch.Client/Brandt.Auftragsbuch.Client.csproj reference Brandt.Auftragsbuch.Vertraege/Brandt.Auftragsbuch.Vertraege.csproj
dotnet add Brandt.Auftragsbuch.Client/Brandt.Auftragsbuch.Client.csproj package Microsoft.Extensions.Http.Resilience --version "10.*"
dotnet add Brandt.Auftragsbuch/Brandt.Auftragsbuch.csproj reference Brandt.Auftragsbuch.Client/Brandt.Auftragsbuch.Client.csproj

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <TargetFramework>net10.0</TargetFramework>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="10.*" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\Brandt.Auftragsbuch.Vertraege\Brandt.Auftragsbuch.Vertraege.csproj" />
  </ItemGroup>

</Project>

namespace Brandt.Auftragsbuch.Client;

public enum ApiFehlerArt
{
    NichtErreichbar,
    Zeitueberschreitung,
    NichtGefunden,
    Konflikt,
    Ungueltig,
    Serverfehler,
    Unerwartet,
}

public sealed record ApiFehler(ApiFehlerArt Art, string Meldung, IReadOnlyDictionary<string, string[]>? Felder = null);

// Erwartbare Fehler sind ein Ergebnis, keine Ausnahme: Ein Formular muss sie anzeigen können, ohne try/catch an jeder Stelle.
public sealed class ApiErgebnis<T>
{
    private readonly T? _wert;

    private ApiErgebnis(T? wert, ApiFehler? fehler)
    {
        _wert = wert;
        Fehler = fehler;
    }

    public ApiFehler? Fehler { get; }

    public bool IstOk => Fehler is null;

    public T Wert => IstOk ? _wert! : throw new InvalidOperationException(Fehler!.Meldung);

    public static ApiErgebnis<T> Erfolg(T wert) => new(wert, null);

    public static ApiErgebnis<T> Misserfolg(ApiFehler fehler) => new(default, fehler);
}

using System.Net;
using System.Net.Http.Json;
using System.Text.Json;
using Brandt.Auftragsbuch.Logik;
using Brandt.Auftragsbuch.Vertraege;
using Polly.Timeout;

namespace Brandt.Auftragsbuch.Client;

public interface IAuftragsApi
{
    Task<ApiErgebnis<AuftragsSeite>> LesenAsync(AuftragsStatus? status, int seite, int seitengroesse, CancellationToken ct = default);

    Task<ApiErgebnis<AuftragDetailDto>> EinzelnLesenAsync(int auftragId, CancellationToken ct = default);

    Task<ApiErgebnis<AuftragDetailDto>> AendernAsync(int auftragId, AuftragAenderungDto aenderung, CancellationToken ct = default);

    Task<ApiErgebnis<AbrechnungDto>> AbrechnenAsync(int auftragId, CancellationToken ct = default);
}

public sealed class AuftragsApiClient(HttpClient http) : IAuftragsApi
{
    private static readonly JsonSerializerOptions Json = VertragsJson.Neu();

    public Task<ApiErgebnis<AuftragsSeite>> LesenAsync(AuftragsStatus? status, int seite, int seitengroesse, CancellationToken ct = default)
    {
        string abfrage = $"seite={seite}&seitengroesse={seitengroesse}" + (status is { } gewaehlt ? $"&status={gewaehlt}" : string.Empty);
        return SendenAsync<AuftragsSeite>(() => http.GetAsync($"api/v1/auftraege?{abfrage}", ct), ct);
    }

    public Task<ApiErgebnis<AuftragDetailDto>> EinzelnLesenAsync(int auftragId, CancellationToken ct = default) =>
        SendenAsync<AuftragDetailDto>(() => http.GetAsync($"api/v1/auftraege/{auftragId}", ct), ct);

    public Task<ApiErgebnis<AuftragDetailDto>> AendernAsync(int auftragId, AuftragAenderungDto aenderung, CancellationToken ct = default) =>
        SendenAsync<AuftragDetailDto>(() => http.PutAsJsonAsync($"api/v1/auftraege/{auftragId}", aenderung, Json, ct), ct);

    public Task<ApiErgebnis<AbrechnungDto>> AbrechnenAsync(int auftragId, CancellationToken ct = default) =>
        SendenAsync<AbrechnungDto>(() => http.PostAsync($"api/v1/auftraege/{auftragId}/abrechnung", null, ct), ct);

    private static async Task<ApiErgebnis<T>> SendenAsync<T>(Func<Task<HttpResponseMessage>> senden, CancellationToken ct)
    {
        try
        {
            using HttpResponseMessage antwort = await senden();
            if (!antwort.IsSuccessStatusCode)
            {
                return ApiErgebnis<T>.Misserfolg(await FehlerLesenAsync(antwort, ct));
            }

            T? wert = await antwort.Content.ReadFromJsonAsync<T>(Json, ct);
            return wert is null
                ? ApiErgebnis<T>.Misserfolg(new ApiFehler(ApiFehlerArt.Unerwartet, "Die Antwort der API war leer."))
                : ApiErgebnis<T>.Erfolg(wert);
        }
        catch (TimeoutRejectedException)
        {
            // Die Zeitgrenze der Widerstandsfähigkeitsschicht (siehe Registrierung).
            return ApiErgebnis<T>.Misserfolg(new ApiFehler(ApiFehlerArt.Zeitueberschreitung, "Die API hat nicht rechtzeitig geantwortet."));
        }
        catch (TaskCanceledException) when (!ct.IsCancellationRequested)
        {
            // HttpClient.Timeout: ein TaskCanceledException, den nicht der Aufrufer ausgelöst hat.
            return ApiErgebnis<T>.Misserfolg(new ApiFehler(ApiFehlerArt.Zeitueberschreitung, "Die API hat nicht rechtzeitig geantwortet."));
        }
        catch (HttpRequestException ex)
        {
            return ApiErgebnis<T>.Misserfolg(new ApiFehler(ApiFehlerArt.NichtErreichbar, "Die API ist nicht erreichbar: " + ex.Message));
        }
        catch (JsonException)
        {
            return ApiErgebnis<T>.Misserfolg(new ApiFehler(ApiFehlerArt.Unerwartet, "Die Antwort der API ist nicht lesbar."));
        }
    }

    private static async Task<ApiFehler> FehlerLesenAsync(HttpResponseMessage antwort, CancellationToken ct)
    {
        ProblemAntwort? problem = null;
        try
        {
            problem = await antwort.Content.ReadFromJsonAsync<ProblemAntwort>(Json, ct);
        }
        catch (JsonException)
        {
            // Kein Problem-JSON, zum Beispiel die Fehlerseite eines Proxys: Es bleibt beim Statuscode.
        }

        string meldung = problem?.Title ?? $"Die API antwortete mit {(int)antwort.StatusCode}.";
        ApiFehlerArt art = antwort.StatusCode switch
        {
            HttpStatusCode.NotFound => ApiFehlerArt.NichtGefunden,
            HttpStatusCode.Conflict => ApiFehlerArt.Konflikt,
            HttpStatusCode.BadRequest or HttpStatusCode.UnprocessableEntity => ApiFehlerArt.Ungueltig,
            >= HttpStatusCode.InternalServerError => ApiFehlerArt.Serverfehler,
            _ => ApiFehlerArt.Unerwartet,
        };
        return new ApiFehler(art, meldung, problem?.Errors);
    }

    // Das Problem-JSON der API (RFC 9457), soweit der Client es braucht.
    private sealed record ProblemAntwort(string? Title, string? Detail, int? Status, Dictionary<string, string[]>? Errors);
}