Table of Contents

Class CdcPositionResetEventArgs

Namespace
Excalibur.Cdc
Assembly
Excalibur.Cdc.dll

Provides data for a CDC position reset event when a stale position is detected.

public sealed class CdcPositionResetEventArgs
Inheritance
CdcPositionResetEventArgs
Inherited Members

Remarks

This is the canonical event args type for all CDC providers. It contains comprehensive information about a stale position scenario, including the capture instance affected, the invalid position, available recovery positions, and diagnostic context.

A stale position occurs when the saved CDC position (e.g., LSN for SQL Server) is no longer valid in the change tables. This can happen due to:

  • CDC cleanup jobs purging old records
  • Database backup/restore operations
  • CDC being disabled and re-enabled
  • Change stream token expiration (for document databases)

Properties

AdditionalContext

Gets or sets additional context information for diagnostics.

public IDictionary<string, object>? AdditionalContext { get; init; }

Property Value

IDictionary<string, object>

Remarks

Provider-specific diagnostic information can be included here, such as:

  • SQL Server: Error number, SQL state, procedure name
  • MongoDB: Cluster time, operation time
  • CosmosDB: Request charge, activity ID

AttemptNumber

Gets or sets the recovery attempt number (1-based).

public int AttemptNumber { get; init; }

Property Value

int

Remarks

Recovery may be attempted multiple times based on MaxRecoveryAttempts. This property indicates which attempt is currently in progress.

CaptureInstance

Gets or sets the name of the CDC capture instance (tracked table) affected.

public string CaptureInstance { get; init; }

Property Value

string

The capture instance name. For SQL Server, this is typically "schema_tablename" (e.g., "dbo_Orders"). For other providers, this may be the collection or table name.

DatabaseName

Gets or sets the database name where the stale position was detected.

public string DatabaseName { get; init; }

Property Value

string

DetectedAt

Gets or sets the timestamp when the stale position was detected.

public DateTimeOffset DetectedAt { get; init; }

Property Value

DateTimeOffset

EarliestAvailablePosition

Gets or sets the earliest available position in the CDC change tables.

public byte[]? EarliestAvailablePosition { get; init; }

Property Value

byte[]

Remarks

This represents the oldest change that can still be read. Resuming from this position is safe but may result in reprocessing previously handled events.

LatestAvailablePosition

Gets or sets the latest available position in the CDC change tables.

public byte[]? LatestAvailablePosition { get; init; }

Property Value

byte[]

Remarks

This represents the most recent change. Resuming from this position skips all unprocessed changes between the stale position and now.

NewPosition

Gets or sets the position that the processor will resume from after recovery.

public byte[]? NewPosition { get; init; }

Property Value

byte[]

Remarks

This will be either the earliest or latest available position depending on the configured Strategy.

OriginalException

Gets or sets the original exception that caused the stale position detection.

public Exception? OriginalException { get; init; }

Property Value

Exception

Remarks

For SQL Server, this is typically a SqlException with error number 22037 or 22029. For other providers, this contains the provider-specific exception.

ProcessorId

Gets or sets the unique identifier of the CDC processor instance.

public string ProcessorId { get; init; }

Property Value

string

The processor identifier, typically the database connection identifier.

ProviderType

Gets or sets the type of CDC provider that detected the stale position.

public string ProviderType { get; init; }

Property Value

string

The provider type name (e.g., "SqlServer", "Postgres", "MongoDB", "CosmosDb").

ReasonCode

Gets or sets the reason code explaining why the position became stale.

public string ReasonCode { get; init; }

Property Value

string

A standardized reason code. Common values include:

  • CDC_CLEANUP - Position purged by CDC cleanup job
  • BACKUP_RESTORE - Position invalid after database restore
  • CDC_REENABLED - CDC was disabled and re-enabled
  • LSN_OUT_OF_RANGE - LSN is outside the valid range
  • TOKEN_EXPIRED - Change stream token expired (document databases)
  • UNKNOWN - Reason could not be determined

ReasonMessage

Gets or sets the human-readable reason message for the position reset.

public string ReasonMessage { get; init; }

Property Value

string

StalePosition

Gets or sets the stale position that was detected as invalid.

public byte[]? StalePosition { get; init; }

Property Value

byte[]

Remarks

The position format is provider-specific:

  • SQL Server: LSN (Log Sequence Number) as a 10-byte array
  • Postgres: WAL position as bytes
  • MongoDB: Resume token as bytes
  • CosmosDB: Continuation token as bytes

May be null if the position could not be determined.

Strategy

Gets or sets the recovery strategy that will be applied.

public StalePositionRecoveryStrategy Strategy { get; init; }

Property Value

StalePositionRecoveryStrategy

Methods

ToString()

Returns a string representation of the event for logging purposes.

public override string ToString()

Returns

string

A formatted string containing the key properties.