Table of Contents

Class CloudEventPayloadSerialization

Namespace
Excalibur.Dispatch.CloudEvents
Assembly
Excalibur.Dispatch.dll

Builds the JsonSerializerOptions CloudEvents serialization runs through, composing the framework's source-generated envelope metadata with a consumer-supplied resolver for their own payload types.

public static class CloudEventPayloadSerialization
Inheritance
CloudEventPayloadSerialization
Inherited Members

Remarks

A CloudEvent has two halves and only one of them is ours. The envelope — the event and its context attributes — is written and read without reflection either way. The payload is the consumer's own CLR type, and no metadata the framework generates can describe a type it has never seen. Serializing that payload is the single call in the whole CloudEvents path that needs a resolver, which is why this type exists and why it is small.

The two factories below are deliberately separate methods rather than one method with a nullable parameter, and the reason is the whole design:

  • CreateOptions(IJsonTypeInfoResolver) requires a resolver. There is no reflection branch inside it, so it carries no trimming annotation and a consumer calling it learns nothing alarming — because nothing alarming happens.
  • CreateReflectionOptions() is the reflection path, and it is annotated. The annotation is the point: it appears in the consumer's IntelliSense and at their own build, so the consumer who opted into reflection is the consumer who is told about it.

A single factory taking a nullable resolver would silently select one of two materially different contracts based on an argument's nullness, and would force the annotation onto both callers or neither. Trimming and dynamic-code support are also orthogonal preconditions — a trimmed but JIT-capable host has dynamic code available and the reflected-over members removed anyway — so no runtime guard can establish the trimming precondition on the caller's behalf. Splitting the surface is what lets the annotation sit exactly where the unsafe contract does.

This mirrors how the platform itself handles the same problem: the reflection-based API is annotated and a separate, unannotated source-generated path is shipped alongside it, rather than one API suppressing the difference.

Methods

CreateOptions(IJsonTypeInfoResolver)

Builds reflection-free serializer options for CloudEvents, composing the framework's source-generated envelope metadata with the consumer's own payload resolver.

public static JsonSerializerOptions CreateOptions(IJsonTypeInfoResolver payloadTypeInfoResolver)

Parameters

payloadTypeInfoResolver IJsonTypeInfoResolver

The consumer's resolver for the types they publish as CloudEvent data — typically a JsonSerializerContext they declare.

Returns

JsonSerializerOptions

Frozen options that resolve both the CloudEvents envelope and the consumer's payloads.

Exceptions

ArgumentNullException

Thrown when payloadTypeInfoResolver is null. Use CreateReflectionOptions() for the reflection-based path instead of passing null here.

CreateReflectionOptions()

Builds reflection-based serializer options for CloudEvents, for hosts that are neither trimmed nor published ahead-of-time.

[RequiresUnreferencedCode("CloudEvents payload serialization uses reflection here. Call CreateOptions with a source-generated IJsonTypeInfoResolver covering the types you publish as CloudEvent data.")]
[RequiresDynamicCode("CloudEvents payload serialization uses reflection here. Call CreateOptions with a source-generated IJsonTypeInfoResolver covering the types you publish as CloudEvent data.")]
public static JsonSerializerOptions CreateReflectionOptions()

Returns

JsonSerializerOptions

Frozen options that resolve payloads reflectively.

Remarks

Prefer CreateOptions(IJsonTypeInfoResolver) with a source-generated resolver. This method exists for the many hosts that run on a full runtime and have no reason to declare one, and its annotations are deliberate rather than an oversight: a consumer who trims or publishes ahead-of-time will see them at their own build, which is the warning they need and the one a nullable parameter on a single factory would have hidden.