Forge.Next.Formatters
3.4.0
dotnet add package Forge.Next.Formatters --version 3.4.0
NuGet\Install-Package Forge.Next.Formatters -Version 3.4.0
<PackageReference Include="Forge.Next.Formatters" Version="3.4.0" />
<PackageVersion Include="Forge.Next.Formatters" Version="3.4.0" />
<PackageReference Include="Forge.Next.Formatters" />
paket add Forge.Next.Formatters --version 3.4.0
#r "nuget: Forge.Next.Formatters, 3.4.0"
#:package Forge.Next.Formatters@3.4.0
#addin nuget:?package=Forge.Next.Formatters&version=3.4.0
#tool nuget:?package=Forge.Next.Formatters&version=3.4.0
Forge.Next.Formatters
Reference, practice and pattern implementations of data formatters for .NET: compression
(GZip, Brotli), symmetric encryption (AES) and serialization (XML, SOAP, JSON). Every formatter
shares one small, predictable, async contract and never throws for expected failures — it returns
an ErrorOr<T> result instead.
- Package version:
3.4.0 - Target frameworks:
net48(without the Brotli formatters),net8.0,net9.0,net10.0,net11.0 - License: Apache-2.0
- Package dependencies:
Forge.Next.Shared,SoapFormatter - Repository: https://github.com/JZO001/Forge.Next.Formatters
Table of contents
- Installation
- Why this library
- Core concepts
- Interfaces
- Classes and public members
ConstsGZipByteArrayFormatterGZipStreamFormatterBrotliByteArrayFormatterBrotliStreamFormatterXmlDataFormatter<T>XmlSoapFormatter<T>SoapAllowedTypesBinderSystemJsonFormatter<T>CryptoFormatterBase<T>- The AES output formats
AesByteArrayFormatterAesStreamFormatterDataFormatterExtensionsServiceCollectionExtensions
- Dependency injection
- Recipes
- Error handling reference
- Security notes
- License
Installation
Install the package from NuGet:
dotnet add package Forge.Next.Formatters
Then import the namespace (and, when you want to inspect results, the ErrorOr namespace):
using Forge.Next.Formatters;
using ErrorOr;
Why this library
Every formatter implements the same interface, IDataFormatter<T>, so once you have learned one
formatter you have learned them all. The differences are only:
| Formatter | Payload type T |
What it does |
|---|---|---|
GZipByteArrayFormatter |
byte[] |
GZip compression / decompression |
GZipStreamFormatter |
Stream |
GZip compression / decompression |
BrotliByteArrayFormatter |
byte[] |
Brotli compression / decompression (not on net48) |
BrotliStreamFormatter |
Stream |
Brotli compression / decompression (not on net48) |
XmlDataFormatter<T> |
T |
XML serialization via XmlSerializer |
XmlSoapFormatter<T> |
T |
SOAP serialization via SoapFormatter |
SystemJsonFormatter<T> |
T |
JSON serialization via System.Text.Json |
AesByteArrayFormatter |
byte[] |
AES-256 encryption / decryption |
AesStreamFormatter |
Stream |
AES-256 encryption / decryption |
All operations are asynchronous and return an ErrorOr<...> value, so failures (a null
argument, a corrupt payload, a wrong key, …) are surfaced as data instead of exceptions.
The compression and encryption formatters come in two shapes:
...ByteArrayFormatter— the payload is an in-memorybyte[]. Convenient when the whole payload comfortably fits in memory....StreamFormatter— the payload is aStream. Convenient for larger payloads and for wiring formatters together without materializing an intermediatebyte[].
On top of the per-formatter methods, the DataFormatterExtensions
helpers add file/stream ReadAsync / WriteAsync overloads that can transparently GZip-(de)compress
the payload for any formatter.
Core concepts
The IDataFormatter<T> contract
Every formatter implements IDataFormatter<T>, 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);
}
Interpretation depends on the formatter:
- For a compression formatter,
WriteAsynccompresses andReadAsyncdecompresses. - For an encryption formatter,
WriteAsyncencrypts andReadAsyncdecrypts. - For a serialization formatter,
WriteAsyncserializes andReadAsyncdeserializes.
Note: For the three serialization formatters (
XmlDataFormatter<T>,XmlSoapFormatter<T>andSystemJsonFormatter<T>) the second overload —ReadAsync(inputStream, outputStream, …)— is intentionally not implemented and always returns aForbiddenerror with the description"Method not implemented.".
The ICryptoFormatter<T> contract
The AES formatters implement ICryptoFormatter<T>, which extends IDataFormatter<T> with the
cryptographic configuration surface:
public interface ICryptoFormatter<T> : IDataFormatter<T>
{
int BufferSize { get; set; } // read/write chunk size
X509Certificate2? Certificate { get; set; } // derives IV + Key when set; obsolete since 3.4.0
byte[] IV { get; set; } // 16-byte initialization vector
byte[] Key { get; set; } // 32-byte (AES-256) key
AesOutputFormat OutputFormat { get; set; } // what WriteAsync writes (since 3.4.0; default Legacy)
bool AcceptUnauthenticated { get; set; } // whether ReadAsync accepts Legacy input (since 3.4.0; default true)
}
These members are implemented once in CryptoFormatterBase<T> and inherited
by AesByteArrayFormatter and AesStreamFormatter.
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<byte[]?> result = await formatter.ReadAsync(stream);
// 1) Imperative check
if (result.IsError)
{
Error error = result.FirstError;
Console.WriteLine($"Failed: {error.Type} - {error.Description}");
}
else
{
byte[]? value = result.Value;
// use value...
}
// 2) Functional Match (from the ErrorOr package)
string message = result.Match(
value => $"Got {value?.Length ?? 0} bytes",
errors => $"Failed: {errors[0].Description}");
The library produces three kinds of errors:
| Error type | When |
|---|---|
Validation |
An argument was null, or BufferSize <= 0. The arguments are checked before any work, and the Description is the offending parameter name, e.g. "inputStream" or "BufferSize". |
Forbidden |
The unimplemented ReadAsync(inputStream, outputStream) overload of the serialization formatters. Description is "Method not implemented.". |
Unexpected |
Any exception raised inside the operation (corrupt data, a non-readable stream, a wrong AES key, a cancellation you did not request such as an inner timeout, …) is caught and returned instead of propagating. Your own cancellation is the exception: it is thrown (see Cancellation). You get one error per exception in the inner-exception chain, each with Code "General.Unexpected", Description set to the exception's message, and Metadata with three entries: "type" (the exception's assembly-qualified type name), "message" and "stackTrace". |
Internally the "catch every exception and turn it into an errored result" behavior is provided by
the ProtectAsync wrapper from Forge.Next.Shared, which every operation runs inside (with your
token and rethrowCancellation: true since 3.4.0). You never call it directly; it is the reason a
corrupt payload becomes result.IsError == true rather than a thrown exception.
The
"stackTrace"and"message"metadata describe the library's internals. Log them, but do not pass these errors unfiltered to an end user or across a trust boundary (see Security notes).
What does throw: the methods throw OperationCanceledException when your CancellationToken
requested cancellation (since 3.4.0); constructors and property setters throw ArgumentNullException
for a null certificate, IV, key or SoapFormatter, and InvalidDataException for an IV that is not
16 bytes or a key that is not 32 bytes.
A note about streams and Position
The single-stream read overloads that return a Stream hand you back a new MemoryStream
that you own (dispose it when you are done). Where it is positioned depends on the formatter:
| Formatter | Position of the returned stream |
|---|---|
GZipStreamFormatter.ReadAsync |
0, ready to read (since 3.2.5) |
BrotliStreamFormatter.ReadAsync |
0, ready to read (since 3.4.0; before, the end) |
AesStreamFormatter.ReadAsync |
0, ready to read (since 3.4.0; before, the end) |
ErrorOr<Stream?> result = await formatter.ReadAsync(input);
using Stream output = result.Value!;
output.Position = 0; // not needed since 3.4.0; harmless, and needed for older versions
Likewise, after WriteAsync fills a MemoryStream you must rewind it (Position = 0) before you
pass it to a ReadAsync call. The formatters never close or dispose the streams you pass in, so
you can rewind and reuse them.
A note about BufferSize
The compression and encryption formatters expose an int BufferSize property
(default Consts.DefaultBufferSize = 8192 bytes) that controls the chunk size used while
streaming. When an operation reads or writes in chunks it first validates BufferSize > 0; a
non-positive value produces a Validation error whose Description is "BufferSize".
GZipByteArrayFormatter.WriteAsync writes the supplied byte[] to the GZip stream in a single
call, so it does not use BufferSize, but it still validates it (since 3.1.0): a non-positive value
gives the same Validation error there too. The serialization formatters (XML, SOAP, JSON) do not
expose BufferSize at all.
Cancellation
Every method takes a CancellationToken as its last parameter (= default). Since 3.4.0, when
your token requests cancellation, the method throws OperationCanceledException (or a subclass
such as TaskCanceledException), as .NET methods do; it is not returned as an error. A cancellation
that your token did not request, for example a stream's own timeout, is still an Unexpected error.
Before 3.4.0 every cancellation came back as an Unexpected error.
try
{
ErrorOr<byte[]?> result = await formatter.ReadAsync(input, cancellationToken);
// handle result.IsError as usual
}
catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
{
// the caller cancelled
}
How the formatters observe the token:
| Formatter | Observes the token |
|---|---|
| GZip, Brotli and AES formatters (both shapes) | On every read and write of the copy loop. |
SystemJsonFormatter<T> |
Through JsonSerializer. |
XmlDataFormatter<T>, XmlSoapFormatter<T> |
Once, before the synchronous serializer starts: a cancelled call reads or writes nothing; once started, the call completes. |
DataFormatterExtensions |
They pass the token on to the formatter and their GZip layer; the FileInfo overloads also check it before they open the file, so a cancelled write leaves an existing file untouched. |
Interfaces
Every concrete formatter is registered and injected through an interface. The full hierarchy:
| Interface | Extends | Adds | Implemented by |
|---|---|---|---|
IDataFormatter<T> |
— | ReadAsync (×2), WriteAsync |
(all formatters) |
ICryptoFormatter<T> |
IDataFormatter<T> |
BufferSize, Certificate, IV, Key, OutputFormat, AcceptUnauthenticated |
CryptoFormatterBase<T> |
IGZipByteArrayFormatter |
IDataFormatter<byte[]> |
BufferSize |
GZipByteArrayFormatter |
IGZipStreamFormatter |
IDataFormatter<Stream> |
BufferSize |
GZipStreamFormatter |
IBrotliByteArrayFormatter |
IDataFormatter<byte[]> |
BufferSize |
BrotliByteArrayFormatter |
IBrotliStreamFormatter |
IDataFormatter<Stream> |
BufferSize |
BrotliStreamFormatter |
IXmlDataFormatter<T> |
IDataFormatter<T> |
Encoding |
XmlDataFormatter<T> |
IXmlSoapFormatter<T> |
IDataFormatter<T> |
— | XmlSoapFormatter<T> |
ISystemJsonFormatter<T> |
IDataFormatter<T> |
SerializerOptions |
SystemJsonFormatter<T> |
IAesByteArrayFormatter |
ICryptoFormatter<byte[]> |
— | AesByteArrayFormatter |
IAesStreamFormatter |
ICryptoFormatter<Stream> |
— | AesStreamFormatter |
The two Brotli interfaces exist on every target, but their implementations do not exist on net48
(System.IO.Compression.Brotli is not available there), so on net48 nothing implements them.
Program against the interfaces (they are what the
AddForgeFormatters… methods register) and let the container hand
you the concrete implementation.
Classes and public members
Consts
Static class holding the constants shared by the formatters.
| Member | Value | Meaning |
|---|---|---|
Consts.DefaultBufferSize |
8192 |
Default read/write buffer size (8 KB) used by the compression/encryption formatters. |
Consts.LengthOfIV |
16 |
Required AES initialization-vector length in bytes (128 bits). |
Consts.LengthOfKey |
32 |
Required AES key length in bytes (256 bits → AES-256). |
int buffer = Consts.DefaultBufferSize; // 8192
byte[] iv = new byte[Consts.LengthOfIV]; // 16 bytes
byte[] key = new byte[Consts.LengthOfKey]; // 32 bytes
GZipByteArrayFormatter
Compresses / decompresses a byte[] using GZip. Implements
IGZipByteArrayFormatter : IDataFormatter<byte[]>.
Public members
int BufferSize { get; set; }— chunk size used while streaming (default8192).Task<ErrorOr<byte[]?>> ReadAsync(Stream inputStream, CancellationToken)— decompress the stream into a byte array.Task<ErrorOr<Success>> ReadAsync(Stream inputStream, Stream outputStream, CancellationToken)— decompress the stream intooutputStream.Task<ErrorOr<Success>> WriteAsync(byte[] data, Stream outputStream, CancellationToken)— compressdataintooutputStream.
Example — compress and decompress a byte array
using Forge.Next.Formatters;
using ErrorOr;
using System.Text;
var formatter = new GZipByteArrayFormatter
{
BufferSize = 16 * 1024 // optional: override the 8 KB default
};
byte[] original = Encoding.UTF8.GetBytes("Hello, Forge.Next.Formatters!");
// WriteAsync -> compress into a stream
using var compressed = new MemoryStream();
ErrorOr<Success> write = await formatter.WriteAsync(original, compressed);
if (write.IsError) throw new InvalidOperationException(write.FirstError.Description);
// ReadAsync -> decompress back into a byte array
compressed.Position = 0;
ErrorOr<byte[]?> read = await formatter.ReadAsync(compressed);
byte[] restored = read.Value!; // equals `original`
Example — decompress directly into another stream
compressed.Position = 0;
using var destination = new MemoryStream();
ErrorOr<Success> result = await formatter.ReadAsync(compressed, destination);
if (!result.IsError)
{
byte[] restored = destination.ToArray();
}
GZipStreamFormatter
Compresses / decompresses a Stream using GZip. Implements
IGZipStreamFormatter : IDataFormatter<Stream>.
Public members
int BufferSize { get; set; }— chunk size (default8192).Task<ErrorOr<Stream?>> ReadAsync(Stream inputStream, CancellationToken)— decompress and return a newStream, positioned at 0 (since 3.2.5; earlier versions left it at the end).Task<ErrorOr<Success>> ReadAsync(Stream inputStream, Stream outputStream, CancellationToken)— decompress intooutputStream.Task<ErrorOr<Success>> WriteAsync(Stream data, Stream outputStream, CancellationToken)— compress thedatastream intooutputStream.
Example
using Forge.Next.Formatters;
using ErrorOr;
using System.Text;
var formatter = new GZipStreamFormatter();
using var source = new MemoryStream(Encoding.UTF8.GetBytes("payload to compress"));
using var compressed = new MemoryStream();
// Compress the source stream into `compressed`
await formatter.WriteAsync(source, compressed);
// Decompress: the returned stream is already at position 0
compressed.Position = 0;
ErrorOr<Stream?> read = await formatter.ReadAsync(compressed);
using Stream decompressed = read.Value!;
using var reader = new StreamReader(decompressed);
string text = await reader.ReadToEndAsync(); // "payload to compress"
BrotliByteArrayFormatter
Compresses / decompresses a byte[] using Brotli. Implements
IBrotliByteArrayFormatter : IDataFormatter<byte[]>.
Available on
net8.0and later only;net48has no Brotli (see Interfaces).
Public members
int BufferSize { get; set; }— chunk size (default8192).Task<ErrorOr<byte[]?>> ReadAsync(Stream inputStream, CancellationToken)— decompress into a byte array.Task<ErrorOr<Success>> ReadAsync(Stream inputStream, Stream outputStream, CancellationToken)— decompress intooutputStream.Task<ErrorOr<Success>> WriteAsync(byte[] data, Stream outputStream, CancellationToken)— compressdataintooutputStream.
Example
using Forge.Next.Formatters;
using ErrorOr;
using System.Text;
var formatter = new BrotliByteArrayFormatter();
byte[] original = Encoding.UTF8.GetBytes(new string('A', 5000));
using var compressed = new MemoryStream();
await formatter.WriteAsync(original, compressed); // compress
compressed.Position = 0;
ErrorOr<byte[]?> read = await formatter.ReadAsync(compressed); // decompress
byte[] restored = read.Value!;
BrotliStreamFormatter
Compresses / decompresses a Stream using Brotli. Implements
IBrotliStreamFormatter : IDataFormatter<Stream>.
Available on
net8.0and later only;net48has no Brotli (see Interfaces).
Public members
int BufferSize { get; set; }— chunk size (default8192).Task<ErrorOr<Stream?>> ReadAsync(Stream inputStream, CancellationToken)— decompress and return a newStream, positioned at 0 (since 3.4.0; earlier versions left it at the end).Task<ErrorOr<Success>> ReadAsync(Stream inputStream, Stream outputStream, CancellationToken)— decompress intooutputStream.Task<ErrorOr<Success>> WriteAsync(Stream data, Stream outputStream, CancellationToken)— compress thedatastream intooutputStream.
Example
using Forge.Next.Formatters;
using ErrorOr;
using System.Text;
var formatter = new BrotliStreamFormatter();
using var source = new MemoryStream(Encoding.UTF8.GetBytes("payload to compress"));
using var compressed = new MemoryStream();
// Compress the source stream into `compressed`
await formatter.WriteAsync(source, compressed);
// Decompress: the returned stream is at position 0 (since 3.4.0)
compressed.Position = 0;
ErrorOr<Stream?> read = await formatter.ReadAsync(compressed);
Stream decompressed = read.Value!;
decompressed.Position = 0; // only needed before 3.4.0
using var reader = new StreamReader(decompressed);
string text = await reader.ReadToEndAsync(); // "payload to compress"
XmlDataFormatter<T>
Serializes / deserializes an object of type T to XML using System.Xml.Serialization.XmlSerializer.
Implements IXmlDataFormatter<T> : IDataFormatter<T>.
Tmust be XML-serializable: a public type with a public parameterless constructor and public read/write members.
Public members
Encoding Encoding { get; set; }— text encoding used for reading and writing (defaultEncoding.UTF8).Task<ErrorOr<T?>> ReadAsync(Stream inputStream, CancellationToken)— deserialize from XML.Task<ErrorOr<Success>> ReadAsync(Stream inputStream, Stream outputStream, CancellationToken)— not implemented; always returns aForbiddenerror.Task<ErrorOr<Success>> WriteAsync(T data, Stream outputStream, CancellationToken)— serializedatato XML.
Example
using Forge.Next.Formatters;
using ErrorOr;
using System.Text;
public class Person
{
public string Name { get; set; } = string.Empty;
public int Age { get; set; }
}
var formatter = new XmlDataFormatter<Person>
{
Encoding = Encoding.UTF8 // optional; UTF-8 is the default
};
var person = new Person { Name = "Ada", Age = 36 };
// Serialize
using var xml = new MemoryStream();
await formatter.WriteAsync(person, xml);
// Deserialize
xml.Position = 0;
ErrorOr<Person?> read = await formatter.ReadAsync(xml);
Person restored = read.Value!; // Name = "Ada", Age = 36
// The stream-to-stream read overload is not supported:
var forbidden = await formatter.ReadAsync(new MemoryStream(), new MemoryStream());
// forbidden.IsError == true, forbidden.FirstError.Type == ErrorType.Forbidden
// forbidden.FirstError.Description == "Method not implemented."
XmlSoapFormatter<T>
Serializes / deserializes an object of type T to SOAP XML using a
System.Runtime.Serialization.Formatters.Soap.SoapFormatter. Implements
IXmlSoapFormatter<T> : IDataFormatter<T>.
Tmust be marked[Serializable].
Untrusted input: use
WithAllowedTypes.SoapFormatter.Deserializecreates the types that the payload names, not onlyT, so untrusted SOAP input can make it create other types (and run their deserialization callbacks) before the cast toTfails. The formatters of the constructors below allow that, as every version did. A formatter made withXmlSoapFormatter<T>.WithAllowedTypes(since 3.4.0) refuses every type you did not list, before it is created (see Security notes).
Constructors
XmlSoapFormatter()— creates an internalSoapFormatter.XmlSoapFormatter(SoapFormatter formatter)— supply your ownSoapFormatter, for example one with your ownBinder. ThrowsArgumentNullExceptionifformatterisnull.static XmlSoapFormatter<T> WithAllowedTypes(params Type[] otherAllowedTypes)— since 3.4.0: a formatter whoseSoapFormatterhas aSoapAllowedTypesBinderthat allowsTandotherAllowedTypesonly. List the custom types ofT's fields, the element types of its arrays (not the array types), and its generic collections such asList<OrderLine>; primitive values and strings need not be listed. A payload that names any other type gives anUnexpectederror, and that type is not created. ThrowsArgumentNullExceptionfor anullarray andArgumentExceptionfor anullelement. Onnet48, however, the SoapFormatter package creates the types ofmscorlib(for exampleList<T>,ArrayList,Version) without asking the binder, so there the restriction covers only the types of other assemblies; read only trusted SOAP input onnet48.
Public members
Task<ErrorOr<T?>> ReadAsync(Stream inputStream, CancellationToken)— deserialize from SOAP. It reads the input into memory first, becauseSoapFormatter.Deserializecloses the stream it reads; soinputStreamstays open, at its end (since 3.4.0; earlier versions closed it).Task<ErrorOr<Success>> ReadAsync(Stream inputStream, Stream outputStream, CancellationToken)— not implemented; always returns aForbiddenerror.Task<ErrorOr<Success>> WriteAsync(T data, Stream outputStream, CancellationToken)— serializedatato SOAP.
Example
using Forge.Next.Formatters;
using ErrorOr;
using System.Runtime.Serialization.Formatters.Soap;
[Serializable]
public class Order
{
public string Product = string.Empty;
public int Quantity;
}
// Default constructor
var formatter = new XmlSoapFormatter<Order>();
// ...or supply your own SoapFormatter:
var custom = new XmlSoapFormatter<Order>(new SoapFormatter());
// ...or, for input that is not fully trusted, allow only the types an Order payload contains:
var restricted = XmlSoapFormatter<Order>.WithAllowedTypes(); // Order has no fields of custom types
var order = new Order { Product = "Widget", Quantity = 5 };
// Serialize to SOAP
using var soap = new MemoryStream();
await formatter.WriteAsync(order, soap);
// Deserialize
soap.Position = 0;
ErrorOr<Order?> read = await formatter.ReadAsync(soap);
Order restored = read.Value!; // Product = "Widget", Quantity = 5
SoapAllowedTypesBinder
Since 3.4.0. A SerializationBinder for the SoapFormatter that lets a payload name only the types it
was given; XmlSoapFormatter<T>.WithAllowedTypes uses it. Use it directly when you configure your own
SoapFormatter.
SoapAllowedTypesBinder(params Type[] allowedTypes)— the types a payload may name. ThrowsArgumentNullExceptionfor anullarray andArgumentExceptionfor anullelement.Type BindToType(string assemblyName, string typeName)— returns the allowed type whose full name istypeName, whatever assembly or version the payload names; any other type throws aSerializationException. A generic type's full name contains its type arguments with their assemblies, so it matches only a payload written with the same ones. Onnet48the types ofmscorlibdo not reach the binder at all (seeWithAllowedTypes).
var soap = new SoapFormatter { Binder = new SoapAllowedTypesBinder(typeof(Order)) };
var formatter = new XmlSoapFormatter<Order>(soap);
SystemJsonFormatter<T>
Serializes / deserializes an object of type T to JSON using System.Text.Json.JsonSerializer.
Implements ISystemJsonFormatter<T> : IDataFormatter<T>.
Public members
JsonSerializerOptions SerializerOptions { get; set; }— options passed toJsonSerializer(defaultJsonSerializerOptions.Default).Task<ErrorOr<T?>> ReadAsync(Stream inputStream, CancellationToken)— deserialize from JSON.Task<ErrorOr<Success>> ReadAsync(Stream inputStream, Stream outputStream, CancellationToken)— not implemented; always returns aForbiddenerror.Task<ErrorOr<Success>> WriteAsync(T data, Stream outputStream, CancellationToken)— serializedatato JSON.
Like every other formatter,
SystemJsonFormatter<T>returns aValidationerror for anullinputStream,dataoroutputStream. Before 3.4.0 itsReadAsync(inputStream)did not check the stream, and anullone came back as anUnexpectederror.
Example
using Forge.Next.Formatters;
using ErrorOr;
using System.Text.Json;
public class Person
{
public string Name { get; set; } = string.Empty;
public int Age { get; set; }
}
var formatter = new SystemJsonFormatter<Person>
{
// optional; defaults to JsonSerializerOptions.Default
SerializerOptions = new JsonSerializerOptions { WriteIndented = true }
};
var person = new Person { Name = "Ada", Age = 36 };
// Serialize to JSON
using var json = new MemoryStream();
await formatter.WriteAsync(person, json);
// Deserialize
json.Position = 0;
ErrorOr<Person?> read = await formatter.ReadAsync(json);
Person restored = read.Value!; // Name = "Ada", Age = 36
// The stream-to-stream read overload is not supported:
var forbidden = await formatter.ReadAsync(new MemoryStream(), new MemoryStream());
// forbidden.FirstError.Type == ErrorType.Forbidden, Description == "Method not implemented."
CryptoFormatterBase<T>
Abstract base class for the AES formatters. Implements ICryptoFormatter<T> : IDataFormatter<T>
and manages the initialization vector (IV), key, optional certificate and buffer size. You do not
use this class directly; you use AesByteArrayFormatter / AesStreamFormatter, which inherit
everything below.
Constructors (all protected, exposed through the derived AES formatters)
CryptoFormatterBase()— generates a random IV (16 bytes) and key (32 bytes) withRandomNumberGenerator, a cryptographic random number generator, on every target. Versions before 3.4.0 usedSystem.Random, which is predictable; onnet48two instances created at the same moment could even get the same IV and key.CryptoFormatterBase(X509Certificate2 certificate)— obsolete since 3.4.0. Derives the IV and key from the certificate's public key. ThrowsArgumentNullExceptionifcertificateisnull. Anyone who has the certificate can compute the same IV and key: see Security notes.CryptoFormatterBase(byte[] iv, byte[] key)— uses the supplied IV and key. ThrowsArgumentNullExceptionif either isnull(and the property setters below validate the length).
Public properties
int BufferSize { get; set; }— chunk size (default8192).X509Certificate2? Certificate { get; set; }— obsolete since 3.4.0 (see Security notes). When set to a non-nullcertificate, the IV is copied from the first 16 bytes of the public key's raw data (PublicKey.EncodedKeyValue.RawData) and the key from the last 32 bytes, into the current IV and key arrays (so arrays you assigned toIVorKeybefore are overwritten in place: the setters keep your array, they do not copy it). Setting it tonullis allowed and leaves the current IV/key untouched.byte[] IV { get; set; }— 16-byte initialization vector. The setter throwsArgumentNullExceptionfornullandInvalidDataExceptionwhen the length is not exactlyConsts.LengthOfIV(16).byte[] Key { get; set; }— 32-byte key. The setter throwsArgumentNullExceptionfornullandInvalidDataExceptionwhen the length is not exactlyConsts.LengthOfKey(32).AesOutputFormat OutputFormat { get; set; }— the formatWriteAsyncwrites (since 3.4.0; defaultAesOutputFormat.Legacy). The setter throwsArgumentOutOfRangeExceptionfor an undefined value. See The AES output formats.bool AcceptUnauthenticated { get; set; }— whetherReadAsyncaccepts the unauthenticatedLegacyformat (since 3.4.0; defaulttrue).
Abstract members (implemented by the concrete AES formatters)
Task<ErrorOr<T?>> ReadAsync(Stream inputStream, CancellationToken)— decrypt intoT.Task<ErrorOr<Success>> ReadAsync(Stream inputStream, Stream outputStream, CancellationToken)— decrypt intooutputStream.Task<ErrorOr<Success>> WriteAsync(T data, Stream outputStream, CancellationToken)— encryptdataintooutputStream.
Example — reading and validating the crypto configuration (via AesByteArrayFormatter)
using Forge.Next.Formatters;
var formatter = new AesByteArrayFormatter(); // random IV + key
Console.WriteLine(formatter.IV.Length); // 16
Console.WriteLine(formatter.Key.Length); // 32
Console.WriteLine(formatter.BufferSize); // 8192
// Assigning material of the wrong size is rejected:
try
{
formatter.IV = new byte[8]; // must be 16
}
catch (InvalidDataException)
{
// handled
}
The AES output formats
Since 3.4.0 the AES formatters can write two formats, chosen with OutputFormat (the enum
AesOutputFormat). Reading recognizes both by their header, whatever OutputFormat is.
| Format | What WriteAsync writes |
Protection |
|---|---|---|
AesOutputFormat.Legacy (the default) |
The bare AES-256-CBC ciphertext with PKCS7 padding, encrypted with the formatter's IV and Key: the format of every earlier version. |
Confidentiality only. A changed ciphertext is not detected, and one formatter uses one IV for every message. |
AesOutputFormat.Authenticated |
The 4-byte header FNF 0x02, a random 16-byte IV per message, the AES-256-CBC ciphertext with PKCS7 padding, and a 32-byte HMAC-SHA256 tag over all of them (encrypt-then-MAC). The encryption and the authentication key are derived from Key (HMAC-SHA256 over two fixed labels); IV is not used. |
Confidentiality and integrity: the tag is checked, in constant time, before anything is decrypted, so a changed or cut-off message gives an error and nothing reaches the output. |
AcceptUnauthenticated (default true) decides whether reading accepts the Legacy format. Set it
to false once all your data is authenticated: input without a valid tag then gives an
Unexpected error. While it is true, a message with the header but a wrong tag is also tried as
Legacy input, because a Legacy message starts with the header bytes by chance once in 2^32.
Moving to the authenticated format:
- Update every reader to 3.4.0 or later: it reads both formats.
- Set
OutputFormat = AesOutputFormat.Authenticatedon the writers. The formatters built by theAddForgeFormatters…methods start withLegacy; set it on the resolved instance, or register your own. - Once the old data has been read and written again, set
AcceptUnauthenticated = false.
var formatter = new AesByteArrayFormatter(iv, key)
{
OutputFormat = AesOutputFormat.Authenticated, // write the authenticated format
AcceptUnauthenticated = false, // and refuse anything else
};
Memory: the authenticated format is built and checked as a whole, so writing and reading keep the
whole message in memory, also with AesStreamFormatter. Reading also copies an input stream that
cannot seek into memory first, in both formats, so it can look at the header and read it again; a
seekable input is read from its current position and goes back there after the header is checked.
AesByteArrayFormatter
Encrypts / decrypts a byte[] with AES-256. Inherits everything from
CryptoFormatterBase<byte[]> and implements IAesByteArrayFormatter.
Constructors
AesByteArrayFormatter()— random IV and key.AesByteArrayFormatter(X509Certificate2 certificate)— IV/key derived from the certificate's public key; obsolete since 3.4.0 (see Deriving keys from a certificate).AesByteArrayFormatter(byte[] iv, byte[] key)— explicit 16-byte IV and 32-byte key.
Public members
Task<ErrorOr<byte[]?>> ReadAsync(Stream inputStream, CancellationToken)— decrypt into a byte array.Task<ErrorOr<Success>> ReadAsync(Stream inputStream, Stream outputStream, CancellationToken)— decrypt intooutputStream.Task<ErrorOr<Success>> WriteAsync(byte[] data, Stream outputStream, CancellationToken)— encryptdataintooutputStream.- Plus the inherited
IV,Key,Certificate,BufferSizemembers.
To decrypt data you must use the same key that was used to encrypt it, and in the default
Legacyformat the same IV too: that output is AES-256-CBC with PKCS7 padding and nothing else, no header, no IV, no authentication tag. See The AES output formats for the authenticated format, and Security notes.
Example
using Forge.Next.Formatters;
using ErrorOr;
using System.Text;
// Fixed IV (16 bytes) and key (32 bytes) so we can decrypt later. For illustration only: in real
// code use random values (see the AesStreamFormatter example) and keep the key secret.
byte[] iv = new byte[16] { 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16 };
byte[] key = new byte[32] {
1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,
17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32 };
var formatter = new AesByteArrayFormatter(iv, key);
byte[] plaintext = Encoding.UTF8.GetBytes("Top secret");
// Encrypt
using var cipher = new MemoryStream();
await formatter.WriteAsync(plaintext, cipher);
// Decrypt (same iv/key)
cipher.Position = 0;
ErrorOr<byte[]?> read = await formatter.ReadAsync(cipher);
byte[] decrypted = read.Value!; // equals `plaintext`
AesStreamFormatter
Encrypts / decrypts a Stream with AES-256. Inherits everything from
CryptoFormatterBase<Stream> and implements IAesStreamFormatter.
Constructors
AesStreamFormatter()— random IV and key.AesStreamFormatter(X509Certificate2 certificate)— IV/key derived from the certificate's public key; obsolete since 3.4.0 (see Deriving keys from a certificate).AesStreamFormatter(byte[] iv, byte[] key)— explicit 16-byte IV and 32-byte key.
Public members
Task<ErrorOr<Stream?>> ReadAsync(Stream inputStream, CancellationToken)— decrypt and return a newStream, positioned at 0 (since 3.4.0; earlier versions left it at the end).Task<ErrorOr<Success>> ReadAsync(Stream inputStream, Stream outputStream, CancellationToken)— decrypt intooutputStream.Task<ErrorOr<Success>> WriteAsync(Stream data, Stream outputStream, CancellationToken)— encrypt thedatastream intooutputStream.- Plus the inherited
IV,Key,Certificate,BufferSizemembers.
Example
using Forge.Next.Formatters;
using ErrorOr;
using System.Security.Cryptography;
using System.Text;
byte[] iv = new byte[16];
byte[] key = new byte[32];
using (var rng = RandomNumberGenerator.Create()) // cryptographic random values, on every target
{
rng.GetBytes(iv);
rng.GetBytes(key);
}
var formatter = new AesStreamFormatter(iv, key);
using var source = new MemoryStream(Encoding.UTF8.GetBytes("stream secret"));
using var cipher = new MemoryStream();
// Encrypt the source stream
await formatter.WriteAsync(source, cipher);
// Decrypt into a returned stream (at position 0 since 3.4.0)
cipher.Position = 0;
ErrorOr<Stream?> read = await formatter.ReadAsync(cipher);
Stream plain = read.Value!;
plain.Position = 0; // only needed before 3.4.0
using var reader = new StreamReader(plain);
string message = await reader.ReadToEndAsync(); // "stream secret"
DataFormatterExtensions
Static class with ReadAsync / WriteAsync extension methods on any IDataFormatter<T>
(named Read / Write before 3.2.5). They add two conveniences over the formatters' own
ReadAsync / WriteAsync methods:
- File or stream overloads — pass a
FileInfoand the file is opened for you (FileShare.Read); writing creates the file or overwrites it. - Transparent GZip — a
compress/decompressflag (which defaults totrue) wraps the payload in a GZip layer using an internalGZipStreamFormatter.
Important — which method you call on a stream: C# prefers a type's own method to an extension method, so
formatter.WriteAsync(data, stream)andformatter.ReadAsync(stream)call the formatter's own methods, without GZip, even though the extensions default totrue. To get the GZip layer on a stream, pass the flag (formatter.WriteAsync(data, stream, compress: true),formatter.ReadAsync(stream, decompress: true)) or call the extension statically (DataFormatterExtensions.WriteAsync(formatter, data, stream)). TheFileInfooverloads have no counterpart on the formatters, soformatter.WriteAsync(data, file)always reaches the extension and compresses by default. Use the same setting on both sides.
Public members
Task<ErrorOr<T?>> ReadAsync<T>(this IDataFormatter<T> formatter, FileInfo file, bool decompress = true, CancellationToken cancellationToken = default)— openfile, read/decode it (GZip-decompressing first whendecompress).Task<ErrorOr<T?>> ReadAsync<T>(this IDataFormatter<T> formatter, Stream stream, bool decompress = true, CancellationToken cancellationToken = default)— read/decodestream(GZip-decompressing first whendecompress).Task<ErrorOr<Success>> WriteAsync<T>(this IDataFormatter<T> formatter, T data, FileInfo file, bool compress = true, CancellationToken cancellationToken = default)— write/encodedatatofile(GZip-compressing whencompress).Task<ErrorOr<Success>> WriteAsync<T>(this IDataFormatter<T> formatter, T data, Stream stream, bool compress = true, CancellationToken cancellationToken = default)— write/encodedatatostream(GZip-compressing whencompress).
A null formatter, data, file or stream returns a Validation error naming the offending
argument. With the GZip layer, the whole payload passes through memory: WriteAsync serializes into
a MemoryStream before compressing it, and ReadAsync decompresses the whole input into a
MemoryStream before the formatter reads it.
The
FileInfooverloads catch every exception except your own cancellation, like the formatters do. TheStreamoverloads do not wrap the formatter call: the library's formatters throw nothing there but your own cancellation, while any exception thrown by your ownIDataFormatter<T>implementation passes through them.
Example — write and read a compressed file
using Forge.Next.Formatters;
using ErrorOr;
var formatter = new SystemJsonFormatter<Person>();
var person = new Person { Name = "Ada", Age = 36 };
var file = new FileInfo("person.json.gz");
// Serialize to JSON and GZip-compress into the file (compress: true is the default)
ErrorOr<Success> write = await formatter.WriteAsync(person, file);
// Read it back, GZip-decompressing first (decompress: true is the default)
ErrorOr<Person?> read = await formatter.ReadAsync(file);
Person restored = read.Value!; // Name = "Ada", Age = 36
Example — a stream, with and without the GZip layer
using var buffer = new MemoryStream();
// GZip on a stream: pass the flag, otherwise the formatter's own WriteAsync is called.
await formatter.WriteAsync(person, buffer, compress: true);
buffer.Position = 0;
ErrorOr<Person?> unzipped = await formatter.ReadAsync(buffer, decompress: true);
// Plain JSON, no compression: the same as the formatter's own methods.
buffer.SetLength(0);
await formatter.WriteAsync(person, buffer, compress: false);
buffer.Position = 0;
ErrorOr<Person?> plain = await formatter.ReadAsync(buffer, decompress: false);
Because the methods extend IDataFormatter<T>, they compose with every formatter in the library —
e.g. xmlFormatter.WriteAsync(model, file) for gzipped XML in a file. Compress before you encrypt
(see Compress and then encrypt): encrypted data does not compress.
ServiceCollectionExtensions
Registers the formatters with the Microsoft dependency-injection container. Three entry points are provided that differ only in the lifetime used for the non-SOAP formatters.
Public members
IServiceCollection AddForgeFormattersAsTransient(this IServiceCollection services)— registers the formatters below as transient and returns the same collection (since 3.2.2).IServiceCollection AddForgeFormattersAsScoped(this IServiceCollection services)— registers the formatters below as scoped (SOAP is transient) and returns the same collection.IServiceCollection AddForgeFormattersAsSingleton(this IServiceCollection services)— registers the formatters below as singletons (SOAP is transient) and returns the same collection.Service Implementation …AsTransient…AsScoped…AsSingletonIGZipByteArrayFormatterGZipByteArrayFormatterTransient Scoped Singleton IGZipStreamFormatterGZipStreamFormatterTransient Scoped Singleton IXmlDataFormatter<>XmlDataFormatter<>Transient Scoped Singleton IBrotliStreamFormatterBrotliStreamFormatterTransient Scoped Singleton IBrotliByteArrayFormatterBrotliByteArrayFormatterTransient Scoped Singleton IAesByteArrayFormatterAesByteArrayFormatterTransient Scoped Singleton IAesStreamFormatterAesStreamFormatterTransient Scoped Singleton ISystemJsonFormatter<>SystemJsonFormatter<>Transient Scoped Singleton IXmlSoapFormatter<>XmlSoapFormatter<>Transient Transient Transient On
net48the two Brotli rows are not registered, so each method adds seven services there, nine on the other targets. The methods useAdd…, notTryAdd…: calling one twice registers everything twice.
using Forge.Next.Formatters;
using Microsoft.Extensions.DependencyInjection;
var services = new ServiceCollection();
services.AddForgeFormattersAsScoped(); // or AddForgeFormattersAsTransient() / AddForgeFormattersAsSingleton()
using var provider = services.BuildServiceProvider();
using var scope = provider.CreateScope();
var gzip = scope.ServiceProvider.GetRequiredService<IGZipByteArrayFormatter>();
var json = scope.ServiceProvider.GetRequiredService<ISystemJsonFormatter<Person>>();
var xml = scope.ServiceProvider.GetRequiredService<IXmlDataFormatter<Person>>();
Dependency injection
The AddForgeFormatters… methods are designed for ASP.NET Core / generic-host applications.
Register once at startup and inject the interfaces where you need them. Pick
AddForgeFormattersAsSingleton when the formatters are stateless in your usage,
AddForgeFormattersAsScoped when you configure per-scope state (for example a per-request AES key),
or AddForgeFormattersAsTransient when every consumer should get its own instance.
using Forge.Next.Formatters;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddForgeFormattersAsScoped(); // or AddForgeFormattersAsTransient() / AddForgeFormattersAsSingleton()
var app = builder.Build();
public sealed class ArchiveService
{
private readonly IGZipByteArrayFormatter _gzip;
private readonly IAesByteArrayFormatter _aes;
// The formatters are injected by the container.
public ArchiveService(IGZipByteArrayFormatter gzip, IAesByteArrayFormatter aes)
{
_gzip = gzip;
_aes = aes;
}
public async Task<byte[]> PackAsync(byte[] payload, CancellationToken ct)
{
using var buffer = new MemoryStream();
var result = await _gzip.WriteAsync(payload, buffer, ct);
if (result.IsError)
throw new InvalidOperationException(result.FirstError.Description);
return buffer.ToArray();
}
}
The AES default constructors generate a random IV/key per instance, with a cryptographic random number generator (
RandomNumberGenerator). WithAddForgeFormattersAsSingletonthe same key lives for the whole application; withAddForgeFormattersAsScopeda new key is created per scope; withAddForgeFormattersAsTransientevery resolution gets a new key, so a formatter injected into one service cannot decrypt what another one encrypted. In every case, if you need a stable key across instances or processes, configureIV/Keyyourself (or register your own instance) rather than relying on the generated one.
Recipes
Compress and then encrypt
A common pipeline is to compress a payload and then encrypt the compressed bytes.
using Forge.Next.Formatters;
using ErrorOr;
using System.Security.Cryptography;
using System.Text;
byte[] iv = new byte[16];
byte[] key = new byte[32];
using (var rng = RandomNumberGenerator.Create())
{
rng.GetBytes(iv);
rng.GetBytes(key);
}
var gzip = new GZipByteArrayFormatter();
var aes = new AesByteArrayFormatter(iv, key);
byte[] payload = Encoding.UTF8.GetBytes(new string('X', 10_000));
// 1) Compress
using var compressed = new MemoryStream();
await gzip.WriteAsync(payload, compressed);
// 2) Encrypt the compressed bytes
using var encrypted = new MemoryStream();
await aes.WriteAsync(compressed.ToArray(), encrypted);
byte[] packaged = encrypted.ToArray();
// --- To restore: decrypt, then decompress ---
using var decryptInput = new MemoryStream(packaged);
ErrorOr<byte[]?> decrypted = await aes.ReadAsync(decryptInput);
using var decompressInput = new MemoryStream(decrypted.Value!);
ErrorOr<byte[]?> restored = await gzip.ReadAsync(decompressInput);
// restored.Value equals `payload`
Deriving keys from a certificate
Warning: this is not confidential encryption. The IV and key come from the certificate's public key alone, and a certificate is public by nature: anyone who has it can compute the same IV and key and decrypt the data. No private key is involved. Use this only where the data needs no protection from whoever has the certificate, for example to read data written this way earlier. For confidentiality, use a secret key of your own (see Security notes).
Since 3.4.0 the certificate constructors and the
Certificateproperty are marked[Obsolete], so using them gives the compiler warning CS0618. They still work exactly as before, so data written this way stays readable; where you call them on purpose, suppress the warning there.
When you construct an AES formatter with an X509Certificate2, its IV and key are derived
deterministically from the certificate's public key, so two formatters built from the same
certificate read each other's output:
using Forge.Next.Formatters;
using ErrorOr;
using System.Security.Cryptography.X509Certificates;
using System.Text;
X509Certificate2 certificate = LoadCertificate(); // your certificate
#pragma warning disable CS0618 // obsolete since 3.4.0: used on purpose, to read data written this way
var writer = new AesByteArrayFormatter(certificate);
var reader = new AesByteArrayFormatter(certificate); // same derived IV/key
#pragma warning restore CS0618
using var cipher = new MemoryStream();
await writer.WriteAsync(Encoding.UTF8.GetBytes("hello"), cipher);
cipher.Position = 0;
ErrorOr<byte[]?> read = await reader.ReadAsync(cipher);
// read.Value == UTF8 bytes of "hello"
Persist an object to a compressed file
The DataFormatterExtensions helpers turn "serialize + compress +
write to disk" into a single call (and the reverse for loading).
using Forge.Next.Formatters;
using ErrorOr;
var formatter = new SystemJsonFormatter<Person>(); // any IDataFormatter<T> works
var file = new FileInfo("people/ada.json.gz");
file.Directory!.Create();
var person = new Person { Name = "Ada", Age = 36 };
// Serialize to JSON, GZip-compress, and write to the file in one call (overwrites the file).
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.
using Forge.Next.Formatters;
using ErrorOr;
var formatter = new GZipByteArrayFormatter();
// null argument -> 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"
// BufferSize <= 0 (on chunked reads/writes) -> Validation error
formatter.BufferSize = 0;
ErrorOr<byte[]?> badBuffer = await formatter.ReadAsync(new MemoryStream(new byte[] { 1, 2, 3 }));
// badBuffer.FirstError.Description == "BufferSize"
// Corrupt/undecodable input -> Unexpected error (not an exception)
var aes = new AesByteArrayFormatter(); // random key
var garbage = new MemoryStream(new byte[] { 9, 9, 9 });
ErrorOr<byte[]?> corrupt = await aes.ReadAsync(garbage);
// corrupt.IsError == true
// corrupt.FirstError.Type == ErrorType.Unexpected
// corrupt.FirstError.Metadata["type"] names the exception; "message" and "stackTrace" too
// Your own cancellation -> OperationCanceledException is thrown (since 3.4.0), not returned
formatter.BufferSize = Consts.DefaultBufferSize;
try
{
await formatter.WriteAsync(new byte[] { 1 }, new MemoryStream(), new CancellationToken(canceled: true));
}
catch (OperationCanceledException)
{
// cancelled
}
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.
Security notes
- The default AES output is not authenticated. The
Legacyformat, still the default, is AES-256-CBC with PKCS7 padding, with no header and no authentication tag: a modified ciphertext decrypts to modified data, or fails on the padding, without the change being detected as such. Since 3.4.0, writeAesOutputFormat.Authenticatedand setAcceptUnauthenticated = false(see The AES output formats); as long asLegacyinput is accepted, an attacker can still hand youLegacyinput. - In the
Legacyformat one formatter uses one IV for every message. The IV is a property of the formatter, not of the message, so two messages that begin with the same bytes give ciphertexts that begin with the same bytes. TheAuthenticatedformat uses a new random IV per message. - Keys derived from a certificate are not secret. The IV and key come from the certificate's public key, so anyone who has the certificate can decrypt (see Deriving keys from a certificate); the certificate members are obsolete since 3.4.0. For an RSA 2048 certificate with the usual exponent 65537, moreover, 9 of the 16 IV bytes and 5 of the 32 key bytes are the same for every certificate (the DER header and the exponent).
- The generated keys. Since 3.4.0 the parameterless AES constructors use a cryptographic random
number generator. Earlier versions used
System.Random, which is predictable, and onnet48formatters created at the same moment got the same key; treat data encrypted with such a generated key as weakly protected. - SOAP deserialization creates the types the payload names.
XmlSoapFormatter<T>.ReadAsyncusesSoapFormatter.Deserialize, which instantiates whatever types the SOAP input names, not onlyT, and runs their deserialization callbacks before the cast toTfails. Read untrusted input with a formatter fromXmlSoapFormatter<T>.WithAllowedTypes(since 3.4.0), or pass aSoapFormatterwith aBinderof your own. Onnet48a binder never sees the types ofmscorlib, which the SOAP formatter creates on its own, so there read trusted SOAP input only. - Errors carry internals. An
Unexpectederror's metadata holds the exception's type, message and stack trace. Log it, but do not send it unfiltered to an end user or another system.
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.Shared (>= 3.3.2)
- SoapFormatter (>= 1.1.9)
-
net10.0
- Forge.Next.Shared (>= 3.3.2)
- SoapFormatter (>= 1.1.9)
-
net11.0
- Forge.Next.Shared (>= 3.3.2)
- SoapFormatter (>= 1.1.9)
-
net8.0
- Forge.Next.Shared (>= 3.3.2)
- SoapFormatter (>= 1.1.9)
-
net9.0
- Forge.Next.Shared (>= 3.3.2)
- SoapFormatter (>= 1.1.9)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Forge.Next.Formatters:
| Package | Downloads |
|---|---|
|
Sesame.Web.Clients.Gateway
Client for Sesame gateway communication |
|
|
Forge.Next.Formatters.Newtonsoft
Forge Patterns and Practices |
GitHub repositories
This package is not used by any popular GitHub repositories.