Class SystemTextJsonSerializer
- Namespace
- Excalibur.Dispatch.Serialization
- Assembly
- Excalibur.Dispatch.dll
Consolidated System.Text.Json serializer implementing ISerializer.
public sealed class SystemTextJsonSerializer : ISerializer
- Inheritance
-
SystemTextJsonSerializer
- Implements
- Inherited Members
- Extension Methods
Remarks
Replaces SystemTextJsonPluggableSerializer and SystemTextJsonMessageSerializer. Provides human-readable JSON output, ideal for debugging and development.
Serializer ID: SystemTextJson (2)
Constructors
SystemTextJsonSerializer()
Initializes a new instance with default options (camelCase, compact).
[RequiresUnreferencedCode("JSON serialization may require types that cannot be statically analyzed.")]
[RequiresDynamicCode("JSON serialization may require runtime code generation.")]
public SystemTextJsonSerializer()
SystemTextJsonSerializer(JsonSerializerOptions?)
Initializes a new instance with custom JSON options.
[RequiresUnreferencedCode("Legacy JSON construction may use reflection. Use Create(JsonSerializerContext) for generated metadata.")]
[RequiresDynamicCode("Legacy JSON construction may require runtime code generation. Use Create(JsonSerializerContext).")]
public SystemTextJsonSerializer(JsonSerializerOptions? options)
Parameters
optionsJsonSerializerOptionsCustom JSON serializer options. If null, defaults with camelCase are used.
Remarks
Mutable options are snapshotted at construction; later caller mutations do not change this codec. The caller's options are never modified. Already-readonly options retain their metadata identity.
Properties
ContentType
Gets the IANA content type for this serializer (e.g., "application/json", "application/x-msgpack").
public string ContentType { get; }
Property Value
Remarks
Used for ASP.NET Core content negotiation via Accept and Content-Type headers.
Name
Gets the unique name of this serializer (e.g., "MemoryPack", "System.Text.Json", "MessagePack").
public string Name { get; }
Property Value
Remarks
This name is used for serializer lookup by name via ISerializerRegistry. The name should remain constant across versions for compatibility.
Version
Gets the version of the serializer library (e.g., "2.1.0").
public string Version { get; }
Property Value
Remarks
Used for diagnostics and migration scenarios. This is the version of the underlying serialization library, not a format version.
Methods
Create(JsonSerializerContext)
Creates a codec that resolves types only through the supplied JSON metadata context.
public static SystemTextJsonSerializer Create(JsonSerializerContext context)
Parameters
contextJsonSerializerContextApplication-supplied metadata, including runtime polymorphic types.
Returns
- SystemTextJsonSerializer
A System.Text.Json codec without a framework reflection fallback.
Remarks
Forwarding contexts are supported; returned metadata owns the effective options. Missing metadata fails rather than falling back to reflection. Consumers own the AOT safety of supplied contexts and converters. The context is borrowed and is not modified or disposed by this codec.
CreateWithMetadata(JsonSerializerOptions)
Creates a codec using one explicit, owned JSON policy and generated metadata composition.
public static SystemTextJsonSerializer CreateWithMetadata(JsonSerializerOptions options)
Parameters
optionsJsonSerializerOptionsThe application wire policy with an explicit metadata resolver.
Returns
- SystemTextJsonSerializer
A codec with a frozen snapshot of the supplied policy and resolver membership.
Remarks
Consumer resolvers precede generated core and CLR CloudEvents metadata fallbacks. All types use the supplied policy, including nested runtime types; context defaults are not separate policies. Resolver and converter objects are borrowed. This does not certify their NativeAOT safety or encode the standard CloudEvents wire format. Use Create(context) for context-owned metadata.
Exceptions
- ArgumentNullException
optionsis null.- ArgumentException
No explicit metadata resolver is configured.
- InvalidOperationException
Required framework metadata is incompatible with the policy.
- NotSupportedException
A resolver cannot provide required framework metadata.
DeserializeObject(ReadOnlySpan<byte>, Type)
Deserializes a runtime-typed value from bytes.
public object DeserializeObject(ReadOnlySpan<byte> data, Type type)
Parameters
dataReadOnlySpan<byte>The byte span containing serialized data.
typeTypeThe runtime type to deserialize to.
Returns
- object
The deserialized object.
Exceptions
- ArgumentNullException
Thrown when
typeis null.- SerializationException
Thrown when deserialization fails.
Deserialize<T>(ReadOnlySpan<byte>)
Deserializes a value from a contiguous byte span.
public T Deserialize<T>(ReadOnlySpan<byte> data)
Parameters
dataReadOnlySpan<byte>The byte span containing serialized data.
Returns
- T
The deserialized value.
Type Parameters
TThe type to deserialize to.
Exceptions
- SerializationException
Thrown when deserialization fails.
SerializeObject(object, Type)
Serializes a runtime-typed value to bytes.
public byte[] SerializeObject(object value, Type type)
Parameters
Returns
- byte[]
The serialized byte array.
Remarks
This overload is necessary for binary serializers (MemoryPack, MessagePack) that require concrete types when the compile-time type is an interface.
Exceptions
- ArgumentNullException
Thrown when
valueortypeis null.- SerializationException
Thrown when serialization fails.
Serialize<T>(T, IBufferWriter<byte>)
Serializes a value to a buffer writer. Allocation depends on the implementation, writer and value.
public void Serialize<T>(T value, IBufferWriter<byte> bufferWriter)
Parameters
valueTThe value to serialize.
bufferWriterIBufferWriter<byte>The buffer writer to write serialized data to.
Type Parameters
TThe type to serialize.
Remarks
Null-argument contract (canonical across all implementations): a null
value is rejected with ArgumentNullException, mirroring
SerializeObject(object, Type). This guarantees that swapping the configured
serializer (MemoryPack, MessagePack, System.Text.Json, Avro, Protobuf, …) does not change the
observable null-handling behavior. For value types T the guard is a no-op.
Exceptions
- ArgumentNullException
Thrown when
valueorbufferWriteris null.- SerializationException
Thrown when serialization fails.