Table of Contents

Class SerializationException

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

Exception thrown when serialization or deserialization operations fail.

public sealed class SerializationException : ApiException, ISerializable
Inheritance
SerializationException
Implements
Inherited Members
Extension Methods

Remarks

This exception is thrown by IPayloadSerializer and serializer implementations when they encounter errors during serialization or deserialization operations.

This exception extends ApiException to provide API-compatible error responses with RFC 7807 problem details support.

Common scenarios that may cause this exception:

  • Unknown or unregistered serializer ID in payload magic byte
  • Corrupt or invalid payload data
  • Type mismatch during deserialization
  • Missing required serializer attributes on types
  • Null values where not supported

Constructors

SerializationException()

Initializes a new instance of the SerializationException class.

public SerializationException()

SerializationException(string)

Initializes a new instance of the SerializationException class with a specified error message.

public SerializationException(string message)

Parameters

message string

The message that describes the error.

SerializationException(string, Exception)

Initializes a new instance of the SerializationException class with a specified error message and a reference to the inner exception.

public SerializationException(string message, Exception innerException)

Parameters

message string

The message that describes the error.

innerException Exception

The exception that is the cause of the current exception.

Properties

Operation

Gets or sets the operation being performed when the exception occurred.

public SerializationOperation Operation { get; init; }

Property Value

SerializationOperation

SerializerId

Gets or sets the serializer ID associated with this exception, if applicable.

public byte? SerializerId { get; init; }

Property Value

byte?

Remarks

This property is set when the exception is related to a specific serializer, such as when an unknown serializer ID is encountered in a payload.

SerializerName

Gets or sets the name of the serializer that threw the exception.

public string? SerializerName { get; init; }

Property Value

string

TargetType

Gets or sets the type that was being serialized or deserialized when the exception occurred.

public Type? TargetType { get; init; }

Property Value

Type

Methods

DeserializationFailed(Type, byte, string, Exception)

Creates a SerializationException for a deserialization failure with full context.

public static SerializationException DeserializationFailed(Type targetType, byte serializerId, string serializerName, Exception innerException)

Parameters

targetType Type

The type being deserialized.

serializerId byte

The ID of the serializer.

serializerName string

The name of the serializer.

innerException Exception

The inner exception that caused the failure.

Returns

SerializationException

A new SerializationException instance.

EmptyPayload()

Creates a SerializationException for an empty payload.

public static SerializationException EmptyPayload()

Returns

SerializationException

A new SerializationException instance.

FormatNotSupported(string, string?)

Creates a SerializationException for an unsupported payload format.

public static SerializationException FormatNotSupported(string formatName, string? suggestion = null)

Parameters

formatName string

The name of the unsupported format.

suggestion string

Suggestion for how to handle this format.

Returns

SerializationException

A new SerializationException instance.

Remarks

This is thrown when the format is recognized but not supported, such as Confluent Schema Registry with Avro/Protobuf payloads.

NullResultForType(Type)

Creates a SerializationException for a null deserialization result with runtime type.

public static SerializationException NullResultForType(Type type)

Parameters

type Type

The type that was being deserialized.

Returns

SerializationException

A new SerializationException instance.

NullResult<T>()

Creates a SerializationException for a null deserialization result.

public static SerializationException NullResult<T>()

Returns

SerializationException

A new SerializationException instance.

Type Parameters

T

The type that was being deserialized.

SerializationFailed(Type, byte, string, Exception)

Creates a SerializationException for a serialization failure with full context.

public static SerializationException SerializationFailed(Type targetType, byte serializerId, string serializerName, Exception innerException)

Parameters

targetType Type

The type being serialized.

serializerId byte

The ID of the serializer.

serializerName string

The name of the serializer.

innerException Exception

The inner exception that caused the failure.

Returns

SerializationException

A new SerializationException instance.

UnknownFormat(byte)

Creates a SerializationException for an unknown payload format.

public static SerializationException UnknownFormat(byte firstByte)

Parameters

firstByte byte

The first byte of the unknown payload.

Returns

SerializationException

A new SerializationException instance.

Remarks

This is thrown when the payload format cannot be identified through hybrid detection: not our magic bytes, not Confluent format, and not raw JSON.

UnknownSerializerId(byte, string?)

Creates a SerializationException for an unknown serializer ID.

public static SerializationException UnknownSerializerId(byte serializerId, string? registeredSerializers = null)

Parameters

serializerId byte

The unknown serializer ID.

registeredSerializers string

Description of registered serializers for the error message.

Returns

SerializationException

A new SerializationException instance.

WrapObject(Type, string, Exception)

Creates a SerializationException wrapping an inner exception for runtime type serialization.

public static SerializationException WrapObject(Type type, string operation, Exception innerException)

Parameters

type Type

The runtime type that was being serialized.

operation string

The operation being performed ("serialize" or "deserialize").

innerException Exception

The inner exception.

Returns

SerializationException

A new SerializationException instance.

Wrap<T>(string, Exception)

Creates a SerializationException wrapping an inner exception.

public static SerializationException Wrap<T>(string operation, Exception innerException)

Parameters

operation string

The operation being performed ("serialization" or "deserialization").

innerException Exception

The inner exception.

Returns

SerializationException

A new SerializationException instance.

Type Parameters

T

The type that was being serialized or deserialized.