Class CdcProcessor
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
appLifetimeIHostApplicationLifetimeProvides notifications about application lifetime events.
dbConfigIDatabaseOptionsThe database configuration for CDC processing.
cdcRepositoryCdcRepositoryThe CDC repository for querying change data.
stateStoreConnectionFactoryFunc<IDbConnection>Supplies a connection per CDC-state operation.
stateStoreOptionsIOptions<SqlServerCdcStateStoreOptions>The CDC state store options.
policyFactoryIDataAccessPolicyFactoryThe factory for creating data access policies.
timeProviderTimeProviderThe time provider used for the stale-position recovery backoff delay, so recovery retries are deterministically testable without wall-clock sleeps.
loggerILogger<CdcProcessor>The logger used to log diagnostics and operational information.
fatalErrorOptionsIOptions<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
disposingboolWhether 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
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
eventHandlerFunc<DataChangeEvent, CancellationToken, Task>A delegate that handles each DataChangeEvent. This handler should be idempotent and thread-safe, and must handle its own exceptions appropriately.
cancellationTokenCancellationTokenA cancellation token to stop processing.
Returns
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
cancellationTokenstill surfaces as OperationCanceledException even when disposal reaches the invocation as well.- InvalidOperationException