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
enableboolTrue 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
upcasterIMessageUpcaster<TOld, TNew>The upcaster instance.
Returns
- UpcastingBuilder
The builder for method chaining.
Type Parameters
TOldThe old message type.
TNewThe 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
factoryFunc<IServiceProvider, IMessageUpcaster<TOld, TNew>>Factory function that creates the upcaster using DI services.
Returns
- UpcastingBuilder
The builder for method chaining.
Type Parameters
TOldThe old message type.
TNewThe 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
assembliesIEnumerable<Assembly>The assemblies to scan.
filterFunc<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
assemblyAssemblyThe assembly to scan.
filterFunc<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"));