OpenUrzednik.Nbp.DependencyInjection 1.0.17-preview.g216ea16a82

OpenUrzednik.Nbp.DependencyInjection

🇬🇧 English version

Rejestracja klientów NBP z OpenUrzednik.Nbp w Microsoft.Extensions.DependencyInjection: klienty typowane z IHttpClientFactory, sprawdzane opcje, logowanie i śledzenie.

Część zestawu OpenUrzednik.NET — zobacz główne README po pełny przegląd projektu.

Instalacja

dotnet add package OpenUrzednik.Nbp.DependencyInjection

Użycie

builder.Services.AddOpenUrzednikNbp();

public sealed class RatesService(INbpCurrencyExchangeRateClient rates)
{
    public Task<OpenUrzednikResult<CurrencyExchangeRates>> GetUsdAsync(CancellationToken cancellationToken)
        => rates.GetLatestAsync("USD", cancellationToken: cancellationToken);
}

Rejestrowane są INbpCurrencyExchangeRateClient, INbpExchangeRateTableClient i INbpGoldPriceClient (oraz ich klasy). Wszystkie korzystają z jednego nazwanego HttpClient ("OpenUrzednik.Nbp"). Klienty są rejestrowane jako transient, jak zwykle przy IHttpClientFactory: nie wstrzykuj ich do singletonów, bo taki singleton zatrzyma jeden HttpClient na zawsze i nie zauważy zmian DNS.

Opcje ustawiasz w lambdzie:

builder.Services.AddOpenUrzednikNbp(options =>
{
    options.ApiUrl = "https://proxy.example.com/nbp/";
    options.Timeout = TimeSpan.FromSeconds(10);
});

Błędne opcje (np. adres http://) zatrzymują start aplikacji wyjątkiem OptionsValidationException.

Ponowienia i limity czasu

Pakiet sam nie dodaje ponowień ani limitów czasu. Zwraca IHttpClientBuilder, więc dodajesz je standardowym API Microsoftu z pakietu Microsoft.Extensions.Http.Resilience:

builder.Services.AddOpenUrzednikNbp()
    .AddStandardResilienceHandler();

NbpOptions.Timeout obejmuje wszystkie próby razem, więc jeśli jest krótszy niż łączny limit handlera, przerwie ponowienia. Z handlerem go nie ustawiaj albo daj mu więcej czasu niż handlerowi.

Domyślnie handler ponawia zapytanie do 3 razy przy statusach 5xx, 408 i 429 (z uwzględnieniem Retry-After). Każda próba ma 10 s, całe zapytanie 30 s. Handler ma też circuit breaker i rate limiter. Szczegóły i zmianę ustawień (np. options.Retry.MaxRetryAttempts = 5) opisuje dokumentacja Microsoftu. Dodaj jeden taki handler, nie kilka. Jeśli aplikacja dodaje go już wszystkim klientom przez ConfigureHttpClientDefaults (jak szablon .NET Aspire), nie dodawaj drugiego. Na .NET Framework pakiety Microsoft.Extensions.Http.Resilience 10.x ostrzegają przy kompilacji, że nie wspierają tej platformy.

Gdy handler odrzuci zapytanie, dostajesz błąd w wyniku, a nie wyjątek: przekroczony czas to RequestTimeoutError, a otwarty circuit breaker albo rate limiter to ServiceUnavailableError. Anulowanie przez wywołującego nadal rzuca OperationCanceledException.

Logowanie i śledzenie

Klienty logują przez zarejestrowany ILoggerFactory. Kategorią jest pełna nazwa klienta (np. OpenUrzednik.Nbp.Gold.NbpGoldPriceClient). Spany trafiają do źródła OpenUrzednik.Nbp, które w OpenTelemetry włączysz przez AddSource("OpenUrzednik.*").

Jeśli zarejestrujesz własny TimeProvider albo INbpUrlBuilderFactory, klienty użyją ich zamiast domyślnych.