Forge.Next.Formatters.Newtonsoft
3.2.0
dotnet add package Forge.Next.Formatters.Newtonsoft --version 3.2.0
NuGet\Install-Package Forge.Next.Formatters.Newtonsoft -Version 3.2.0
<PackageReference Include="Forge.Next.Formatters.Newtonsoft" Version="3.2.0" />
<PackageVersion Include="Forge.Next.Formatters.Newtonsoft" Version="3.2.0" />
<PackageReference Include="Forge.Next.Formatters.Newtonsoft" />
paket add Forge.Next.Formatters.Newtonsoft --version 3.2.0
#r "nuget: Forge.Next.Formatters.Newtonsoft, 3.2.0"
#:package Forge.Next.Formatters.Newtonsoft@3.2.0
#addin nuget:?package=Forge.Next.Formatters.Newtonsoft&version=3.2.0
#tool nuget:?package=Forge.Next.Formatters.Newtonsoft&version=3.2.0
Forge.Next.Formatters.Newtonsoft
Reference, practice and pattern implementation of a Newtonsoft.Json (Json.NET) data formatter for
.NET. It is the Json.NET counterpart of SystemJsonFormatter<T> from
Forge.Next.Formatters: it implements the very
same IDataFormatter<T> contract, serializes objects to JSON and back with
Newtonsoft.Json, and never throws for expected failures — it
returns an ErrorOr<T> result instead. The one exception it
lets through is your own cancellation: a cancelled CancellationToken throws
OperationCanceledException.
- Package version:
3.2.0 - Target frameworks:
net48,net8.0,net9.0,net10.0,net11.0 - License: Apache-2.0
- Package dependencies:
Forge.Next.Formatters3.4.0,Newtonsoft.Json13.0.4, and onnet48tonet10.0Microsoft.Extensions.DependencyInjection.Abstractions(8.0.0 onnet48andnet8.0, 9.0.0 onnet9.0, 10.0.0 onnet10.0; onnet11.0it is part of the shared framework).Forge.Next.SharedandErrorOrcome throughForge.Next.Formatters. - Repository: https://github.com/JZO001/Forge.Next.Formatters.Newtonsoft
Table of contents
- Installation
- Why this library
- Core concepts
- Interfaces
- Classes and public members
- Dependency injection
- Recipes
- Error handling reference
- License
Installation
Install the package from NuGet:
dotnet add package Forge.Next.Formatters.Newtonsoft
Then import the namespaces you need (the formatter, the Newtonsoft.Json settings types, and — when
you want to inspect results — the ErrorOr namespace):
using Forge.Next.Formatters.Newtonsoft;
using Newtonsoft.Json;
using ErrorOr;
Why this library
Forge.Next.Formatters already ships a JSON formatter (SystemJsonFormatter<T>) built on
System.Text.Json. This package adds a drop-in alternative built on Newtonsoft.Json, for the
cases where you need Json.NET specifically:
- Json.NET features —
[JsonProperty],[JsonIgnore], customJsonConverters,PreserveReferencesHandling,TypeNameHandling,DefaultValueHandling, and the large ecosystem of Json.NET-based converters and contracts. - Existing Json.NET models — types already annotated for Newtonsoft.Json serialize identically.
net48support — the formatter targetsnet48in addition tonet8.0/net9.0/net10.0/net11.0.
The formatter implements the same IDataFormatter<T> contract as every other Forge formatter, so it
composes with the helpers in Forge.Next.Formatters (for example the GZip-aware
DataFormatterExtensions.ReadAsync / WriteAsync) exactly like the built-in formatters do.
| Formatter | Payload type T |
Engine | What it does |
|---|---|---|---|
NewtonsoftJsonFormatter<T> |
T |
Newtonsoft.Json | JSON serialization / deserialization |
All operations are asynchronous and return an ErrorOr<...> value, so failures (a null argument,
malformed JSON, an unmatched type, …) are surfaced as data instead of exceptions. A cancellation you
request through the CancellationToken is thrown as OperationCanceledException, as .NET code expects.
Core concepts
The IDataFormatter<T> contract
NewtonsoftJsonFormatter<T> implements IDataFormatter<T> (from Forge.Next.Formatters), which has
exactly three methods:
public interface IDataFormatter<T>
{
// Read/decode the whole input stream and return the produced object.
Task<ErrorOr<T?>> ReadAsync(Stream inputStream, CancellationToken cancellationToken = default);
// Read/decode the input stream and write the produced bytes to the output stream.
Task<ErrorOr<Success>> ReadAsync(Stream inputStream, Stream outputStream, CancellationToken cancellationToken = default);
// Write/encode the object into the output stream.
Task<ErrorOr<Success>> WriteAsync(T data, Stream outputStream, CancellationToken cancellationToken = default);
}
For this serialization formatter:
WriteAsyncserializes the object to JSON and writes it to the output stream.ReadAsync(inputStream)deserializes the JSON from the input stream into aT.
Note: As with the other serialization formatters in the Forge family, the second overload —
ReadAsync(inputStream, outputStream, …)— is intentionally not implemented and always returns aForbiddenerror with the description"Method not implemented.".
Working with ErrorOr<T> results
None of the public methods throw for an expected failure. Instead they return an ErrorOr<T>. The
two patterns you will use most:
ErrorOr<Person?> result = await formatter.ReadAsync(stream);
// 1) Imperative check
if (result.IsError)
{
Error error = result.FirstError;
Console.WriteLine($"Failed: {error.Type} - {error.Description}");
}
else
{
Person? value = result.Value;
// use value...
}
// 2) Functional Match (from the ErrorOr package)
string message = result.Match(
value => $"Got {value?.Name}",
errors => $"Failed: {errors[0].Description}");
The formatter produces three kinds of errors:
| Error type | When |
|---|---|
Validation |
WriteAsync was called with a null data or null outputStream, or ReadAsync(inputStream) with a null inputStream (since 3.2.0). The Description is the offending parameter name — "data", "outputStream" or "inputStream". Checked before any work, so it comes even with a cancelled token. |
Forbidden |
The unimplemented ReadAsync(inputStream, outputStream) overload. Description is "Method not implemented.". |
Unexpected |
Any exception raised inside the operation (malformed JSON, a type mismatch, a stream that fails, …) is caught and returned instead of propagating: one Unexpected error per exception in the inner-exception chain, outermost first, with the code General.Unexpected, the exception's message as the Description, and the metadata type (the exception's assembly-qualified type name), message and stackTrace. |
Internally the "catch the exception and turn it into an errored result" behavior is provided by the
ProtectAsync wrapper from Forge.Next.Shared, which every operation runs inside. You never call it
directly; it is the reason malformed JSON becomes result.IsError == true rather than a thrown
JsonException.
Cancellation is not an error. When the CancellationToken you pass is cancelled, the method throws
OperationCanceledException (since 3.2.0; before, the cancellation came back as an Unexpected error).
An OperationCanceledException that does not come from your token — an inner timeout, for example — is
still returned as an Unexpected error.
Like
SystemJsonFormatter<T>(since Forge.Next.Formatters 3.4.0), the single-streamReadAsync(inputStream)checks for anullstream first and returns aValidationerror; before 3.2.0 thenullsurfaced as anUnexpectederror. ThestackTracemetadata of anUnexpectederror is the exception's stack trace: log it, but do not hand it to an untrusted party as it is.
The default JsonSerializerSettings
Every NewtonsoftJsonFormatter<T> starts with a fresh JsonSerializerSettings instance produced by
CreateDefaultSettings():
new JsonSerializerSettings
{
DateFormatHandling = DateFormatHandling.IsoDateFormat,
DefaultValueHandling = DefaultValueHandling.Populate,
Formatting = Formatting.None,
NullValueHandling = NullValueHandling.Include,
PreserveReferencesHandling = PreserveReferencesHandling.Objects
};
| Setting | Value | Effect |
|---|---|---|
DateFormatHandling |
IsoDateFormat |
Dates are written/read in ISO 8601 (2026-07-12T10:20:30Z). |
DefaultValueHandling |
Populate |
On deserialization, members absent from the JSON are set to their default value. |
Formatting |
None |
Compact output, no indentation. |
NullValueHandling |
Include |
null members are written to the JSON. |
PreserveReferencesHandling |
Objects |
Object references are tracked with $id/$ref metadata so shared/circular references round-trip. |
You can replace the whole SerializerSettings object, or start from the defaults and tweak
individual properties — see Customize the serializer settings.
PreserveReferencesHandling and the $id metadata
Because the default settings enable PreserveReferencesHandling.Objects, the serialized JSON contains
Json.NET reference-tracking metadata ("$id", and "$ref" for repeated references):
{"$id":"1","Name":"Ada","Age":36}
This is expected. It lets object graphs with shared or circular references round-trip correctly (see
Round-trip circular object references). If you are producing
JSON for a third party that does not understand $id/$ref, turn the feature off:
NewtonsoftJsonFormatter<Person> formatter = new NewtonsoftJsonFormatter<Person>
{
SerializerSettings = new JsonSerializerSettings
{
PreserveReferencesHandling = PreserveReferencesHandling.None
}
};
A note about streams and Position
WriteAsync writes to the output stream you supply and does not close it; ReadAsync likewise
reads the input stream without closing it (its internal StreamReader is created with
leaveOpen: true). When you write into a MemoryStream and then read it back with the same (or
another) formatter, rewind it first:
using MemoryStream buffer = new MemoryStream();
await formatter.WriteAsync(person, buffer);
buffer.Position = 0; // <-- rewind before reading
ErrorOr<Person?> read = await formatter.ReadAsync(buffer);
System.Text.Json vs. Newtonsoft.Json
NewtonsoftJsonFormatter<T> is API-compatible with SystemJsonFormatter<T> — both implement
IDataFormatter<T> and expose a settings/options property — but they are configured with different
types:
SystemJsonFormatter<T> |
NewtonsoftJsonFormatter<T> |
|
|---|---|---|
| Engine | System.Text.Json |
Newtonsoft.Json |
| Interface | ISystemJsonFormatter<T> |
INewtonsoftJsonFormatter<T> |
| Configuration property | JsonSerializerOptions SerializerOptions |
JsonSerializerSettings SerializerSettings |
| Default configuration | JsonSerializerOptions.Default |
CreateDefaultSettings() |
| DI (scoped) | AddForgeFormattersAsScoped() |
AddForgeNewtonsoftJsonFormatterAsScoped() |
Newtonsoft.Json has no native asynchronous (de)serialization, so in this formatter the stream I/O
is performed asynchronously while the (de)serialization itself is synchronous. The public methods
are still async and honor the CancellationToken: a cancelled token throws
OperationCanceledException. Json.NET itself does not take the token, so ReadAsync checks it before
the read and passes it to the stream read, and WriteAsync checks it before serializing and passes it to
the stream write. On net48 the stream read does not take the token (that overload exists from .NET 7),
so there only the check before the read observes it.
Interfaces
The formatter is registered and injected through its interface:
| Interface | Extends | Adds | Implemented by |
|---|---|---|---|
IDataFormatter<T> |
— | ReadAsync (×2), WriteAsync |
(all Forge formatters) |
INewtonsoftJsonFormatter<T> |
IDataFormatter<T> |
SerializerSettings |
NewtonsoftJsonFormatter<T> |
Program against INewtonsoftJsonFormatter<T> (it is what the
AddForgeNewtonsoftJsonFormatter… methods register) and let the
container hand you the concrete implementation.
Classes and public members
INewtonsoftJsonFormatter<T>
The abstraction for the Newtonsoft.Json formatter. Extends IDataFormatter<T> and adds the Json.NET
configuration surface.
public interface INewtonsoftJsonFormatter<T> : IDataFormatter<T>
{
JsonSerializerSettings SerializerSettings { get; set; }
}
Public members
JsonSerializerSettings SerializerSettings { get; set; }— the Json.NET settings used for both serialization and deserialization.- Inherited from
IDataFormatter<T>:ReadAsync(Stream, …),ReadAsync(Stream, Stream, …),WriteAsync(T, Stream, …).
Example — depend on the interface
using Forge.Next.Formatters.Newtonsoft;
using Newtonsoft.Json;
using ErrorOr;
public sealed class ProfileSerializer
{
private readonly INewtonsoftJsonFormatter<Person> _formatter;
// Injected by the DI container (see "Dependency injection").
public ProfileSerializer(INewtonsoftJsonFormatter<Person> formatter)
{
_formatter = formatter;
// The settings are configurable through the interface:
_formatter.SerializerSettings.Formatting = Formatting.Indented;
}
public async Task<byte[]> SaveAsync(Person person, CancellationToken ct)
{
using MemoryStream buffer = new MemoryStream();
ErrorOr<Success> result = await _formatter.WriteAsync(person, buffer, ct);
if (result.IsError)
throw new InvalidOperationException(result.FirstError.Description);
return buffer.ToArray();
}
}
NewtonsoftJsonFormatter<T>
Serializes / deserializes an object of type T to JSON using Newtonsoft.Json.JsonConvert.
Implements INewtonsoftJsonFormatter<T> : IDataFormatter<T>.
Tcan be any type Json.NET can serialize (public types with public read/write members, Json.NET-annotated types, collections, etc.).
Public members
JsonSerializerSettings SerializerSettings { get; set; }— the settings passed toJsonConvert(default: the value ofCreateDefaultSettings()).static JsonSerializerSettings CreateDefaultSettings()— creates a newJsonSerializerSettingsinstance carrying the documented defaults. A fresh instance is returned on every call, so callers may mutate it without affecting other formatter instances.Task<ErrorOr<T?>> ReadAsync(Stream inputStream, CancellationToken)— deserializeTfrom the JSON ininputStream, from its current position to its end. Returns aValidationerror wheninputStreamisnull; JSONnulland an empty stream give a successful result whose value isnull. ThrowsOperationCanceledExceptionwhen the token is cancelled.Task<ErrorOr<Success>> ReadAsync(Stream inputStream, Stream outputStream, CancellationToken)— not implemented; always returns aForbiddenerror ("Method not implemented.").Task<ErrorOr<Success>> WriteAsync(T data, Stream outputStream, CancellationToken)— serializedatato JSON and write it tooutputStreamas UTF-8, without a byte order mark. Returns aValidationerror whendataoroutputStreamisnull. ThrowsOperationCanceledExceptionwhen the token is cancelled; nothing is written then.
SerializerSettings
using Forge.Next.Formatters.Newtonsoft;
using Newtonsoft.Json;
NewtonsoftJsonFormatter<Person> formatter = new NewtonsoftJsonFormatter<Person>();
// Inspect the defaults...
Formatting f = formatter.SerializerSettings.Formatting; // Formatting.None
// ...or replace them wholesale.
formatter.SerializerSettings = new JsonSerializerSettings
{
Formatting = Formatting.Indented,
NullValueHandling = NullValueHandling.Ignore
};
CreateDefaultSettings()
Use this when you want the library defaults as a starting point and then adjust a few properties:
using Forge.Next.Formatters.Newtonsoft;
using Newtonsoft.Json;
JsonSerializerSettings settings = NewtonsoftJsonFormatter<Person>.CreateDefaultSettings();
settings.Formatting = Formatting.Indented; // keep the other defaults, change only formatting
NewtonsoftJsonFormatter<Person> formatter = new NewtonsoftJsonFormatter<Person> { SerializerSettings = settings };
WriteAsync / ReadAsync — full round-trip
The samples of this README use this type:
public class Person
{
public string Name { get; set; } = string.Empty;
public int Age { get; set; }
}
using Forge.Next.Formatters.Newtonsoft;
using ErrorOr;
NewtonsoftJsonFormatter<Person> formatter = new NewtonsoftJsonFormatter<Person>();
Person person = new Person { Name = "Ada", Age = 36 };
// Serialize to JSON
using MemoryStream json = new MemoryStream();
ErrorOr<Success> write = await formatter.WriteAsync(person, json);
if (write.IsError) throw new InvalidOperationException(write.FirstError.Description);
// Deserialize (rewind first!)
json.Position = 0;
ErrorOr<Person?> read = await formatter.ReadAsync(json);
Person restored = read.Value!; // Name = "Ada", Age = 36
ReadAsync(inputStream, outputStream) — not implemented
ErrorOr<Success> forbidden = await formatter.ReadAsync(new MemoryStream(), new MemoryStream());
// forbidden.IsError == true
// forbidden.FirstError.Type == ErrorType.Forbidden
// forbidden.FirstError.Description == "Method not implemented."
WriteAsync / ReadAsync — validation of null arguments
using ErrorOr;
// null data -> Validation error, Description = "data"
ErrorOr<Success> nullData = await formatter.WriteAsync(null!, new MemoryStream());
// nullData.FirstError.Type == ErrorType.Validation, Description == "data"
// null output stream -> Validation error, Description = "outputStream"
ErrorOr<Success> nullOut = await formatter.WriteAsync(new Person(), null!);
// nullOut.FirstError.Type == ErrorType.Validation, Description == "outputStream"
// null input stream -> Validation error, Description = "inputStream" (since 3.2.0)
ErrorOr<Person?> nullIn = await formatter.ReadAsync(null!);
// nullIn.FirstError.Type == ErrorType.Validation, Description == "inputStream"
ServiceCollectionExtensions
Registers the Newtonsoft.Json formatter with the Microsoft dependency-injection container. Two entry
points are provided that differ only in the registered lifetime. Both register the open generic
INewtonsoftJsonFormatter<> → NewtonsoftJsonFormatter<>, so you can resolve it for any T.
Public members
IServiceCollection AddForgeNewtonsoftJsonFormatterAsScoped(this IServiceCollection services)— registers the formatter as scoped and returns the same collection.IServiceCollection AddForgeNewtonsoftJsonFormatterAsSingleton(this IServiceCollection services)— registers the formatter as a singleton and returns the same collection.Service Implementation …AsScoped…AsSingletonINewtonsoftJsonFormatter<>NewtonsoftJsonFormatter<>Scoped Singleton
Example
using Forge.Next.Formatters.Newtonsoft;
using Microsoft.Extensions.DependencyInjection;
ServiceCollection services = new ServiceCollection();
services.AddForgeNewtonsoftJsonFormatterAsScoped(); // or AddForgeNewtonsoftJsonFormatterAsSingleton()
using ServiceProvider provider = services.BuildServiceProvider();
using IServiceScope scope = provider.CreateScope();
INewtonsoftJsonFormatter<Person> json = scope.ServiceProvider.GetRequiredService<INewtonsoftJsonFormatter<Person>>();
// json is a NewtonsoftJsonFormatter<Person>
Dependency injection
The AddForgeNewtonsoftJsonFormatter… methods are designed for ASP.NET Core / generic-host
applications. Register once at startup and inject INewtonsoftJsonFormatter<T> where you need it. Pick
…AsSingleton when the formatter's configuration is fixed for the whole application, or …AsScoped
when you configure per-scope state (for example a per-request SerializerSettings).
using Forge.Next.Formatters.Newtonsoft;
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
builder.Services.AddForgeNewtonsoftJsonFormatterAsSingleton();
// It composes with the base package too:
// builder.Services.AddForgeFormattersAsScoped();
WebApplication app = builder.Build();
using Forge.Next.Formatters.Newtonsoft;
using ErrorOr;
public sealed class DocumentStore
{
private readonly INewtonsoftJsonFormatter<Document> _json;
// The formatter is injected by the container.
public DocumentStore(INewtonsoftJsonFormatter<Document> json) => _json = json;
public async Task<byte[]> SerializeAsync(Document doc, CancellationToken ct)
{
using MemoryStream buffer = new MemoryStream();
ErrorOr<Success> result = await _json.WriteAsync(doc, buffer, ct);
if (result.IsError)
throw new InvalidOperationException(result.FirstError.Description);
return buffer.ToArray();
}
}
The formatter's default
SerializerSettingsenablePreserveReferencesHandling.Objects. If a singleton formatter is shared across the whole app and you mutate itsSerializerSettingsat runtime, that change is global. Prefer configuring the settings once at registration time, or use a scoped lifetime when you need per-scope configuration.
Recipes
Customize the serializer settings
using Forge.Next.Formatters.Newtonsoft;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;
NewtonsoftJsonFormatter<Person> formatter = new NewtonsoftJsonFormatter<Person>
{
SerializerSettings = new JsonSerializerSettings
{
Formatting = Formatting.Indented,
NullValueHandling = NullValueHandling.Ignore,
ContractResolver = new CamelCasePropertyNamesContractResolver()
}
};
using MemoryStream buffer = new MemoryStream();
await formatter.WriteAsync(new Person { Name = "Ada", Age = 36 }, buffer);
// JSON is indented and uses camelCased property names ("name", "age").
Round-trip circular object references
The default PreserveReferencesHandling.Objects lets object graphs with shared or circular references
serialize and deserialize correctly.
public class Node
{
public string Name { get; set; } = string.Empty;
public Node? Next { get; set; }
}
using Forge.Next.Formatters.Newtonsoft;
using ErrorOr;
Node a = new Node { Name = "A" };
Node b = new Node { Name = "B" };
a.Next = b;
b.Next = a; // circular reference
NewtonsoftJsonFormatter<Node> formatter = new NewtonsoftJsonFormatter<Node>(); // defaults preserve references
using MemoryStream buffer = new MemoryStream();
await formatter.WriteAsync(a, buffer); // does not loop forever
buffer.Position = 0;
ErrorOr<Node?> read = await formatter.ReadAsync(buffer);
Node restored = read.Value!;
// restored.Next!.Next is the same instance as restored (cycle rebuilt via $ref)
Use a custom JsonConverter
using Forge.Next.Formatters.Newtonsoft;
using Newtonsoft.Json;
using Newtonsoft.Json.Converters;
NewtonsoftJsonFormatter<Order> formatter = new NewtonsoftJsonFormatter<Order>();
// Serialize enums as strings, for example.
formatter.SerializerSettings.Converters.Add(new StringEnumConverter());
using MemoryStream buffer = new MemoryStream();
await formatter.WriteAsync(new Order { Status = OrderStatus.Shipped }, buffer);
// "Status":"Shipped" instead of "Status":2
Compress JSON with GZip
Because NewtonsoftJsonFormatter<T> is an IDataFormatter<T>, the GZip-aware extension methods from
Forge.Next.Formatters (DataFormatterExtensions.WriteAsync / ReadAsync) work on it directly.
On a stream, name
compress/decompressin the call.formatter.WriteAsync(person, buffer)andformatter.ReadAsync(buffer)are the formatter's own methods (plain JSON, no compression): C# picks an instance method before an extension method. TheFileInfooverloads exist only as extension methods.
using Forge.Next.Formatters; // DataFormatterExtensions
using Forge.Next.Formatters.Newtonsoft; // NewtonsoftJsonFormatter<T>
using ErrorOr;
NewtonsoftJsonFormatter<Person> formatter = new NewtonsoftJsonFormatter<Person>();
Person person = new Person { Name = "Ada", Age = 36 };
// Serialize to JSON AND GZip-compress into a stream.
using MemoryStream buffer = new MemoryStream();
await formatter.WriteAsync(person, buffer, compress: true); // extension method from the base package
// Read back: GZip-decompress AND deserialize.
buffer.Position = 0;
ErrorOr<Person?> read = await formatter.ReadAsync(buffer, decompress: true);
Person restored = read.Value!;
Persist an object to a compressed file
using Forge.Next.Formatters; // DataFormatterExtensions
using Forge.Next.Formatters.Newtonsoft;
using ErrorOr;
NewtonsoftJsonFormatter<Person> formatter = new NewtonsoftJsonFormatter<Person>();
FileInfo file = new FileInfo("people/ada.json.gz");
file.Directory!.Create();
Person person = new Person { Name = "Ada", Age = 36 };
// Serialize to JSON, GZip-compress, and write to the file in one call.
ErrorOr<Success> saved = await formatter.WriteAsync(person, file); // compress: true (default)
// Load: decompress and deserialize in one call.
ErrorOr<Person?> loaded = await formatter.ReadAsync(file); // decompress: true (default)
Person restored = loaded.Value!;
Error handling reference
Every method returns an ErrorOr<...>; inspect it instead of catching exceptions. The one exception to
expect is your own cancellation, an OperationCanceledException.
using Forge.Next.Formatters.Newtonsoft;
using ErrorOr;
NewtonsoftJsonFormatter<Person> formatter = new NewtonsoftJsonFormatter<Person>();
// null data -> Validation error, Description = parameter name
ErrorOr<Success> nullData = await formatter.WriteAsync(null!, new MemoryStream());
// nullData.IsError == true
// nullData.FirstError.Type == ErrorType.Validation
// nullData.FirstError.Description == "data"
// Unimplemented stream-to-stream read -> Forbidden
ErrorOr<Success> forbidden = await formatter.ReadAsync(new MemoryStream(), new MemoryStream());
// forbidden.FirstError.Type == ErrorType.Forbidden
// forbidden.FirstError.Description == "Method not implemented."
// Malformed JSON -> Unexpected error (not an exception)
using MemoryStream garbage = new MemoryStream(System.Text.Encoding.UTF8.GetBytes("this is not json"));
ErrorOr<Person?> corrupt = await formatter.ReadAsync(garbage);
// corrupt.IsError == true
// corrupt.FirstError.Type == ErrorType.Unexpected
// corrupt.FirstError.Metadata!["type"] names the exception (Newtonsoft.Json.JsonReaderException, …)
// Your own cancellation -> OperationCanceledException (not an error)
using CancellationTokenSource cts = new CancellationTokenSource();
cts.Cancel();
try
{
await formatter.ReadAsync(new MemoryStream(), cts.Token);
}
catch (OperationCanceledException)
{
// the read was cancelled by the caller
}
Handy ErrorOr<T> members:
IsError—truewhen the operation failed.Value— the successful result (only valid whenIsErrorisfalse).FirstError— the firstError; use.Type,.Code,.Description.Errors— the full list ofErrorvalues.Match(...)/MatchFirst(...)/Switch(...)— functional handling.
License
Copyright © Zoltan Juhasz. Licensed under the Apache License 2.0.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | 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 is compatible. 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. net11.0 is compatible. |
| .NET Framework | net48 is compatible. net481 was computed. |
-
.NETFramework 4.8
- Forge.Next.Formatters (>= 3.4.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
- Newtonsoft.Json (>= 13.0.4)
-
net10.0
- Forge.Next.Formatters (>= 3.4.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.0)
- Newtonsoft.Json (>= 13.0.4)
-
net11.0
- Forge.Next.Formatters (>= 3.4.0)
- Newtonsoft.Json (>= 13.0.4)
-
net8.0
- Forge.Next.Formatters (>= 3.4.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
- Newtonsoft.Json (>= 13.0.4)
-
net9.0
- Forge.Next.Formatters (>= 3.4.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 9.0.0)
- Newtonsoft.Json (>= 13.0.4)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.