Table of Contents

Class SystemTextJsonSerializer

Namespace
Excalibur.Dispatch.Serialization
Assembly
Excalibur.Dispatch.dll

Consolidated System.Text.Json serializer implementing ISerializer.

public sealed class SystemTextJsonSerializer : ISerializer
Inheritance
SystemTextJsonSerializer
Implements
Inherited Members
Extension Methods

Remarks

Replaces SystemTextJsonPluggableSerializer and SystemTextJsonMessageSerializer. Provides human-readable JSON output, ideal for debugging and development.

Serializer ID: SystemTextJson (2)

Constructors

SystemTextJsonSerializer()

Initializes a new instance with default options (camelCase, compact).

[RequiresUnreferencedCode("JSON serialization may require types that cannot be statically analyzed.")]
[RequiresDynamicCode("JSON serialization may require runtime code generation.")]
public SystemTextJsonSerializer()

SystemTextJsonSerializer(JsonSerializerOptions?)

Initializes a new instance with custom JSON options.

[RequiresUnreferencedCode("Legacy JSON construction may use reflection. Use Create(JsonSerializerContext) for generated metadata.")]
[RequiresDynamicCode("Legacy JSON construction may require runtime code generation. Use Create(JsonSerializerContext).")]
public SystemTextJsonSerializer(JsonSerializerOptions? options)

Parameters

options JsonSerializerOptions

Custom JSON serializer options. If null, defaults with camelCase are used.

Remarks

Mutable options are snapshotted at construction; later caller mutations do not change this codec. The caller's options are never modified. Already-readonly options retain their metadata identity.

Properties

ContentType

Gets the IANA content type for this serializer (e.g., "application/json", "application/x-msgpack").

public string ContentType { get; }

Property Value

string

Remarks

Used for ASP.NET Core content negotiation via Accept and Content-Type headers.

Name

Gets the unique name of this serializer (e.g., "MemoryPack", "System.Text.Json", "MessagePack").

public string Name { get; }

Property Value

string

Remarks

This name is used for serializer lookup by name via ISerializerRegistry. The name should remain constant across versions for compatibility.

Version

Gets the version of the serializer library (e.g., "2.1.0").

public string Version { get; }

Property Value

string

Remarks

Used for diagnostics and migration scenarios. This is the version of the underlying serialization library, not a format version.

Methods

Create(JsonSerializerContext)

Creates a codec that resolves types only through the supplied JSON metadata context.

public static SystemTextJsonSerializer Create(JsonSerializerContext context)

Parameters

context JsonSerializerContext

Application-supplied metadata, including runtime polymorphic types.

Returns

SystemTextJsonSerializer

A System.Text.Json codec without a framework reflection fallback.

Remarks

Forwarding contexts are supported; returned metadata owns the effective options. Missing metadata fails rather than falling back to reflection. Consumers own the AOT safety of supplied contexts and converters. The context is borrowed and is not modified or disposed by this codec.

CreateWithMetadata(JsonSerializerOptions)

Creates a codec using one explicit, owned JSON policy and generated metadata composition.

public static SystemTextJsonSerializer CreateWithMetadata(JsonSerializerOptions options)

Parameters

options JsonSerializerOptions

The application wire policy with an explicit metadata resolver.

Returns

SystemTextJsonSerializer

A codec with a frozen snapshot of the supplied policy and resolver membership.

Remarks

Consumer resolvers precede generated core and CLR CloudEvents metadata fallbacks. All types use the supplied policy, including nested runtime types; context defaults are not separate policies. Resolver and converter objects are borrowed. This does not certify their NativeAOT safety or encode the standard CloudEvents wire format. Use Create(context) for context-owned metadata.

Exceptions

ArgumentNullException

options is null.

ArgumentException

No explicit metadata resolver is configured.

InvalidOperationException

Required framework metadata is incompatible with the policy.

NotSupportedException

A resolver cannot provide required framework metadata.

DeserializeObject(ReadOnlySpan<byte>, Type)

Deserializes a runtime-typed value from bytes.

public object DeserializeObject(ReadOnlySpan<byte> data, Type type)

Parameters

data ReadOnlySpan<byte>

The byte span containing serialized data.

type Type

The runtime type to deserialize to.

Returns

object

The deserialized object.

Exceptions

ArgumentNullException

Thrown when type is null.

SerializationException

Thrown when deserialization fails.

Deserialize<T>(ReadOnlySpan<byte>)

Deserializes a value from a contiguous byte span.

public T Deserialize<T>(ReadOnlySpan<byte> data)

Parameters

data ReadOnlySpan<byte>

The byte span containing serialized data.

Returns

T

The deserialized value.

Type Parameters

T

The type to deserialize to.

Exceptions

SerializationException

Thrown when deserialization fails.

SerializeObject(object, Type)

Serializes a runtime-typed value to bytes.

public byte[] SerializeObject(object value, Type type)

Parameters

value object

The value to serialize.

type Type

The runtime type to use for serialization.

Returns

byte[]

The serialized byte array.

Remarks

This overload is necessary for binary serializers (MemoryPack, MessagePack) that require concrete types when the compile-time type is an interface.

Exceptions

ArgumentNullException

Thrown when value or type is null.

SerializationException

Thrown when serialization fails.

Serialize<T>(T, IBufferWriter<byte>)

Serializes a value to a buffer writer. Allocation depends on the implementation, writer and value.

public void Serialize<T>(T value, IBufferWriter<byte> bufferWriter)

Parameters

value T

The value to serialize.

bufferWriter IBufferWriter<byte>

The buffer writer to write serialized data to.

Type Parameters

T

The type to serialize.

Remarks

Null-argument contract (canonical across all implementations): a null value is rejected with ArgumentNullException, mirroring SerializeObject(object, Type). This guarantees that swapping the configured serializer (MemoryPack, MessagePack, System.Text.Json, Avro, Protobuf, …) does not change the observable null-handling behavior. For value types T the guard is a no-op.

Exceptions

ArgumentNullException

Thrown when value or bufferWriter is null.

SerializationException

Thrown when serialization fails.