OpenUrzednik.Core 1.0.0

Prefix Reserved
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package OpenUrzednik.Core --version 1.0.0
                    
NuGet\Install-Package OpenUrzednik.Core -Version 1.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OpenUrzednik.Core" Version="1.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="OpenUrzednik.Core" Version="1.0.0" />
                    
Directory.Packages.props
<PackageReference Include="OpenUrzednik.Core" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add OpenUrzednik.Core --version 1.0.0
                    
#r "nuget: OpenUrzednik.Core, 1.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package OpenUrzednik.Core@1.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=OpenUrzednik.Core&version=1.0.0
                    
Install as a Cake Addin
#tool nuget:?package=OpenUrzednik.Core&version=1.0.0
                    
Install as a Cake Tool

OpenUrzednik.Core

🇵🇱 Wersja polska (skrócona)

⚠️ Unofficial: OpenUrzednik.NET is a community project. It is not affiliated with, authorized or endorsed by Narodowy Bank Polski (NBP) or any other Polish public institution.

Shared abstractions for the whole OpenUrzednik.NET set: the Result pattern (OpenUrzednikResult / OpenUrzednikResult<T>), typed errors (OpenUrzednikError) and exceptions (OpenUrzednikException) for consumers who prefer the classic style.

Part of OpenUrzednik.NET. See the main README for an overview of the project.

Installation

dotnet add package OpenUrzednik.Core

Example

using OpenUrzednik.Core;
using OpenUrzednik.Core.Errors;

OpenUrzednikResult<int> result = OpenUrzednikResult.Success(42);
int value = result.EnsureSuccess();

A failed result:

using OpenUrzednik.Core;
using OpenUrzednik.Core.Errors;
using OpenUrzednik.Core.Exceptions;

OpenUrzednikResult<int> failed = OpenUrzednikResult.Failure<int>(new ValidationError("NIP is invalid.", ruleName: "nipChecksum", name: "nip", value: null));

try
{
    int value = failed.EnsureSuccess();
}
catch (OpenUrzednikValidationException ex)
{
    Console.WriteLine(ex.Message);
}

Trimming and Native AOT

The .NET builds (net8.0, net10.0) are trimming- and Native AOT-compatible: publishing an app with trimming or Native AOT gives no warning from this package. CI checks it on every change (ADR-0014). The netstandard2.0 build (.NET Framework) isn't covered.

Working with a result

var label = result
    .Map(v => v * 2)
    .Match(v => $"Value: {v}", errors => $"Error: {errors[0].Message}");

if (result.TryGetValue(out var current))
    Console.WriteLine(current);

Map changes the value of a successful result, Bind runs another operation that also returns a result, and Match handles both cases. If the result holds errors, they pass through unchanged and the functions you pass aren't called.

EnsureSuccess() throws an exception derived from OpenUrzednikException. Its Error property holds the error with its metadata (e.g. the HTTP status code), and Errors holds all of the result's errors. Several validation errors go into one OpenUrzednikValidationException.

Read Value only after IsSuccess or TryGetValue. On a failed result it throws an InvalidOperationException that names the errors; use EnsureSuccess() if you want the typed exception.

Every provider package (today OpenUrzednik.Nbp) depends on this package. You usually don't install it on its own, unless you are building your own client in the same style.

Errors

A client returns these errors in the result. Switch on the type, or compare Code with the ErrorCode constants:

Situation Error Code Metadata
An argument fails a format or range check ValidationError validation ruleName; name and value when known
HTTP 400 (the message includes the server's message) BadRequestError badRequest statusCode
HTTP 401, 403 UnauthorizedError unauthorized statusCode
HTTP 404 NotFoundError notFound statusCode
No data for the date or range (an empty list from the API) NotFoundError notFound none
HTTP 408 RequestTimeoutError requestTimeout statusCode
HTTP 429 RateLimitExceededError (RetryAfter) rateLimitExceeded statusCode, retryAfter
HTTP 5xx ServiceUnavailableError serviceUnavailable statusCode
A resilience handler's open circuit breaker or rate limiter (with AddOpenUrzednik… DI registration) ServiceUnavailableError serviceUnavailable none
Another HTTP status UnknownError unknown statusCode
An empty or malformed response SerializationError serialization none
No connection (DNS, TLS, refused or broken connection) ConnectionFailedError connectionFailed none
A timeout (the client's or HttpClient's deadline, a resilience handler's timeout) RequestTimeoutError (Timeout when known) requestTimeout none

The metadata keys are constants: HttpErrorMetadata.StatusCodeKey, RateLimitExceededError.RetryAfterMetadataKey, ValidationError.RuleNameMetadataKey, NameMetadataKey and ValueMetadataKey. Read the status code with error.GetHttpStatusCode() (int?) or error.TryGetHttpStatusCode(out var status): it is set only when an HTTP response caused the error. Error types describe the situation, not the transport, so the same type can come from a response or from elsewhere (an empty list is a NotFoundError without a status code).

From the first stable release, within a major version the type and Code of each case above, and the metadata keys, stay the same. New errors may appear in a minor version (e.g. a more specific error in place of UnknownError), so always handle a default case.

A client throws instead of returning an error in three cases: you cancel (OperationCanceledException), you pass an invalid argument (ArgumentNullException, ArgumentOutOfRangeException, thrown before the task is returned) or invalid options (ArgumentException from the constructor).

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

    • No dependencies.
  • net10.0

    • No dependencies.
  • net8.0

    • No dependencies.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on OpenUrzednik.Core:

Package Downloads
OpenUrzednik.Nbp

Unofficial .NET client for the NBP (Narodowy Bank Polski) API: currency exchange rates, rate tables and gold prices. Not affiliated with NBP.

OpenUrzednik.Diagnostics

Unofficial OpenUrzednik.NET adapter for System.Diagnostics: turns the clients' spans into Activities for OpenTelemetry and other listeners.

OpenUrzednik.Extensions.Logging

Unofficial OpenUrzednik.NET adapter for Microsoft.Extensions.Logging: sends the clients' structured logs to ILogger.

OpenUrzednik.Transport.Http

Unofficial OpenUrzednik.NET HTTP transport types: the errors caused by HTTP responses (HttpNotFoundError and the others, subclasses of Core's condition errors) and their status code, for the REST providers and the apps that use them.

GitHub repositories

This package is not used by any popular GitHub repositories.