Table of Contents

Interface IPayloadSerializer

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

High-level abstraction for serializing and deserializing payloads with automatic format detection.

public interface IPayloadSerializer
Extension Methods

Remarks

This is the primary interface used by Outbox, Inbox, and Event Store for payload serialization. It provides a facade over ISerializerRegistry and handles:

  • Magic byte prepending during serialization
  • Automatic format detection during deserialization
  • Routing to the correct ISerializer implementation

Payload Format:

[Byte 0: Serializer ID] [Bytes 1..N: Serialized Payload]

Serialization and format-detection costs depend on the implementation, serializer, payload, runtime, and configuration. This interface does not guarantee a fixed latency or allocation cost. Measure the complete serialization or deserialization operation with representative payloads.

Usage:

// Serialization (prepends magic byte automatically)
byte[] payload = payloadSerializer.Serialize(myEvent);
// payload[0] contains the serializer ID

// Deserialization (detects format from magic byte) var myEvent = payloadSerializer.Deserialize<MyEvent>(payload);

See the pluggable serialization architecture documentation for the magic byte format.

Methods

DeserializeObject(byte[], Type)

Deserializes a byte array to an object of the specified runtime type, automatically detecting the format.

object DeserializeObject(byte[] data, Type type)

Parameters

data byte[]

Byte array in format: [magic byte (1 byte)][serialized payload (N bytes)].

type Type

The runtime type to deserialize to.

Returns

object

The deserialized object.

Remarks

The runtime-typed counterpart of SerializeObject(object, Type), and the read side of the persistence contract: a stored payload names its own serializer in the magic byte, so a store that resolves its message type at runtime can read an entry back through the serializer that wrote it rather than through whichever serializer happens to be configured when the entry is drained.

Exceptions

ArgumentNullException

Thrown when data or type is null.

SerializationException

Thrown when:

  • The payload is empty
  • The magic byte identifies an unknown/unregistered serializer
  • Deserialization fails

Deserialize<T>(byte[])

Deserializes a byte array to an object, automatically detecting the format.

T Deserialize<T>(byte[] data)

Parameters

data byte[]

Byte array in format: [magic byte (1 byte)][serialized payload (N bytes)].

Returns

T

The deserialized object.

Type Parameters

T

The type to deserialize to.

Remarks

The method reads the magic byte (first byte) to determine which serializer to use:

  • Fast path: If magic byte matches current serializer ID, uses current serializer directly
  • Migration path: If magic byte differs, looks up serializer in registry by ID

This design enables seamless migration between serializers - old data remains readable as long as the original serializer is still registered.

Exceptions

ArgumentNullException

Thrown when data is null.

SerializationException

Thrown when:

  • The payload is empty
  • The magic byte identifies an unknown/unregistered serializer
  • Deserialization fails

GetCurrentSerializerId()

Gets the serializer ID that would be used for the next serialization operation.

byte GetCurrentSerializerId()

Returns

byte

The ID of the current serializer.

Remarks

Useful for diagnostics and testing to verify which serializer is active.

Exceptions

InvalidOperationException

Thrown when no current serializer is configured.

GetCurrentSerializerName()

Gets the name of the serializer that would be used for the next serialization operation.

string GetCurrentSerializerName()

Returns

string

The name of the current serializer.

Remarks

Useful for diagnostics and logging.

Exceptions

InvalidOperationException

Thrown when no current serializer is configured.

SerializeObject(object, Type)

Serializes an object to a byte array with magic byte header, using the specified runtime type.

byte[] SerializeObject(object value, Type type)

Parameters

value object

The value to serialize.

type Type

The runtime type to use for serialization.

Returns

byte[]

Byte array in format: [magic byte (1 byte)][serialized payload (N bytes)]. The magic byte identifies the serializer used.

Remarks

This overload is useful when the compile-time type differs from the runtime type, such as when serializing interface references (e.g., IDispatchMessage) that hold concrete types at runtime. Binary serializers like MemoryPack and MessagePack require concrete types for proper serialization.

Exceptions

ArgumentNullException

Thrown when value or type is null.

SerializationException

Thrown when serialization fails.

InvalidOperationException

Thrown when no current serializer is configured in the registry.

Serialize<T>(T)

Serializes an object to a byte array with magic byte header.

byte[] Serialize<T>(T value)

Parameters

value T

The value to serialize.

Returns

byte[]

Byte array in format: [magic byte (1 byte)][serialized payload (N bytes)]. The magic byte identifies the serializer used.

Type Parameters

T

The type to serialize.

Remarks

Uses the current serializer from GetCurrent() and prepends its ID as the first byte of the result.

The resulting byte array is suitable for direct storage in databases (e.g., VARBINARY columns).

Exceptions

ArgumentNullException

Thrown when value is null.

SerializationException

Thrown when serialization fails.

InvalidOperationException

Thrown when no current serializer is configured in the registry.