Table of Contents

Class CdcRecoveryOptions

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

Configuration options for CDC stale position recovery behavior.

public sealed class CdcRecoveryOptions
Inheritance
CdcRecoveryOptions
Inherited Members

Remarks

These options control 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.

The default configuration uses FallbackToEarliest which is the safest option, potentially reprocessing events but ensuring no data loss.

Properties

EnableStructuredLogging

Gets or sets a value indicating whether to log structured events for position resets.

public bool EnableStructuredLogging { get; set; }

Property Value

bool

true to enable structured logging; otherwise, false. Default is true.

MaxRecoveryAttempts

Gets or sets the maximum number of recovery attempts before giving up.

[Range(0, 2147483647)]
public int MaxRecoveryAttempts { get; set; }

Property Value

int

The maximum number of retry attempts. Default is 3.

Remarks

After exhausting all recovery attempts, the processor will throw a SqlServerCdcStalePositionException regardless of the configured strategy.

OnPositionReset

Gets or sets the callback invoked when a stale position reset occurs.

public CdcPositionResetHandler? OnPositionReset { get; set; }

Property Value

CdcPositionResetHandler

The callback delegate, or null if not configured.

Remarks

This callback is required when RecoveryStrategy 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 RecoveryStrategy.

RecoveryAttemptDelay

Gets or sets the delay between recovery attempts.

public TimeSpan RecoveryAttemptDelay { get; set; }

Property Value

TimeSpan

The delay between attempts. Default is 1 second.

RecoveryStrategy

Gets or sets the strategy for handling stale position scenarios.

public StalePositionRecoveryStrategy RecoveryStrategy { get; set; }

Property Value

StalePositionRecoveryStrategy

The recovery strategy to use. Default is FallbackToEarliest.

Remarks

Methods

FromCdcOptions(CdcOptions)

Creates a CdcRecoveryOptions from the recovery-related properties of CdcOptions.

public static CdcRecoveryOptions FromCdcOptions(CdcOptions cdcOptions)

Parameters

cdcOptions CdcOptions

The CDC options containing recovery configuration.

Returns

CdcRecoveryOptions

A new CdcRecoveryOptions with properties copied from the source.

Remarks

This factory eliminates the need to manually copy each recovery property when bridging from the user-facing CdcOptions (in Excalibur.Cdc) to the provider-specific CdcRecoveryOptions (in Excalibur.Cdc.SqlServer). If a new recovery property is added to CdcOptions, it only needs to be added here rather than at every bridge site.

Exceptions

ArgumentNullException

Thrown if cdcOptions is null.

Validate()

Validates the options and throws if the configuration is invalid.

public void Validate()

Exceptions

InvalidOperationException

Thrown when RecoveryStrategy is InvokeCallback but OnPositionReset is not configured.