Table of Contents

Class UpcastingBuilder

Namespace
Excalibur.Dispatch.Versioning
Assembly
Excalibur.Dispatch.dll

Fluent builder for configuring message upcasting services.

public sealed class UpcastingBuilder
Inheritance
UpcastingBuilder
Inherited Members
Extension Methods

Remarks

This builder collects upcaster registration actions during configuration. The actions are executed when the IUpcastingPipeline singleton is created, avoiding the anti-pattern of calling BuildServiceProvider() during configuration.

Usage:

services.AddMessageUpcasting(builder =>
{
    builder.RegisterUpcaster<UserEventV1, UserEventV2>(new UserEventV1ToV2());
    builder.ScanAssembly(typeof(Program).Assembly);
});

Methods

EnableAutoUpcastOnReplay(bool)

Enables or disables automatic upcasting during event store replay.

public UpcastingBuilder EnableAutoUpcastOnReplay(bool enable = true)

Parameters

enable bool

True to enable, false to disable.

Returns

UpcastingBuilder

The builder for method chaining.

Remarks

When enabled, events loaded from the event store will be automatically upcasted to their latest version before being applied to aggregates.

RegisterUpcaster<TOld, TNew>(IMessageUpcaster<TOld, TNew>)

Registers an upcaster instance for a specific version transition.

public UpcastingBuilder RegisterUpcaster<TOld, TNew>(IMessageUpcaster<TOld, TNew> upcaster) where TOld : IDispatchMessage, IVersionedMessage where TNew : IDispatchMessage, IVersionedMessage

Parameters

upcaster IMessageUpcaster<TOld, TNew>

The upcaster instance.

Returns

UpcastingBuilder

The builder for method chaining.

Type Parameters

TOld

The old message type.

TNew

The new message type.

Remarks

Use this method when the upcaster has no dependencies and can be created directly.

Example:

builder.RegisterUpcaster<UserEventV1, UserEventV2>(new UserEventV1ToV2());

RegisterUpcaster<TOld, TNew>(Func<IServiceProvider, IMessageUpcaster<TOld, TNew>>)

Registers an upcaster using a factory function that receives the service provider.

public UpcastingBuilder RegisterUpcaster<TOld, TNew>(Func<IServiceProvider, IMessageUpcaster<TOld, TNew>> factory) where TOld : IDispatchMessage, IVersionedMessage where TNew : IDispatchMessage, IVersionedMessage

Parameters

factory Func<IServiceProvider, IMessageUpcaster<TOld, TNew>>

Factory function that creates the upcaster using DI services.

Returns

UpcastingBuilder

The builder for method chaining.

Type Parameters

TOld

The old message type.

TNew

The new message type.

Remarks

Use this method when the upcaster has dependencies that need to be resolved from DI.

Example:

builder.RegisterUpcaster<UserEventV1, UserEventV2>(sp =>
    new UserEventV1ToV2(sp.GetRequiredService<ILogger>()));

ScanAssemblies(IEnumerable<Assembly>, Func<Type, bool>?)

Scans multiple assemblies for upcaster types.

[RequiresUnreferencedCode("Assembly scanning uses reflection to discover upcaster types.")]
[RequiresDynamicCode("Assembly scanning registers generic upcasters at runtime.")]
public UpcastingBuilder ScanAssemblies(IEnumerable<Assembly> assemblies, Func<Type, bool>? filter = null)

Parameters

assemblies IEnumerable<Assembly>

The assemblies to scan.

filter Func<Type, bool>

Optional filter to exclude certain types.

Returns

UpcastingBuilder

The builder for method chaining.

ScanAssembly(Assembly, Func<Type, bool>?)

Scans an assembly for all types implementing IMessageUpcaster<TOld, TNew> and registers them with the pipeline.

[RequiresUnreferencedCode("Assembly scanning uses reflection to discover upcaster types.")]
[RequiresDynamicCode("Assembly scanning registers generic upcasters at runtime.")]
public UpcastingBuilder ScanAssembly(Assembly assembly, Func<Type, bool>? filter = null)

Parameters

assembly Assembly

The assembly to scan.

filter Func<Type, bool>

Optional filter to exclude certain types. Return true to include, false to exclude.

Returns

UpcastingBuilder

The builder for method chaining.

Remarks

This method discovers all concrete types implementing IMessageUpcaster<TOld, TNew> and creates instances using either their parameterless constructor or DI resolution.

Example:

// Scan all upcasters in the assembly
builder.ScanAssembly(typeof(Program).Assembly);

// Scan with filter builder.ScanAssembly(typeof(Program).Assembly, t => !t.Name.Contains("Test"));