Skip to content

v1.0.0

Latest

Choose a tag to compare

@github-actions github-actions released this 06 Nov 09:29
· 200 commits to develop since this release
5e90165

OpenUrzednik.NET 1.0.0

The first stable release of the unofficial .NET clients for the NBP API: OpenUrzednik.Core, OpenUrzednik.Nbp, OpenUrzednik.Nbp.DependencyInjection, OpenUrzednik.Extensions.Logging and OpenUrzednik.Diagnostics. From this version on, minor and patch releases don't break the public API, the error contract or the telemetry names (Versioning and support).

Upgrading

  • Update all OpenUrzednik packages together, with an explicit version. The early previews were numbered 1.0.N-preview (up to 1.0.36-preview for OpenUrzednik.Nbp), and NuGet sorts 1.0.0 below them, so it won't offer 1.0.0 as an update from one of those. Set 1.0.0 on every OpenUrzednik package yourself, e.g. dotnet add package OpenUrzednik.Nbp --version 1.0.0. Mixing 1.0.0 with a preview can fail the restore with NU1605 (package downgrade) or silently keep a preview. Those previews are unlisted on nuget.org. From a 0.1.0-preview.N or 1.0.0-preview.N version, NuGet offers 1.0.0 as usual.

  • Remove any reference to OpenUrzednik.Http. It is no longer a package: its code is compiled into the provider packages, and its types are internal (#153). The 1.0.0 packages don't depend on it. OpenUrzednik.Gus, OpenUrzednik.Krs and OpenUrzednik.Mf aren't published either (#52).

  • Dates are DateTime on every target (ADR-0005, #157). The .NET builds used DateOnly for method parameters and model dates. The time of day and Kind of an argument are ignored, and returned dates are midnight with DateTimeKind.Unspecified. Calls with a DateOnly still compile on .NET 8 and later, through the NbpDateOnlyExtensions extension methods, but:

    • a mock setup like client.GetAsync(Arg.Any<DateOnly>()) compiles against the extension method and no longer matches the interface method; set up Arg.Any<DateTime>() instead;
    • positional deconstruction of a model into DateOnly variables no longer compiles;
    • System.Text.Json writes model dates as "2026-10-02T00:00:00" instead of "2026-10-02", which changes the JSON of an API that returns the models.

    See Dates and .NET Framework.

  • Targets: netstandard2.0, net8.0 and net10.0. net9.0 was dropped; .NET 9 apps get the net8.0 build with the same API (#134). .NET Framework 4.7.2 or later uses netstandard2.0 (#39). See Supported platforms.

  • Dependency minimums:

    • OpenUrzednik.Core, OpenUrzednik.Nbp and OpenUrzednik.Diagnostics have no package dependencies on .NET 8 and .NET 10. On netstandard2.0, OpenUrzednik.Nbp needs System.Text.Json, System.Net.Http.Json and Microsoft.Bcl.TimeProvider 10.0.14 and Microsoft.Bcl.HashCode 6.0.0; OpenUrzednik.Diagnostics needs System.Diagnostics.DiagnosticSource 10.0.14.
    • OpenUrzednik.Extensions.Logging needs Microsoft.Extensions.Logging.Abstractions 8.0.0 or later (#40).
    • OpenUrzednik.Nbp.DependencyInjection needs Microsoft.Extensions.Http 8.0.1 and Microsoft.Extensions.Options 8.0.2 on net8.0, both 10.0.14 on net10.0 and netstandard2.0, and Polly.Core 8.8.1. A .NET 8 app now stays on Microsoft.Extensions 8.x; the previews brought in 10.x (#137). If your .NET 8 app used a 10.x-only Microsoft.Extensions API without referencing that package itself, reference it now. See Dependencies.
  • Code written against a preview: go through the breaking changes below. Each line says what to change.

Changes since the previews

💥 Breaking changes

  • The clients lost their Default prefix: NbpGoldPriceClient, NbpCurrencyExchangeRateClient, NbpExchangeRateTableClient (#6).
  • Clients, their interfaces and NbpOptions moved to the OpenUrzednik.Nbp namespace; models stay in .Currency, .Table and .Gold, and .Options is gone. OpenUrzednik.Core.Extensions is gone too: EnsureSuccess() and And() are instance methods, the Task<…> extensions are in OpenUrzednik.Core, and RecordError/RecordErrors in OpenUrzednik.Core.Telemetry (#156).
  • Table B: GetCountry* and CountryExchangeRates are removed. The mid-rate currency methods take TableType table = TableType.A before the token, so a token passed by position must now be named (cancellationToken: token) (#13).
  • Rate types renamed: Currency.ExchangeRate → CurrencyRate, Currency.BuySellExchangeRate → CurrencyBuySellRate, Table.ExchangeRate → TableRate, Table.BuySellExchangeRate → TableBuySellRate (#22). The table C properties Buy and Sell are now Ask and Bid, after the API's fields; the positional order is unchanged (#47).
  • Construction: HttpClientExtensions.ConfigureForNbpApi is removed, and the clients no longer change the HttpClient; pass NbpOptions to the constructor. NbpOptions.Timeout is optional, and when it is unset the HttpClient timeout applies (100 s by default, was 10 s). NbpOptions.ApiUrl defaults to null, and an http:// BaseAddress or one with a query throws ArgumentException (#28). The URL builders, their factory and NbpTable are internal, and the full constructor has no urlBuilderFactory parameter; for a gateway, use ApiUrl and a DelegatingHandler (#154, API gateways).
  • Public dates are DateTime on every target; see Upgrading (#157).
  • Network failures, timeouts and bad payloads are returned as errors, no longer thrown as HttpRequestException or TaskCanceledException; reading the body also counts against the timeout (#18). HTTP statuses map to specific errors: 400 BadRequestError with NBP's message, 401/403 UnauthorizedError, 408 RequestTimeoutError, 5xx ServiceUnavailableError; DNS, TLS and connection failures are ConnectionFailedError (#16, #161).
  • Error codes renamed: validationError → validation, serializationError → serialization, unknownError → unknown (#161). Read the status code with GetHttpStatusCode() or TryGetHttpStatusCode(); OpenUrzednikError.StatusCodeMetadataKey became HttpErrorMetadata.StatusCodeKey (still "statusCode") (#188).
  • Exceptions: ValidationException → OpenUrzednikValidationException and SerializationException → OpenUrzednikSerializationException (#62). EnsureSuccess() no longer throws AggregateException or a raw JsonException (#17, #29). ToException() returns OpenUrzednikException; a custom error implements CreateException() instead (#29).
  • default(OpenUrzednikResult<T>) is a failure, no longer a success holding default(T) (#15).
  • A null currency or an undefined TableType throws ArgumentNullException or ArgumentOutOfRangeException from the call instead of returning a ValidationError (#158). EnsureSuccessAsync, MapAsync and BindAsync throw for a null argument at the call, not from the returned task (#181).
  • NbpGoldPriceClient, NbpCurrencyExchangeRateClient, NbpExchangeRateTableClient and NbpOptions are sealed (#164).
  • Every assembly is strong-named (public key token e8d5ca0d09eb5ce1), and the assembly version is 1.0.0.0 for every 1.x release; update binding redirects on .NET Framework (#165).
  • Telemetry names: span names nbp.*.get_date and nbp.*.get_range → nbp.*.date and nbp.*.range (#31); tags http.path → url.path (now the absolute path) and http.status_code → http.response.status_code (#33); error.code → error.type (#163). Update dashboards and queries.
  • Logging: every IOpenUrzednikLogger.Log overload takes an OpenUrzednikEventId, so a custom logger must be updated (#163). The logger category is the client's full type name (e.g. OpenUrzednik.Nbp.NbpGoldPriceClient): a filter on OpenUrzednik.Nbp still matches, but filters on OpenUrzednik.Nbp.Currency, .Table or .Gold no longer do (#156).

🚀 Features

  • OpenUrzednik.Nbp.DependencyInjection: AddOpenUrzednikNbp() registers the clients with validated options, logging and tracing, and turns resilience-handler rejections into errors (#34); AddOpenUrzednikNbpRejectionHandler() does that for clients you register yourself (#187); AddKeyedOpenUrzednikNbp(key) registers several NBP setups as keyed services (#189). See the DI README.
  • Get…LastPublishedBeforeAsync on every NBP client: the last publication strictly before a date, as Polish tax and accounting rules use it (#198, The last rate before a date).
  • Result API: Map, Bind, BindAsync, Match, TryGetValue, MapAsync/BindAsync on Task<…>, and OpenUrzednikException.Error/Errors with the original errors (#29, Working with a result).
  • New errors: BadRequestError, RequestTimeoutError and ConnectionFailedError, with public metadata keys (#16, #18, #161, Errors).
  • Logging and tracing in the NBP clients (#5), with adapters to ILogger (OpenUrzednik.Extensions.Logging) and ActivitySource (OpenUrzednik.Diagnostics) (#33). Log event ids in NbpLogEvents, and on .NET a client without a trace source records its spans on OpenUrzednik.Nbp (#163). The HTTP span has server.address and server.port (#186). See the telemetry reference.
  • netstandard2.0 target for .NET Framework 4.7.2 or later (#39).
  • The .NET builds are trimming- and Native AOT-compatible, checked in CI by publishing a Native AOT app (#55, #195).
  • Runnable samples: a console app and a minimal Web API (#60).

🐞 Bug fixes

  • Table B calls failed with a SerializationError against the real API (#13).
  • Rates and tables A and C published before 2004-05-04 failed with a SerializationError; their CurrencyName is now empty (#201).
  • HTTP request and response messages are disposed, so a failed response no longer holds its connection (#14).
  • Dates in URLs, messages and span tags are formatted invariantly; under a culture such as th-TH the URLs had a non-Gregorian year (#19).
  • NbpGoldPriceClient methods default their CancellationToken (#20).
  • The client checks the API's limits before sending (top count, date ranges of 367 or 93 days, future dates), so a request the API would reject returns a ValidationError (#21, #46).
  • Each package shows its own README on nuget.org (#54).

📚 Documentation

  • Publication times, API limits and thread safety in the XML docs and the NBP README (#23, #66, #171).
  • English is the main documentation language; the package READMEs have Polish versions of the introduction and quick start (#58, #130).
  • Compatibility, versioning, support and security policies (#164, #173).
  • How to correlate client logs with traces (#200).

Full changelog: https://github.com/milten89/OpenUrzednik.NET/commits/v1.0.0