Table of Contents

Class EventSerializationDefaults

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

Provides the single canonical JsonSerializerOptions contract used to serialize and deserialize event payloads across every event store and the default event serializer.

public static class EventSerializationDefaults
Inheritance
EventSerializationDefaults
Inherited Members

Remarks

Event stores historically declared their own inline options that diverged from the read path: some omitted the string-enum converter (writing an enum as a number) or the null-ignore condition, so an event written by a store could mis-read when loaded through the serializer. Sourcing one options instance here keeps write and read byte-for-byte compatible on enum and nullable-property handling.

Properties

Canonical

Gets the single frozen (read-only) canonical JsonSerializerOptions instance shared by every event store and the default event serializer.

public static JsonSerializerOptions Canonical { get; }

Property Value

JsonSerializerOptions

The frozen canonical serializer options for event payloads and metadata.

Remarks

This instance is IsReadOnly and therefore safe to share without defensive copying; it must not be mutated. Callers that need a mutable copy call CreateCanonicalOptions(). Prefer reading it through the JsonSerializerOptions.Events extension accessor at adoption sites.

Methods

CreateCanonicalOptions()

Creates a new JsonSerializerOptions configured with the canonical event contract: camelCase property names, enums written as strings, and null values omitted.

[UnconditionalSuppressMessage("AOT", "IL3050:RequiresDynamicCode", Justification = "The non-generic string-enum converter is the reflection-based event serialization path; the AOT opt-in is enforced where the reflection serializer is constructed.")]
public static JsonSerializerOptions CreateCanonicalOptions()

Returns

JsonSerializerOptions

The canonical serializer options for event payloads and metadata.

Remarks

A fresh instance is returned per call because JsonSerializerOptions becomes read-only once used; callers that need to cache it should hold the returned instance for their own lifetime.

SerializeMetadataWithResolver(IDictionary<string, object>, JsonSerializerOptions)

Writes event metadata a property at a time, resolving each value against its own runtime type through the resolver carried by the supplied options.

public static byte[] SerializeMetadataWithResolver(IDictionary<string, object> metadata, JsonSerializerOptions jsonOptions)

Parameters

metadata IDictionary<string, object>

The event metadata to write.

jsonOptions JsonSerializerOptions

The canonical serializer options carrying the host's resolver.

Returns

byte[]

The UTF-8 encoded metadata object.

Remarks

Metadata is an IDictionary<string, object>, and the reflection serializer writes each value as its runtime type. Source generation resolves nothing at run time, so the dictionary cannot simply be handed to the resolver: the honest form of "each value as its runtime type" is to write the object here and look up JsonTypeInfo per value. Declaring Dictionary<string, object> on a context instead would compile and then throw on the very values it appeared to cover.

With canonical value metadata the output matches the reflection path. A forwarding resolver may return metadata bound to a child context: that metadata owns each value's nested representation. Keys are written verbatim, the outer writer inherits the encoder and indentation from the supplied options, and a null value is written as an explicit null -- WhenWritingNull governs object properties, not dictionary entries, so the reflection path emits it too.

Call this only when TryApplyTypeInfoResolver(JsonSerializerOptions, IJsonTypeInfoResolver?) reported that a resolver was attached; with no resolver the reflection path (JsonSerializer.SerializeToUtf8Bytes(metadata, jsonOptions)) is the equivalent and cheaper form.

TryApplyTypeInfoResolver(JsonSerializerOptions, IJsonTypeInfoResolver?)

Attaches a host-supplied source-generated type-info resolver to canonical event serializer options and freezes them.

public static bool TryApplyTypeInfoResolver(JsonSerializerOptions jsonOptions, IJsonTypeInfoResolver? resolver)

Parameters

jsonOptions JsonSerializerOptions

The canonical serializer options to attach the resolver to.

resolver IJsonTypeInfoResolver

The host's resolver, or null to keep the reflection path.

Returns

bool

true when a resolver was attached.

Remarks

The resolver supplies type METADATA only. It is attached to the canonical options rather than replacing them, so the naming policy, string-enum representation and null handling that fix the stored wire format stay canonical and apply to whichever resolver is in use -- events written with a resolver are byte-identical to events written without one.

Supplying no resolver is only viable where reflection-based serialization is available. Where it is not -- a Native AOT publish, or any host that has disabled the System.Text.Json.JsonSerializer.IsReflectionEnabledByDefault feature switch -- an absent resolver is rejected here, at store construction, rather than surfacing as a failure on the first event a running application tries to write.

Exceptions

InvalidOperationException

resolver is null and reflection-based serialization is unavailable, so the reflection path this would fall back to cannot run.