OpenUrzednik.Nbp 1.0.35-preview.g216ea16a82

OpenUrzednik.Nbp

🇬🇧 English version

Klient NBP (Narodowy Bank Polski) dla OpenUrzednik.NET — kursy walut oraz ceny złota z API Narodowego Banku Polskiego.

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

Status

🧪 Wersja preview — dostępne są klienty kursów walut (NbpCurrencyExchangeRateClient), tabel kursów (NbpExchangeRateTableClient) i cen złota (NbpGoldPriceClient). Publiczne API może się jeszcze zmienić przed wydaniem stabilnym.

Instalacja

dotnet add package OpenUrzednik.Nbp

Wymaga OpenUrzednik.Core i OpenUrzednik.Http (instalowane automatycznie jako zależności).

Użycie

Najprostszy wariant: domyślny adres API NBP i limit czasu z HttpClient.

using var httpClient = new HttpClient();
var client = new NbpGoldPriceClient(httpClient);

var result = await client.GetLatestAsync();
if (result.IsSuccess)
    Console.WriteLine($"{result.Value.Date}: {result.Value.Price} zł");
else
    Console.WriteLine(result.Errors[0].Message);

Własny adres (np. proxy albo bramki API) i limit czasu przekazujesz w NbpOptions. Klient nie zmienia HttpClient, więc możesz go współdzielić z innym kodem:

var client = new NbpCurrencyExchangeRateClient(httpClient, new NbpOptions
{
    ApiUrl = "https://proxy.example.com/nbp/",
    Timeout = TimeSpan.FromSeconds(5),
});

Z kontenerem DI użyj pakietu OpenUrzednik.Nbp.DependencyInjection: builder.Services.AddOpenUrzednikNbp() rejestruje wszystkie trzy klienty, a .AddStandardResilienceHandler() dodaje ponowienia.

Klient bierze adres API z pierwszego ustawionego miejsca: NbpOptions.ApiUrl, HttpClient.BaseAddress, a na końcu domyślny https://api.nbp.pl/api/. Jeśli nie ustawisz NbpOptions.Timeout, obowiązuje limit czasu HttpClient (domyślnie 100 s). NbpOptions.Timeout może ten limit skrócić, ale nie wydłużyć, bo HttpClient.Timeout nadal obowiązuje do otrzymania nagłówków odpowiedzi. Adres API nie może zawierać zapytania (?…) ani fragmentu (#…).

Błędy, takie jak brak danych, przekroczony limit zapytań albo upływ limitu czasu, wracają w wyniku, a nie jako wyjątki. Jeśli wolisz wyjątki, wywołaj na wyniku EnsureSuccess().

.NET Framework

Pakiet działa też na .NET Framework (przez netstandard2.0). Tam daty są typu DateTime, a nie DateOnly: metody przyjmują DateTime i zwracają go w modelach (np. GoldPrice.Date). Liczy się tylko data: godzinę klient pomija, a zwracane daty mają godzinę 00:00 i DateTimeKind.Unspecified.

Jeśli piszesz bibliotekę, która korzysta z tego pakietu, kompiluj ją na te same platformy (np. netstandard2.0;net8.0). Biblioteka tylko dla netstandard2.0 wywołuje metody z DateTime, a w aplikacji .NET 8+ NuGet wybierze wersję z DateOnly, więc dostaniesz MissingMethodException.

Logowanie i śledzenie

Klienty przyjmują opcjonalne parametry logger i traceSource. Bez nich nic nie logują i nie tworzą spanów. Żeby korzystać z ILogger i OpenTelemetry, zainstaluj adaptery OpenUrzednik.Extensions.Logging i OpenUrzednik.Diagnostics:

using OpenUrzednik.Diagnostics;
using OpenUrzednik.Extensions.Logging;
using OpenUrzednik.Nbp;
using OpenUrzednik.Nbp.Gold;

var client = new NbpGoldPriceClient(httpClient,
    logger: loggerFactory.CreateOpenUrzednikLogger<NbpGoldPriceClient>(),
    traceSource: ActivityTraceSource.GetShared(NbpTelemetry.SourceName));

Spany trafiają do źródła OpenUrzednik.Nbp, a logi do kategorii z pełną nazwą klienta (np. OpenUrzednik.Nbp.Gold.NbpGoldPriceClient).

Klienty używają własnych interfejsów (IOpenUrzednikLogger, IOpenUrzednikTraceSource z OpenUrzednik.Core), a nie ILogger i ActivitySource. Dzięki temu ten pakiet nie potrzebuje Microsoft.Extensions.Logging.Abstractions ani innych pakietów do logowania i śledzenia. Z ILogger i ActivitySource łączą go dopiero adaptery.