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
configureAction<JsonSerializerOptions>Optional configuration action for JsonSerializerOptions. Applied after the default TypeInfoResolver is set, so callers can override it (e.g., set
TypeInfoResolver = nullfor reflection-based serialization).jsonContextJsonSerializerContextOptional JSON context for AOT serialization.
bufferManagerIPooledBufferServiceOptional 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
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
Returns
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
utf8JsonReadOnlySpan<byte>typeType
Returns
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
utf8JsonStreamtypeTypecancellationTokenCancellationToken
Returns
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
utf8JsonStreamcancellationTokenCancellationToken
Returns
- ValueTask<T>
Type Parameters
T
DeserializeFromUtf8(ReadOnlyMemory<byte>, Type)
Deserializes from UTF-8 memory.
public object? DeserializeFromUtf8(ReadOnlyMemory<byte> utf8Json, Type type)
Parameters
utf8JsonReadOnlyMemory<byte>typeType
Returns
DeserializeFromUtf8(ReadOnlySpan<byte>, Type)
Deserializes from UTF-8 bytes.
public object? DeserializeFromUtf8(ReadOnlySpan<byte> utf8Json, Type type)
Parameters
utf8JsonReadOnlySpan<byte>typeType
Returns
DeserializeFromUtf8<T>(ReadOnlySpan<byte>)
Deserializes a typed value from UTF-8 bytes.
public T? DeserializeFromUtf8<T>(ReadOnlySpan<byte> utf8Json)
Parameters
utf8JsonReadOnlySpan<byte>
Returns
- T
Type Parameters
T
DeserializeMessage<T>(byte[])
Deserializes a message from a byte array.
public T DeserializeMessage<T>(byte[] data)
Parameters
databyte[]
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
jsonstringThe JSON string to deserialize.
Returns
- T
The deserialized object of type
T.
Type Parameters
TThe 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
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
Returns
SerializeMessage<T>(T)
Serializes a message to a byte array.
public byte[] SerializeMessage<T>(T message)
Parameters
messageT
Returns
- byte[]
Type Parameters
T
SerializeToElement<T>(T)
Serializes an object to a JsonElement for further manipulation.
public JsonElement SerializeToElement<T>(T value)
Parameters
valueTThe object to serialize.
Returns
- JsonElement
A JsonElement representing the serialized object.
Type Parameters
TThe 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
Returns
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
valueT
Returns
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
writerIBufferWriter<byte>valueobjecttypeType
SerializeToUtf8Bytes(object?, Type)
Serializes an object to UTF-8 bytes.
public byte[] SerializeToUtf8Bytes(object? value, Type type)
Parameters
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
writerIBufferWriter<byte>valueobjecttypeType
Serialize<T>(T)
Serializes an object to a JSON string.
public string Serialize<T>(T value)
Parameters
valueTThe object to serialize.
Returns
- string
A JSON string representation of the object.
Type Parameters
TThe type of object to serialize.