Skip to content

Releases

v1.0.0

Choose a tag to compare

@github-actions github-actions released this 06 Nov 09:29
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.NbpGoldPric...
Read more