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
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
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
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
dataReadOnlySpan<byte>The byte span containing serialized data.
typeTypeThe runtime type to deserialize to.
Returns
- object
The deserialized object.
Exceptions
- ArgumentNullException
Thrown when
typeis 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
dataReadOnlySpan<byte>The byte span containing serialized data.
Returns
- T
The deserialized value.
Type Parameters
TThe 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
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
valueortypeis 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
valueTThe value to serialize.
bufferWriterIBufferWriter<byte>The buffer writer to write serialized data to.
Type Parameters
TThe 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
valueorbufferWriteris null.- SerializationException
Thrown when serialization fails.