Table of Contents

Class CdcRepository

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

Provides methods for interacting with SQL Server Change Data Capture (CDC) tables.

public class CdcRepository : ICdcRepository, IAsyncDisposable, IDisposable, ICdcRepositoryLsnMapping
Inheritance
CdcRepository
Implements
Inherited Members

Constructors

CdcRepository(IDb)

Initializes a new instance of the CdcRepository class using a database wrapper.

public CdcRepository(IDb db)

Parameters

db IDb

The database wrapper providing the connection.

Exceptions

ArgumentNullException

Thrown if db is null.

CdcRepository(IDbConnection, int)

Initializes a new instance of the CdcRepository class using a provided database connection.

public CdcRepository(IDbConnection connection, int commandTimeoutSeconds = 60)

Parameters

connection IDbConnection

The database connection to use for CDC queries.

commandTimeoutSeconds int

The command timeout in seconds for database operations. Defaults to RegularTimeoutSeconds (60s).

Exceptions

ArgumentNullException

Thrown if connection is null.

Methods

ChangesExistAsync(byte[], byte[], IEnumerable<string>, CancellationToken)

Checks if changes exist between two LSN positions for the specified capture instances.

public Task<bool> ChangesExistAsync(byte[] fromPosition, byte[] toPosition, IEnumerable<string> captureInstances, CancellationToken cancellationToken)

Parameters

fromPosition byte[]

The starting LSN position.

toPosition byte[]

The ending LSN position.

captureInstances IEnumerable<string>

A collection of capture instance names to query for changes.

cancellationToken CancellationToken

A token to observe while waiting for the task to complete.

Returns

Task<bool>

A task that represents the asynchronous operation, containing a boolean indicating whether changes exist.

Dispose()

Releases all resources used by the CdcRepository.

public void Dispose()

Dispose(bool)

Core disposal implementation.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

True if disposing managed resources; otherwise, false.

DisposeAsync()

Asynchronously releases the unmanaged resources used by the CdcRepository.

public ValueTask DisposeAsync()

Returns

ValueTask

A value task that represents the asynchronous dispose operation.

DisposeCoreAsync()

Core asynchronous disposal implementation.

protected virtual ValueTask DisposeCoreAsync()

Returns

ValueTask

A value task that represents the asynchronous disposal operation.

FetchChangesAsync(string, int, byte[], byte[], byte[]?, CdcOperationCodes, CancellationToken, string?)

Fetches change rows within an LSN range for the specified capture instance.

[SuppressMessage("Maintainability", "CA1506:Avoid excessive class coupling", Justification = "CDC query method requires many Dapper/ADO.NET/CDC types; coupling is inherent to the domain.")]
public Task<IEnumerable<CdcRow>> FetchChangesAsync(string captureInstance, int batchSize, byte[] fromLsn, byte[] toLsn, byte[]? lastSequenceValue, CdcOperationCodes lastOperation, CancellationToken cancellationToken, string? logicalTableName = null)

Parameters

captureInstance string

A capture instance table name to query for changes.

batchSize int

The number of records to retrieve in the batch.

fromLsn byte[]

The starting LSN position (inclusive).

toLsn byte[]

The ending LSN position (inclusive).

lastSequenceValue byte[]

The last processed sequence value, if any. This is used for processing changes with finer granularity.

lastOperation CdcOperationCodes

The CDC operation code filter for the types of changes to retrieve.

cancellationToken CancellationToken

A token to observe while waiting for the task to complete.

logicalTableName string

The logical table name to use in TableName instead of the capture instance. When null, the capture instance name is used (backward-compatible default). This allows handlers to match on the consumer-configured table name (e.g., dbo.Customers) rather than the SQL Server capture instance name (e.g., dbo_Customers).

Returns

Task<IEnumerable<CdcRow>>

An asynchronous stream of CdcRow instances representing the captured changes.

GetLsnToTimeAsync(byte[], CancellationToken)

Maps an LSN to a commit time in the database.

public Task<DateTime?> GetLsnToTimeAsync(byte[] lsn, CancellationToken cancellationToken)

Parameters

lsn byte[]

The LSN to map to a time.

cancellationToken CancellationToken

A token to observe while waiting for the task to complete.

Returns

Task<DateTime?>

A task that represents the asynchronous operation, containing the mapped commit time as a nullable DateTime.

GetMaxPositionAsync(CancellationToken)

Retrieves the maximum LSN currently available in the database.

public Task<byte[]> GetMaxPositionAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A token to observe while waiting for the task to complete.

Returns

Task<byte[]>

A task that represents the asynchronous operation, containing the maximum LSN as a byte array.

GetMinPositionAsync(string, CancellationToken)

Retrieves the minimum LSN for a specific capture instance.

public Task<byte[]> GetMinPositionAsync(string captureInstance, CancellationToken cancellationToken)

Parameters

captureInstance string

The capture instance to query.

cancellationToken CancellationToken

A token to observe while waiting for the task to complete.

Returns

Task<byte[]>

A task that represents the asynchronous operation, containing the minimum LSN as a byte array.

GetNextLsnAsync(byte[], CancellationToken)

Retrieves the next Log Sequence Number (LSN) after the specified last processed LSN.

public Task<byte[]> GetNextLsnAsync(byte[] lastProcessedLsn, CancellationToken cancellationToken)

Parameters

lastProcessedLsn byte[]

The LSN from which to find the next LSN.

cancellationToken CancellationToken

A token to observe while waiting for the task to complete.

Returns

Task<byte[]>

A task that represents the asynchronous operation, containing the next LSN as a byte array.

GetNextLsnAsync(string, byte[], CancellationToken)

Retrieves the next Log Sequence Number (LSN) after the specified last processed LSN for a specific capture instance.

public Task<byte[]?> GetNextLsnAsync(string captureInstance, byte[] lastProcessedLsn, CancellationToken cancellationToken)

Parameters

captureInstance string

The name of the capture instance to query for the next LSN.

lastProcessedLsn byte[]

The LSN from which to find the next LSN.

cancellationToken CancellationToken

A token to observe while waiting for the task to complete.

Returns

Task<byte[]>

A task that represents the asynchronous operation, containing the next LSN as a nullable byte array, or null if no next LSN is available.

GetNextValidLsnAsync(byte[], CancellationToken)

Retrieves the next valid LSN after the specified last processed LSN.

public Task<byte[]?> GetNextValidLsnAsync(byte[] lastProcessedLsn, CancellationToken cancellationToken)

Parameters

lastProcessedLsn byte[]

The LSN from which to find the next valid LSN.

cancellationToken CancellationToken

A token to observe while waiting for the task to complete.

Returns

Task<byte[]>

A task that represents the asynchronous operation, containing the next valid LSN as a nullable byte array.

GetTimeToLsnAsync(DateTime, string, CancellationToken)

Maps a time to an LSN using the specified relational operator.

public Task<byte[]?> GetTimeToLsnAsync(DateTime lsnDate, string relationalOperator, CancellationToken cancellationToken)

Parameters

lsnDate DateTime

The date to map to an LSN.

relationalOperator string

The relational operator for mapping (e.g., "smallest greater than", "largest less than or equal").

cancellationToken CancellationToken

A token to observe while waiting for the task to complete.

Returns

Task<byte[]>

A task that represents the asynchronous operation, containing the mapped LSN as a nullable byte array.