Table of Contents

Class PayloadSerializer

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

Default implementation of IPayloadSerializer using magic byte format detection.

public sealed class PayloadSerializer : IPayloadSerializer
Inheritance
PayloadSerializer
Implements
Inherited Members
Extension Methods

Remarks

This class provides the primary serialization facade for internal persistence stores (Outbox, Inbox, Event Store). It handles:

  • Prepending the serializer ID as a magic byte during serialization
  • Detecting the format via magic byte during deserialization
  • Routing to the appropriate ISerializer implementation

Serialization and format-detection costs depend on the serializer, payload, runtime, and configuration. Measure complete operations with representative payloads; header handling and registry lookup do not have a guaranteed fixed latency or allocation cost.

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

Constructors

PayloadSerializer(ISerializerRegistry, ILogger<PayloadSerializer>)

Initializes a new instance of the PayloadSerializer class.

public PayloadSerializer(ISerializerRegistry registry, ILogger<PayloadSerializer> logger)

Parameters

registry ISerializerRegistry

The serializer registry.

logger ILogger<PayloadSerializer>

The logger instance.

Exceptions

ArgumentNullException

Thrown when registry or logger is null.

PayloadSerializer(ISerializerRegistry, ILogger<PayloadSerializer>, JsonSerializerOptions?)

Initializes a new instance of the PayloadSerializer class with custom JSON options for fallback deserialization.

public PayloadSerializer(ISerializerRegistry registry, ILogger<PayloadSerializer> logger, JsonSerializerOptions? jsonOptions)

Parameters

registry ISerializerRegistry

The serializer registry.

logger ILogger<PayloadSerializer>

The logger instance.

jsonOptions JsonSerializerOptions

Custom JSON serializer options for fallback deserialization of raw JSON from external systems. If null, defaults with PropertyNameCaseInsensitive and camelCase naming policy are used.

Exceptions

ArgumentNullException

Thrown when registry or logger is null.

Methods

DeserializeObject(byte[], Type)

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

public 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

DeserializeTransportMessage<T>(byte[])

Deserializes transport message data with hybrid format detection for external system interoperability.

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

Parameters

data byte[]

The raw message payload bytes from a transport (Kafka, RabbitMQ, etc.).

Returns

T

The deserialized object.

Type Parameters

T

The type to deserialize to.

Remarks

Hybrid Format Detection Strategy:

  1. Our format (internal): Magic byte 1-254 with a registered serializer. Uses ISerializerRegistry.IsRegistered(byte) to confirm.
  2. Confluent Schema Registry: Byte 0x00 followed by 4-byte schema ID. Falls back to JSON if payload starts with '{' or '['.
  3. Raw JSON (external): Payload starts with '{' (0x7B) or '[' (0x5B). Used for interoperability with external Kafka/RabbitMQ producers.
  4. Unknown format: Throws SerializationException.

Important: Raw JSON detection works because we check if a serializer is actually registered for the ID, not just if the ID is in the valid range (1-254). This allows bytes like 0x7B (123 = '{') and 0x5B (91 = '[') to fall through to JSON detection when no serializer is registered at those IDs.

Deserialize<T>(byte[])

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

public 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.

public 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.

public 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.

public 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.

public 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.