Interface ICdcStateStore
Defines the contract for storing and retrieving CDC checkpoint positions.
public interface ICdcStateStore
- Extension Methods
Examples
// Using state store with CDC processor
public class CdcConsumer
{
private readonly IChangeDataCapture<Order> _cdc;
private readonly ICdcStateStore _stateStore;
private const string ConsumerId = "order-sync-service";
public async Task ProcessAsync(CancellationToken ct)
{
// Load last checkpoint
var checkpoint = await _stateStore.GetPositionAsync(ConsumerId, ct);
await foreach (var change in _cdc.GetChangesAsync(checkpoint, ct))
{
await ProcessChangeAsync(change);
// Save checkpoint after processing
await _stateStore.SavePositionAsync(ConsumerId, change.Position, ct);
}
}
}
Remarks
The state store provides durable storage for CDC positions, enabling:
- Crash recovery - Resume processing from the last acknowledged position
- Consumer tracking - Multiple consumers can maintain independent positions
- Progress monitoring - Track how far behind each consumer is
Implementation Guidelines:
- Implementations should be durable (survive restarts)
- Consider using the same database as the CDC source for transactional consistency
- Provide atomic updates to prevent lost checkpoints
Methods
DeletePositionAsync(string, CancellationToken)
Deletes the checkpoint for the specified consumer.
Task<bool> DeletePositionAsync(string consumerId, CancellationToken cancellationToken)
Parameters
consumerIdstringA unique identifier for the CDC consumer.
cancellationTokenCancellationTokenA token to observe for cancellation requests.
Returns
Remarks
Use this to reset a consumer to start processing from the beginning, or to clean up checkpoints for decommissioned consumers.
GetAllPositionsAsync(CancellationToken)
Gets all consumer positions tracked by this state store.
IAsyncEnumerable<(string ConsumerId, ChangePosition Position)> GetAllPositionsAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenA token to observe for cancellation requests.
Returns
- IAsyncEnumerable<(string ConsumerId, ChangePosition Position)>
An async enumerable of consumer ID and position pairs.
Remarks
Use this for monitoring and operational visibility into consumer progress.
GetPositionAsync(string, CancellationToken)
Gets the last saved position for the specified consumer.
Task<ChangePosition?> GetPositionAsync(string consumerId, CancellationToken cancellationToken)
Parameters
consumerIdstringA unique identifier for the CDC consumer. This allows multiple consumers to independently track their positions in the same CDC stream.
cancellationTokenCancellationTokenA token to observe for cancellation requests.
Returns
- Task<ChangePosition>
The last saved position for the consumer, or null if no checkpoint exists (indicating the consumer should start from the beginning).
SavePositionAsync(string, ChangePosition, CancellationToken)
Saves a position checkpoint for the specified consumer.
Task<CdcPositionSaveOutcome> SavePositionAsync(string consumerId, ChangePosition position, CancellationToken cancellationToken)
Parameters
consumerIdstringA unique identifier for the CDC consumer.
positionChangePositionThe position to save. This represents the last successfully processed change.
cancellationTokenCancellationTokenA token to observe for cancellation requests.
Returns
- Task<CdcPositionSaveOutcome>
What the store did: Advanced when the checkpoint now holds
position, or one of the refusals when it does not. Callers MUST test for Advanced BY NAME — deciding success by excluding the known refusals makes every member added later a success, which is how this contract would fail open.
Remarks
Atomicity: Implementations MUST apply the checkpoint atomically. If the save does not apply, the previous checkpoint remains intact and the return value says so.
Monotonicity is permitted, and it is observable. An implementation MAY refuse to move its checkpoint backwards, reporting RefusedAsStale; an implementation with no such guard performs an unconditional write and reports Advanced. Both are conforming. What is NOT conforming is declining the write and leaving the caller unable to tell: the outcome is the whole point of the return value.
Transactional Processing: For exactly-once semantics, consider saving the checkpoint in the same transaction as the business operation that processes the change.
Exceptions
- ArgumentException
consumerIdis empty or whitespace.- ArgumentNullException
positionis null.- ObjectDisposedException
The store has been disposed.
- OperationCanceledException
cancellationTokenwas signalled.