Class CdcRecoveryOptions
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
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
- Throw - Throws exception (legacy behavior)
- FallbackToEarliest - Resume from earliest (safe, may reprocess)
- FallbackToLatest - Skip to latest (data loss possible)
- InvokeCallback - Custom handling via callback
Methods
FromCdcOptions(CdcOptions)
Creates a CdcRecoveryOptions from the recovery-related properties of CdcOptions.
public static CdcRecoveryOptions FromCdcOptions(CdcOptions cdcOptions)
Parameters
cdcOptionsCdcOptionsThe 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
cdcOptionsisnull.
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.