Table of Contents

Class AotJsonEventSerializer

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.dll

AOT-compatible JSON event serializer that uses compile-time type registries instead of reflection-based type resolution.

public sealed class AotJsonEventSerializer : IEventSerializer
Inheritance
AotJsonEventSerializer
Implements
Inherited Members
Extension Methods

Remarks

This serializer is the AOT-safe alternative to JsonEventSerializer. It uses IEventTypeRegistry for type name resolution (populated from the source-generated EventStoreTypeMap) and JsonSerializerContext for type-safe JSON serialization.

Consumers opt in by referencing the Excalibur.Dispatch.SourceGenerators package, which generates the type map at compile time.

Wire-shape parity (enforced). The emitted JSON is controlled entirely by the consumer-supplied JsonSerializerContext. To stay byte-compatible with events written through the reflection-based JsonEventSerializer (camelCase property names, enums as strings, nulls omitted), the context MUST be annotated with [JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase, UseStringEnumConverter = true, DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull)], and the generated Default instance must be the one supplied — those settings are applied to MyContext.Default and not to a new MyContext(), which carries default (PascalCase, null-writing) options. The naming-policy and null-handling halves of that contract are read back off Options, and a divergent context is rejected by the constructor, so a PascalCase or null-writing context fails loudly at composition instead of silently writing payloads the reflection path mis-reads. The string-enum half is not surfaced on the options object at all, so it is checked behaviourally instead: the first enum reachable from a registered event type is serialized through the context and a numeric result is rejected on the same terms.

Event metadata. Metadata is an IDictionary<string, object>, so each metadata value is written as its runtime type. Source generation resolves nothing at run time, so every runtime value type the application places in that dictionary must itself be declared on the context — [JsonSerializable(typeof(string))], [JsonSerializable(typeof(int))], [JsonSerializable(typeof(bool))], and so on for the types actually stored. An undeclared value type raises NotSupportedException on serialize. Declare the closed value types; do not declare Dictionary<string, object> itself as a shortcut — that compiles and then throws at run time on the same values.

Constructors

AotJsonEventSerializer(JsonSerializerContext, params Type[])

Initializes a new instance of the AotJsonEventSerializer class over an explicit set of event types.

public AotJsonEventSerializer(JsonSerializerContext jsonContext, params Type[] eventTypes)

Parameters

jsonContext JsonSerializerContext

The source-generated JSON serializer context declaring every event type — and every metadata value type — the application serializes. Pass the generated Default instance.

eventTypes Type[]

The event types resolvable by name when loading stored events. These are the same types passed to AddEventTypes(...); an event type that is absent here cannot be loaded back from the store.

Remarks

This is the manual-composition entry point. Applications using dependency injection call services.AddAotEventSerializer(MyJsonContext.Default) instead, which shares the event-type allow-list already populated by AddEventTypes(...).

Exceptions

ArgumentNullException

jsonContext or eventTypes (or any element) is null.

ArgumentException

jsonContext does not carry the canonical event wire-shape settings.

Methods

DeserializeEvent(byte[], Type)

Deserializes an event from bytes.

public IDomainEvent DeserializeEvent(byte[] data, Type eventType)

Parameters

data byte[]

The serialized event data.

eventType Type

The type of event to deserialize.

Returns

IDomainEvent

The deserialized event.

GetTypeName(Type)

Gets the type name for serialization.

public string GetTypeName(Type type)

Parameters

type Type

The type to get the name for.

Returns

string

Type name for storage.

ResolveType(string)

Resolves a type from its stored name.

public Type ResolveType(string typeName)

Parameters

typeName string

The stored type name.

Returns

Type

The resolved type.

SerializeEvent(IDomainEvent)

Serializes an event to bytes.

public byte[] SerializeEvent(IDomainEvent domainEvent)

Parameters

domainEvent IDomainEvent

The event to serialize.

Returns

byte[]

Serialized event data.