Interface ICdcBuilder
Fluent builder interface for configuring Excalibur CDC processor.
public interface ICdcBuilder
- Extension Methods
Examples
services.AddCdcProcessor(cdc =>
{
cdc.UseSqlServer(sql =>
{
sql.ConnectionString(connectionString)
.SchemaName("cdc")
.StateTableName("CdcProcessingState")
.PollingInterval(TimeSpan.FromSeconds(5))
.BatchSize(100);
})
.TrackTable("dbo.Orders", table =>
{
table.MapInsert<OrderCreatedEvent>()
.MapUpdate<OrderUpdatedEvent>()
.MapDelete<OrderDeletedEvent>();
})
.TrackTable("dbo.Customers", table =>
{
table.MapInsert<CustomerCreatedEvent>()
.MapAll<CustomerChangedEvent>();
})
.WithRecovery(recovery =>
{
recovery.Strategy(StalePositionRecoveryStrategy.FallbackToEarliest)
.MaxAttempts(3)
.AttemptDelay(TimeSpan.FromSeconds(1));
})
.EnableBackgroundProcessing();
});
Remarks
This interface follows the Microsoft-style fluent builder pattern. It provides the single entry point for CDC configuration.
All methods return this for method chaining, enabling a fluent configuration experience.
For table discovery via configuration binding or handler auto-discovery, see ICdcBuilderDiscovery which is implemented by the same concrete builder.
Properties
Services
Gets the service collection being configured.
IServiceCollection Services { get; }
Property Value
Methods
BindProcessingConfiguration(string)
Binds CdcProcessingOptions to the specified configuration section path.
ICdcBuilder BindProcessingConfiguration(string sectionPath)
Parameters
sectionPathstringThe configuration section path (e.g.,
"Cdc:Processing").
Returns
- ICdcBuilder
The builder for fluent chaining.
Examples
cdc.EnableBackgroundProcessing()
.BindProcessingConfiguration("Cdc:Processing");
Remarks
When specified, the CdcProcessingOptions will be bound to the given
configuration section, allowing runtime control via appsettings.json or any
IConfiguration source.
Exceptions
- ArgumentNullException
Thrown when
sectionPathis null.- ArgumentException
Thrown when
sectionPathis empty or whitespace.
EnableBackgroundProcessing(bool)
Enables background processing of CDC changes.
ICdcBuilder EnableBackgroundProcessing(bool enable = true)
Parameters
enableboolWhether to enable background processing. Default is true.
Returns
- ICdcBuilder
The builder for fluent chaining.
Examples
cdc.UseSqlServer(sql => sql.ConnectionString(connectionString))
.TrackTable("dbo.Orders", t => t.MapAll<OrderChangedEvent>())
.EnableBackgroundProcessing();
Remarks
When enabled, a hosted service will be registered that periodically polls for CDC changes and processes them through the configured event handlers.
For serverless scenarios where background services are not suitable,
omit this call and use ICdcProcessor directly.
TrackTable(string, Action<ICdcTableBuilder>)
Configures tracking for a database table with event mappings.
ICdcBuilder TrackTable(string tableName, Action<ICdcTableBuilder> configure)
Parameters
tableNamestringThe fully qualified table name (e.g., "dbo.Orders").
configureAction<ICdcTableBuilder>The table tracking configuration action.
Returns
- ICdcBuilder
The builder for fluent chaining.
Examples
cdc.TrackTable("dbo.Orders", table =>
{
table.MapInsert<OrderCreatedEvent>()
.MapUpdate<OrderUpdatedEvent>()
.MapDelete<OrderDeletedEvent>();
});
Remarks
Use this method to configure which database tables to track for changes and how to map those changes to domain events.
Table naming conventions: Use singular, schema-qualified names
(e.g., "dbo.Order" not "Orders"). SQL Server CDC capture instances
are derived from table names, so consistent naming avoids ambiguity when querying
cdc.fn_cdc_get_all_changes_* functions. If your database uses plural table
names, pass the exact name as it appears in the database.
Exceptions
- ArgumentNullException
Thrown when
tableNameorconfigureis null.
TrackTable<TEntity>(Action<ICdcTableBuilder>?)
Configures tracking for a database table inferred from entity type.
ICdcBuilder TrackTable<TEntity>(Action<ICdcTableBuilder>? configure = null) where TEntity : class
Parameters
configureAction<ICdcTableBuilder>Optional table tracking configuration action.
Returns
- ICdcBuilder
The builder for fluent chaining.
Type Parameters
TEntityThe entity type to infer table name from.
Examples
cdc.TrackTable<Order>(table =>
{
table.MapAll<OrderChangedEvent>();
});
Remarks
The table name is inferred from the entity type name using the singular form
(e.g., TrackTable<Order>() maps to {DefaultSchema}.Order).
No naive pluralization is applied. For custom table names (e.g., plural tables
or non-default schemas), use the string overload:
TrackTable("sales.OrderItems", configure).
WithRecovery(Action<ICdcRecoveryBuilder>)
Configures recovery options for stale position handling.
ICdcBuilder WithRecovery(Action<ICdcRecoveryBuilder> configure)
Parameters
configureAction<ICdcRecoveryBuilder>The recovery configuration action.
Returns
- ICdcBuilder
The builder for fluent chaining.
Examples
cdc.WithRecovery(recovery =>
{
recovery.Strategy(StalePositionRecoveryStrategy.FallbackToEarliest)
.MaxAttempts(5)
.AttemptDelay(TimeSpan.FromSeconds(30));
});
Remarks
Use this method to configure how the CDC processor handles scenarios where the saved position (LSN) is no longer valid in the database.
Exceptions
- ArgumentNullException
Thrown when
configureis null.