Class CdcPositionResetEventArgs
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
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
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
DetectedAt
Gets or sets the timestamp when the stale position was detected.
public DateTimeOffset DetectedAt { get; init; }
Property Value
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
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 jobBACKUP_RESTORE- Position invalid after database restoreCDC_REENABLED- CDC was disabled and re-enabledLSN_OUT_OF_RANGE- LSN is outside the valid rangeTOKEN_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
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
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.