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
messagestringThe 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
messagestringThe message that describes the error.
innerExceptionExceptionThe 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
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
TargetType
Gets or sets the type that was being serialized or deserialized when the exception occurred.
public Type? TargetType { get; init; }
Property Value
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
targetTypeTypeThe type being deserialized.
serializerIdbyteThe ID of the serializer.
serializerNamestringThe name of the serializer.
innerExceptionExceptionThe 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
formatNamestringThe name of the unsupported format.
suggestionstringSuggestion 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
typeTypeThe 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
TThe 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
targetTypeTypeThe type being serialized.
serializerIdbyteThe ID of the serializer.
serializerNamestringThe name of the serializer.
innerExceptionExceptionThe 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
firstBytebyteThe 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
serializerIdbyteThe unknown serializer ID.
registeredSerializersstringDescription 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
typeTypeThe runtime type that was being serialized.
operationstringThe operation being performed ("serialize" or "deserialize").
innerExceptionExceptionThe 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
operationstringThe operation being performed ("serialization" or "deserialization").
innerExceptionExceptionThe inner exception.
Returns
- SerializationException
A new SerializationException instance.
Type Parameters
TThe type that was being serialized or deserialized.