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
registryISerializerRegistryThe serializer registry.
loggerILogger<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
registryISerializerRegistryThe serializer registry.
loggerILogger<PayloadSerializer>The logger instance.
jsonOptionsJsonSerializerOptionsCustom 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
databyte[]Byte array in format: [magic byte (1 byte)][serialized payload (N bytes)].
typeTypeThe 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
databyte[]The raw message payload bytes from a transport (Kafka, RabbitMQ, etc.).
Returns
- T
The deserialized object.
Type Parameters
TThe type to deserialize to.
Remarks
Hybrid Format Detection Strategy:
-
Our format (internal): Magic byte 1-254 with a registered serializer.
Uses
ISerializerRegistry.IsRegistered(byte)to confirm. - Confluent Schema Registry: Byte 0x00 followed by 4-byte schema ID. Falls back to JSON if payload starts with '{' or '['.
- Raw JSON (external): Payload starts with '{' (0x7B) or '[' (0x5B). Used for interoperability with external Kafka/RabbitMQ producers.
- 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
databyte[]Byte array in format: [magic byte (1 byte)][serialized payload (N bytes)].
Returns
- T
The deserialized object.
Type Parameters
TThe 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
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
valueTThe 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
TThe 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.