Table of Contents

Interface ICdcRecoveryBuilder

Namespace
Excalibur.Cdc
Assembly
Excalibur.Cdc.dll

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

delay TimeSpan

The 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 delay is negative.

EnableStructuredLogging(bool)

Enables or disables structured logging for recovery events.

ICdcRecoveryBuilder EnableStructuredLogging(bool enable = true)

Parameters

enable bool

Whether 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

count int

The 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 count is negative.

OnPositionReset(CdcPositionResetHandler)

Configures a custom handler for position reset events.

ICdcRecoveryBuilder OnPositionReset(CdcPositionResetHandler handler)

Parameters

handler CdcPositionResetHandler

The 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 handler is null.

Strategy(StalePositionRecoveryStrategy)

Sets the recovery strategy for stale positions.

ICdcRecoveryBuilder Strategy(StalePositionRecoveryStrategy strategy)

Parameters

strategy StalePositionRecoveryStrategy

The 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.