Table of Contents

Interface ICdcBuilder

Namespace
Excalibur.Cdc
Assembly
Excalibur.Cdc.dll

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

IServiceCollection

The IServiceCollection.

Methods

BindProcessingConfiguration(string)

Binds CdcProcessingOptions to the specified configuration section path.

ICdcBuilder BindProcessingConfiguration(string sectionPath)

Parameters

sectionPath string

The 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 sectionPath is null.

ArgumentException

Thrown when sectionPath is empty or whitespace.

EnableBackgroundProcessing(bool)

Enables background processing of CDC changes.

ICdcBuilder EnableBackgroundProcessing(bool enable = true)

Parameters

enable bool

Whether 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

tableName string

The fully qualified table name (e.g., "dbo.Orders").

configure Action<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 tableName or configure is 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

configure Action<ICdcTableBuilder>

Optional table tracking configuration action.

Returns

ICdcBuilder

The builder for fluent chaining.

Type Parameters

TEntity

The 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

configure Action<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 configure is null.