Table of Contents

Class DispatchJsonSerializer

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

JSON serializer using pooled buffers and writers to reduce repeated allocations.

public sealed class DispatchJsonSerializer : IDisposable
Inheritance
DispatchJsonSerializer
Implements
Inherited Members
Extension Methods

Remarks

This serializer is designed for high-throughput scenarios where memory allocations must be minimized. It uses the following strategies:

  • Pooled Utf8JsonWriter instances
  • Pooled byte buffers for serialization
  • Direct UTF-8 operations to avoid string allocations
  • Struct-based result handles; total allocation depends on buffering, ownership and payload.

Constructors

DispatchJsonSerializer(Action<JsonSerializerOptions>?, JsonSerializerContext?, IPooledBufferService?)

Initializes a new instance of the DispatchJsonSerializer class.

public DispatchJsonSerializer(Action<JsonSerializerOptions>? configure = null, JsonSerializerContext? jsonContext = null, IPooledBufferService? bufferManager = null)

Parameters

configure Action<JsonSerializerOptions>

Optional configuration action for JsonSerializerOptions. Applied after the default TypeInfoResolver is set, so callers can override it (e.g., set TypeInfoResolver = null for reflection-based serialization).

jsonContext JsonSerializerContext

Optional JSON context for AOT serialization.

bufferManager IPooledBufferService

Optional buffer manager for memory pooling.

Properties

SerializerName

Gets the name of the serializer.

public string SerializerName { get; }

Property Value

string

The current SerializerName value.

SerializerVersion

Gets the version of the serializer format.

public string SerializerVersion { get; }

Property Value

string

The current SerializerVersion value.

Telemetry

Gets telemetry information about serializer operations.

public SerializerTelemetry Telemetry { get; }

Property Value

SerializerTelemetry

The current Telemetry value.

Methods

Deserialize(string, Type)

Deserializes a JSON string to an object of the specified type.

public object? Deserialize(string json, Type type)

Parameters

json string

The JSON string to deserialize.

type Type

The target type for deserialization.

Returns

object

The deserialized object.

Exceptions

ArgumentException

Thrown when json is null or whitespace.

ArgumentNullException

Thrown when type is null.

SerializationException

Thrown when the payload is empty or deserialization yields a null result.

DeserializeAsync(string, Type)

Deserializes a JSON string to an object asynchronously.

public ValueTask<object?> DeserializeAsync(string json, Type type)

Parameters

json string
type Type

Returns

ValueTask<object>

DeserializeFromBytes(ReadOnlySpan<byte>, Type)

Deserializes directly from UTF-8 bytes with minimal allocations.

[MethodImpl(MethodImplOptions.AggressiveInlining)]
public object? DeserializeFromBytes(ReadOnlySpan<byte> utf8Json, Type type)

Parameters

utf8Json ReadOnlySpan<byte>
type Type

Returns

object

DeserializeFromStreamAsync(Stream, Type, CancellationToken)

Deserializes directly from a stream with minimal allocations.

[MethodImpl(MethodImplOptions.AggressiveInlining)]
public ValueTask<object?> DeserializeFromStreamAsync(Stream utf8Json, Type type, CancellationToken cancellationToken)

Parameters

utf8Json Stream
type Type
cancellationToken CancellationToken

Returns

ValueTask<object>

DeserializeFromStreamAsync<T>(Stream, CancellationToken)

Deserializes directly from a stream with minimal allocations.

[MethodImpl(MethodImplOptions.AggressiveInlining)]
public ValueTask<T?> DeserializeFromStreamAsync<T>(Stream utf8Json, CancellationToken cancellationToken)

Parameters

utf8Json Stream
cancellationToken CancellationToken

Returns

ValueTask<T>

Type Parameters

T

DeserializeFromUtf8(ReadOnlyMemory<byte>, Type)

Deserializes from UTF-8 memory.

public object? DeserializeFromUtf8(ReadOnlyMemory<byte> utf8Json, Type type)

Parameters

utf8Json ReadOnlyMemory<byte>
type Type

Returns

object

DeserializeFromUtf8(ReadOnlySpan<byte>, Type)

Deserializes from UTF-8 bytes.

