Interface ICdcRecoveryBuilder
Fluent builder interface for configuring CDC recovery settings.
public interface ICdcRecoveryBuilder
Examples
cdc.WithRecovery(recovery =>
{
recovery.Strategy(StalePositionRecoveryStrategy.FallbackToEarliest)
.MaxAttempts(5)
.AttemptDelay(TimeSpan.FromSeconds(30))
.OnPositionReset((args, ct) => { /* custom handling */ })
.EnableStructuredLogging(true);
});
Remarks
This builder configures how the CDC processor handles scenarios where the saved position (LSN) is no longer valid in the database. This can occur due to CDC cleanup jobs, database restores, or CDC being disabled and re-enabled.
All methods return this for method chaining.
Methods
AttemptDelay(TimeSpan)
Sets the delay between recovery attempts.
ICdcRecoveryBuilder AttemptDelay(TimeSpan delay)
Parameters
delayTimeSpanThe delay between attempts.
Returns
- ICdcRecoveryBuilder
The builder for fluent chaining.
Examples
recovery.AttemptDelay(TimeSpan.FromSeconds(30));
Remarks
Default is 1 second.
Exceptions
- ArgumentOutOfRangeException
Thrown when
delayis negative.
EnableStructuredLogging(bool)
Enables or disables structured logging for recovery events.
ICdcRecoveryBuilder EnableStructuredLogging(bool enable = true)
Parameters
enableboolWhether to enable structured logging. Default is true.
Returns
- ICdcRecoveryBuilder
The builder for fluent chaining.
Examples
recovery.EnableStructuredLogging(false);
Remarks
When enabled, detailed structured log events will be emitted for position resets and recovery attempts, useful for monitoring and alerting.
Default is enabled.
MaxAttempts(int)
Sets the maximum number of recovery attempts before giving up.
ICdcRecoveryBuilder MaxAttempts(int count)
Parameters
countintThe maximum number of retry attempts.
Returns
- ICdcRecoveryBuilder
The builder for fluent chaining.
Examples
recovery.MaxAttempts(5);
Remarks
After exhausting all recovery attempts, the processor will throw
a CdcStalePositionException regardless of the configured strategy.
Default is 3 attempts.
Exceptions
- ArgumentOutOfRangeException
Thrown when
countis negative.
OnPositionReset(CdcPositionResetHandler)
Configures a custom handler for position reset events.
ICdcRecoveryBuilder OnPositionReset(CdcPositionResetHandler handler)
Parameters
handlerCdcPositionResetHandlerThe handler delegate.
Returns
- ICdcRecoveryBuilder
The builder for fluent chaining.
Examples
recovery.OnPositionReset(async (args, ct) =>
{
logger.LogWarning("Position reset for {CaptureInstance}", args.CaptureInstance);
await Task.CompletedTask;
});
Remarks
This callback is required when Strategy is set to InvokeCallback.
The callback is also invoked (if configured) for other strategies to allow
logging or alerting, but the recovery action is determined by the strategy.
Exceptions
- ArgumentNullException
Thrown when
handleris null.
Strategy(StalePositionRecoveryStrategy)
Sets the recovery strategy for stale positions.
ICdcRecoveryBuilder Strategy(StalePositionRecoveryStrategy strategy)
Parameters
strategyStalePositionRecoveryStrategyThe recovery strategy to use.
Returns
- ICdcRecoveryBuilder
The builder for fluent chaining.
Examples
recovery.Strategy(StalePositionRecoveryStrategy.FallbackToLatest);
Remarks
Available strategies:
Throw- Throws exception (legacy behavior)FallbackToEarliest- Resume from earliest (safe, may reprocess)FallbackToLatest- Skip to latest (data loss possible)InvokeCallback- Custom handling via callback
Default is FallbackToEarliest.