Table of Contents

Class CdcProcessor

Namespace
Excalibur.Cdc.SqlServer
Assembly
Excalibur.Cdc.SqlServer.dll

Processes Change Data Capture (CDC) changes by reading from a database, managing state, and invoking a specified event handler.

public class CdcProcessor : ISqlServerCdcProcessor, ICdcProcessor<DataChangeEvent>, IAsyncDisposable, IDisposable
Inheritance
CdcProcessor
Implements
Derived
Inherited Members

Remarks

Orchestrates a producer-consumer pipeline: the producer reads CDC rows from the database, the consumer processes them via a caller-supplied event handler. Stale LSN positions are recovered automatically when CdcRecoveryOptions is configured.

Implementation delegates to Excalibur.Cdc.SqlServer.CdcCheckpointManager (LSN tracking and state persistence), Excalibur.Cdc.SqlServer.CdcChangeDetector (producer / CDC row fetching), and Excalibur.Cdc.SqlServer.CdcChangeApplier (consumer / event processing). This class owns the channel, the recovery retry loop, and the disposal lifecycle.

Constructors

CdcProcessor(IHostApplicationLifetime, IDatabaseOptions, CdcRepository, Func<IDbConnection>, IOptions<SqlServerCdcStateStoreOptions>?, IDataAccessPolicyFactory, TimeProvider, ILogger<CdcProcessor>, IOptions<CdcFatalErrorOptions<DataChangeEvent>>?)

Initializes a new instance of the CdcProcessor class.

public CdcProcessor(IHostApplicationLifetime appLifetime, IDatabaseOptions dbConfig, CdcRepository cdcRepository, Func<IDbConnection> stateStoreConnectionFactory, IOptions<SqlServerCdcStateStoreOptions>? stateStoreOptions, IDataAccessPolicyFactory policyFactory, TimeProvider timeProvider, ILogger<CdcProcessor> logger, IOptions<CdcFatalErrorOptions<DataChangeEvent>>? fatalErrorOptions = null)

Parameters

appLifetime IHostApplicationLifetime

Provides notifications about application lifetime events.

dbConfig IDatabaseOptions

The database configuration for CDC processing.

cdcRepository CdcRepository

The CDC repository for querying change data.

stateStoreConnectionFactory Func<IDbConnection>

Supplies a connection per CDC-state operation.

stateStoreOptions IOptions<SqlServerCdcStateStoreOptions>

The CDC state store options.

policyFactory IDataAccessPolicyFactory

The factory for creating data access policies.

timeProvider TimeProvider

The time provider used for the stale-position recovery backoff delay, so recovery retries are deterministically testable without wall-clock sleeps.

logger ILogger<CdcProcessor>

The logger used to log diagnostics and operational information.

fatalErrorOptions IOptions<CdcFatalErrorOptions<DataChangeEvent>>

Options containing an optional delegate that is invoked when a non-recoverable exception occurs during CDC processing. If the delegate is not configured, the processor will rethrow the exception and stop processing.

Exceptions

ArgumentNullException

Thrown if any required dependency is null .

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Dispose(bool)

Releases resources after all admitted processing has stopped.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

Whether managed resources should be released.

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

DisposeCoreAsync()

Disposes of resources used by the CdcProcessor.

protected virtual ValueTask DisposeCoreAsync()

Returns

ValueTask

ProcessBatchAsync(Func<DataChangeEvent, CancellationToken, Task>, CancellationToken)

Processes CDC changes asynchronously by producing changes from the database and consuming them with the provided handler. Ensures events are processed in strict order to preserve consistency across related changes.

public Task<int> ProcessBatchAsync(Func<DataChangeEvent, CancellationToken, Task> eventHandler, CancellationToken cancellationToken)

Parameters

eventHandler Func<DataChangeEvent, CancellationToken, Task>

A delegate that handles each DataChangeEvent. This handler should be idempotent and thread-safe, and must handle its own exceptions appropriately.

cancellationToken CancellationToken

A cancellation token to stop processing.

Returns

Task<int>

The total number of events processed.

Remarks

If an unhandled exception occurs during ordered event processing, the error is logged at Critical level and passed to the fatal error handler delegate, if supplied. If not supplied, the processor will rethrow and stop execution.

Exceptions

ObjectDisposedException

Thrown if the instance is already disposed, and also if it is disposed while this invocation is still waiting to be admitted behind another one. A waiting invocation reports the disposal rather than a cancellation so that the refusal does not depend on scheduling: the instance is gone, so a retry cannot succeed. A cancellation requested through cancellationToken still surfaces as OperationCanceledException even when disposal reaches the invocation as well.

InvalidOperationException