public object? DeserializeFromUtf8(ReadOnlySpan<byte> utf8Json, Type type)

Parameters

utf8Json ReadOnlySpan<byte>
type Type

Returns

object

DeserializeFromUtf8<T>(ReadOnlySpan<byte>)

Deserializes a typed value from UTF-8 bytes.

public T? DeserializeFromUtf8<T>(ReadOnlySpan<byte> utf8Json)

Parameters

utf8Json ReadOnlySpan<byte>

Returns

T

Type Parameters

T

DeserializeMessage<T>(byte[])

Deserializes a message from a byte array.

public T DeserializeMessage<T>(byte[] data)

Parameters

data byte[]

Returns

T

Type Parameters

T

Deserialize<T>(string)

Deserializes a JSON string to an object of type T.

public T? Deserialize<T>(string json)

Parameters

json string

The JSON string to deserialize.

Returns

T

The deserialized object of type T.

Type Parameters

T

The type to deserialize to.

Exceptions

ArgumentException

Thrown when json is null or whitespace.

SerializationException

Thrown when the payload is empty or deserialization yields a null result.

Dispose()

Releases all resources used by the DispatchJsonSerializer.

public void Dispose()

Remarks

Call after serialization operations have completed. Only internally created writer pools are disposed; supplied pools remain owned by their caller. Concurrent calls admit one cleanup operation, but do not wait for another caller's cleanup to finish.

Serialize(object?, Type)

Serializes an object to a JSON string using the specified type.

public string Serialize(object? value, Type type)

Parameters

value object

The object to serialize.

type Type

The type to use for serialization.

Returns

string

A JSON string representation of the object.

SerializeAsync(object, Type)

Serializes an object to a JSON string asynchronously.

public ValueTask<string> SerializeAsync(object value, Type type)

Parameters

value object
type Type

Returns

ValueTask<string>

SerializeMessage<T>(T)

Serializes a message to a byte array.

public byte[] SerializeMessage<T>(T message)

Parameters

message T

Returns

byte[]

Type Parameters

T

SerializeToElement<T>(T)

Serializes an object to a JsonElement for further manipulation.

public JsonElement SerializeToElement<T>(T value)

Parameters

value T

The object to serialize.

Returns

JsonElement

A JsonElement representing the serialized object.

Type Parameters

T

The type of object to serialize.

SerializeToPooledBuffer(object?, Type)

Serializes an object directly to a pooled buffer. Pool growth and result ownership may allocate.

[MethodImpl(MethodImplOptions.AggressiveInlining)]
public PooledSerializationResult SerializeToPooledBuffer(object? value, Type type)

Parameters

value object
type Type

Returns

PooledSerializationResult

SerializeToPooledBuffer<T>(T)

Serializes an object directly to a pooled buffer. Pool growth and result ownership may allocate.

[MethodImpl(MethodImplOptions.AggressiveInlining)]
public PooledSerializationResult SerializeToPooledBuffer<T>(T value)

Parameters

value T

Returns

PooledSerializationResult

Type Parameters

T

SerializeToUtf8(IBufferWriter<byte>, object?, Type)

Serializes an object directly to a UTF-8 buffer writer.

public void SerializeToUtf8(IBufferWriter<byte> writer, object? value, Type type)

Parameters

writer IBufferWriter<byte>
value object
type Type

SerializeToUtf8Bytes(object?, Type)

Serializes an object to UTF-8 bytes.

public byte[] SerializeToUtf8Bytes(object? value, Type type)

Parameters

value object
type Type

Returns

byte[]

SerializeToWriter(IBufferWriter<byte>, object?, Type)

Serializes directly to the provided buffer writer with zero intermediate allocations.

[MethodImpl(MethodImplOptions.AggressiveInlining)]
public void SerializeToWriter(IBufferWriter<byte> writer, object? value, Type type)

Parameters

writer IBufferWriter<byte>
value object
type Type

Serialize<T>(T)

Serializes an object to a JSON string.

public string Serialize<T>(T value)

Parameters

value T

The object to serialize.

Returns

string

A JSON string representation of the object.

Type Parameters

T

The type of object to serialize.