Repository navigation
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 to1.0.36-previewfor OpenUrzednik.Nbp), and NuGet sorts1.0.0below them, so it won't offer 1.0.0 as an update from one of those. Set1.0.0on 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 a0.1.0-preview.Nor1.0.0-preview.Nversion, 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.KrsandOpenUrzednik.Mfaren't published either (#52). -
Dates are
DateTimeon every target (ADR-0005, #157). The .NET builds usedDateOnlyfor method parameters and model dates. The time of day andKindof an argument are ignored, and returned dates are midnight withDateTimeKind.Unspecified. Calls with aDateOnlystill compile on .NET 8 and later, through theNbpDateOnlyExtensionsextension methods, but:- a mock setup like
client.GetAsync(Arg.Any<DateOnly>())compiles against the extension method and no longer matches the interface method; set upArg.Any<DateTime>()instead; - positional deconstruction of a model into
DateOnlyvariables 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.
- a mock setup like
-
Targets:
netstandard2.0,net8.0andnet10.0.net9.0was dropped; .NET 9 apps get thenet8.0build with the same API (#134). .NET Framework 4.7.2 or later usesnetstandard2.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 needsSystem.Text.Json,System.Net.Http.JsonandMicrosoft.Bcl.TimeProvider10.0.14 andMicrosoft.Bcl.HashCode6.0.0; OpenUrzednik.Diagnostics needsSystem.Diagnostics.DiagnosticSource10.0.14. - OpenUrzednik.Extensions.Logging needs
Microsoft.Extensions.Logging.Abstractions8.0.0 or later (#40). - OpenUrzednik.Nbp.DependencyInjection needs
Microsoft.Extensions.Http8.0.1 andMicrosoft.Extensions.Options8.0.2 onnet8.0, both 10.0.14 onnet10.0andnetstandard2.0, andPolly.Core8.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.
- OpenUrzednik.Core, OpenUrzednik.Nbp and OpenUrzednik.Diagnostics have no package dependencies on .NET 8 and .NET 10. On
-
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
Defaultprefix:NbpGoldPriceClient,NbpCurrencyExchangeRateClient,NbpExchangeRateTableClient(#6). - Clients, their interfaces and
NbpOptionsmoved to theOpenUrzednik.Nbpnamespace; models stay in.Currency,.Tableand.Gold, and.Optionsis gone.OpenUrzednik.Core.Extensionsis gone too:EnsureSuccess()andAnd()are instance methods, theTask<…>extensions are inOpenUrzednik.Core, andRecordError/RecordErrorsinOpenUrzednik.Core.Telemetry(#156). - Table B:
GetCountry*andCountryExchangeRatesare removed. The mid-rate currency methods takeTableType table = TableType.Abefore 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 propertiesBuyandSellare nowAskandBid, after the API's fields; the positional order is unchanged (#47). - Construction:
HttpClientExtensions.ConfigureForNbpApiis removed, and the clients no longer change theHttpClient; passNbpOptionsto the constructor.NbpOptions.Timeoutis optional, and when it is unset theHttpClienttimeout applies (100 s by default, was 10 s).NbpOptions.ApiUrldefaults tonull, and anhttp://BaseAddressor one with a query throwsArgumentException(#28). The URL builders, their factory andNbpTableare internal, and the full constructor has nourlBuilderFactoryparameter; for a gateway, useApiUrland aDelegatingHandler(#154, API gateways). - Public dates are
DateTimeon every target; see Upgrading (#157). - Network failures, timeouts and bad payloads are returned as errors, no longer thrown as
HttpRequestExceptionorTaskCanceledException; reading the body also counts against the timeout (#18). HTTP statuses map to specific errors: 400BadRequestErrorwith NBP's message, 401/403UnauthorizedError, 408RequestTimeoutError, 5xxServiceUnavailableError; DNS, TLS and connection failures areConnectionFailedError(#16, #161). - Error codes renamed:
validationError→validation,serializationError→serialization,unknownError→unknown(#161). Read the status code withGetHttpStatusCode()orTryGetHttpStatusCode();OpenUrzednikError.StatusCodeMetadataKeybecameHttpErrorMetadata.StatusCodeKey(still"statusCode") (#188). - Exceptions:
ValidationException→OpenUrzednikValidationExceptionandSerializationException→OpenUrzednikSerializationException(#62).EnsureSuccess()no longer throwsAggregateExceptionor a rawJsonException(#17, #29).ToException()returnsOpenUrzednikException; a custom error implementsCreateException()instead (#29). default(OpenUrzednikResult<T>)is a failure, no longer a success holdingdefault(T)(#15).- A
nullcurrency or an undefinedTableTypethrowsArgumentNullExceptionorArgumentOutOfRangeExceptionfrom the call instead of returning aValidationError(#158).EnsureSuccessAsync,MapAsyncandBindAsyncthrow for anullargument at the call, not from the returned task (#181). NbpGoldPriceClient,NbpCurrencyExchangeRateClient,NbpExchangeRateTableClientandNbpOptionsaresealed(#164).- Every assembly is strong-named (public key token
e8d5ca0d09eb5ce1), and the assembly version is1.0.0.0for every 1.x release; update binding redirects on .NET Framework (#165). - Telemetry names: span names
nbp.*.get_dateandnbp.*.get_range→nbp.*.dateandnbp.*.range(#31); tagshttp.path→url.path(now the absolute path) andhttp.status_code→http.response.status_code(#33);error.code→error.type(#163). Update dashboards and queries. - Logging: every
IOpenUrzednikLogger.Logoverload takes anOpenUrzednikEventId, 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 onOpenUrzednik.Nbpstill matches, but filters onOpenUrzednik.Nbp.Currency,.Tableor.Goldno 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…LastPublishedBeforeAsyncon 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/BindAsynconTask<…>, andOpenUrzednikException.Error/Errorswith the original errors (#29, Working with a result). - New errors:
BadRequestError,RequestTimeoutErrorandConnectionFailedError, with public metadata keys (#16, #18, #161, Errors). - Logging and tracing in the NBP clients (#5), with adapters to
ILogger(OpenUrzednik.Extensions.Logging) andActivitySource(OpenUrzednik.Diagnostics) (#33). Log event ids inNbpLogEvents, and on .NET a client without a trace source records its spans onOpenUrzednik.Nbp(#163). The HTTP span hasserver.addressandserver.port(#186). See the telemetry reference. netstandard2.0target 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
SerializationErroragainst the real API (#13). - Rates and tables A and C published before 2004-05-04 failed with a
SerializationError; theirCurrencyNameis 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-THthe URLs had a non-Gregorian year (#19). NbpGoldPriceClientmethods default theirCancellationToken(#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