Table of Contents

Interface ISerializer

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

Core serialization contract following the System.Text.Json pattern: minimal core interface with convenience overloads as extension methods in SerializerExtensions.

public interface ISerializer
Extension Methods

Remarks

This interface replaces IMessageSerializer, IBinaryMessageSerializer, IInternalSerializer, IPluggableSerializer, IJsonSerializer, IUtf8JsonSerializer, IHttpSerializer, and IZeroCopySerializer with a single unified contract.

Design:

  • 4 methods: two generic (IBufferWriter/Span), two runtime-typed (object/Type)
  • 3 properties: Name, Version, ContentType
  • Buffer type overloads (byte[], Stream, Pipe, Memory, Sequence, string) are extension methods
  • Implementations must be thread-safe and stateless
  • AOT annotations belong on implementations, not this interface

Properties

ContentType

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

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").

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").

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

DeserializeObject(ReadOnlySpan<byte>, Type)

Deserializes a runtime-typed value from bytes.

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.

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.

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.

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.