Table of Contents

Class SerializerIds

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

Well-known serializer IDs assigned by the framework for pluggable serialization.

public static class SerializerIds
Inheritance
SerializerIds
Inherited Members

Remarks

This class defines the magic byte values used to identify serializers in persisted payloads. Each payload is prefixed with a single byte identifying the serializer used, enabling:

  • Deterministic format detection without exception-based sniffing
  • Graceful migration between serializers
  • Support for multiple serializers in the same system

ID Ranges:

  • 1-199: Framework-assigned serializers (reserved by Excalibur.Dispatch)
  • 200-254: Custom consumer-defined serializers
  • 0: Invalid/uninitialized (reserved for error detection)
  • 255: Unknown/fallback (reserved for future use)

See the serialization architecture documentation for the full design rationale.

Fields

Avro

Avro - Apache Avro (schema-based, streaming/Kafka optimized).

public const byte Avro = 5

Field Value

byte

Remarks

Avro provides schema-based serialization optimized for streaming and Kafka scenarios with excellent schema evolution support via Confluent Schema Registry.

CustomRangeEnd

End of custom serializer ID range (consumer-assigned).

public const byte CustomRangeEnd = 254

Field Value

byte

CustomRangeStart

Start of custom serializer ID range (consumer-assigned).

public const byte CustomRangeStart = 200

Field Value

byte

Remarks

IDs 200-254 are available for custom consumer-defined serializers. When registering a custom serializer, use an ID in this range.

FrameworkReservedEnd

End of framework-reserved ID range.

public const byte FrameworkReservedEnd = 199

Field Value

byte

FrameworkReservedStart

Start of framework-reserved ID range.

public const byte FrameworkReservedStart = 6

Field Value

byte

Remarks

IDs 6-199 are reserved for future framework-assigned serializers. Do not use these IDs for custom serializers.

Invalid

Invalid/uninitialized serializer ID.

public const byte Invalid = 0

Field Value

byte

Remarks

This value indicates an error condition or uninitialized state. Payloads with this ID should be rejected.

MemoryPack

MemoryPack - High-performance binary serializer (opt-in).

public const byte MemoryPack = 1

Field Value

byte

Remarks

MemoryPack provides the fastest serialization for .NET-only environments. Opt-in via provider package; JSON (System.Text.Json) is the default.

MessagePack

MessagePack - Compact binary serializer (cross-language).

public const byte MessagePack = 3

Field Value

byte

Remarks

MessagePack provides good performance with cross-language compatibility. Suitable for polyglot environments with Python, Go, or other language consumers.

Protobuf

Protobuf - Protocol Buffers (schema-based, cross-language).

public const byte Protobuf = 4

Field Value

byte

Remarks

Protocol Buffers provide schema-based serialization with excellent cross-language support and backward compatibility guarantees.

SystemTextJson

System.Text.Json - Human-readable JSON serializer.

public const byte SystemTextJson = 2

Field Value

byte

Remarks

Useful for debugging and development scenarios where human-readable payloads are preferred over performance.

Unknown

Unknown serializer (fallback/error indicator).

public const byte Unknown = 255

Field Value

byte

Remarks

Reserved for future use as a fallback or error indicator. Payloads with this ID should be rejected.

Methods

IsCustomId(byte)

Validates whether a serializer ID is in the custom range.

public static bool IsCustomId(byte id)

Parameters

id byte

The serializer ID to validate.

Returns

bool

True if the ID is in the custom range (200-254), false otherwise.

IsFrameworkId(byte)

Validates whether a serializer ID is in the framework-assigned range.

public static bool IsFrameworkId(byte id)

Parameters

id byte

The serializer ID to validate.

Returns

bool

True if the ID is framework-assigned (1-199), false otherwise.

IsValidId(byte)

Validates whether a serializer ID is in the valid range for registration.

public static bool IsValidId(byte id)

Parameters

id byte

The serializer ID to validate.

Returns

bool

True if the ID is valid for registration (1-254), false otherwise.

IsValidSerializerId(byte)

Checks if a byte represents a valid magic byte for our serialization format.

public static bool IsValidSerializerId(byte firstByte)

Parameters

firstByte byte

The first byte of the payload.

Returns

bool

True if this byte represents one of our serializer IDs.

Remarks

This method is used for hybrid format detection in transport deserialization. Valid magic bytes are in the range 1-254 (our serializer IDs).

Detection Order for Transport Messages:

  1. Our magic bytes (1-254) → Use IPayloadSerializer
  2. Confluent format (0x00 + 4 bytes) → Skip header, try JSON
  3. Raw JSON (0x7B or 0x5B) → Direct JSON deserialize
  4. Unknown → Throw with diagnostic info

Note: 0x00 is reserved for Confluent Schema Registry format detection The transport layer detects this format and handles it specially for Kafka interoperability.