Table of Contents

Class ChangePosition

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.Abstractions.dll

Abstract base class representing a position in a Change Data Capture (CDC) stream.

public abstract class ChangePosition : IEquatable<ChangePosition>
Inheritance
ChangePosition
Implements
Derived
Inherited Members
Extension Methods

Examples

// Provider-specific position example (Postgres)
public sealed class PostgresCdcPosition : ChangePosition
{
    public NpgsqlLogSequenceNumber Lsn { get; }

    public PostgresCdcPosition(NpgsqlLogSequenceNumber lsn)
    {
        Lsn = lsn;
    }

    public override string ToToken() => Lsn.ToString();
    public override bool IsValid => Lsn != NpgsqlLogSequenceNumber.Invalid;

    public static PostgresCdcPosition Parse(string token) =>
        new(NpgsqlLogSequenceNumber.Parse(token));
}

Remarks

Each CDC provider has its own native position representation:

ProviderPosition Type
SQL ServerLog Sequence Number (LSN) - byte array
PostgresWAL Log Sequence Number - 64-bit value (e.g., "0/1234ABCD")
MongoDBResume Token - BsonDocument
CosmosDBContinuation Token - string
DynamoDBShard Iterator - string
FirestoreSnapshot time or document change sequence

Provider implementations derive from this class to provide strongly-typed positions while maintaining a common interface for position serialization and comparison.

Implementation Guidelines:

  • Override ToToken() to serialize position for storage/resumption.
  • Override IsValid to indicate whether the position represents a valid point in the stream.
  • Provide a static Parse(string token) or TryParse method for deserialization.
  • Implement IComparable<T> if position ordering is meaningful for the provider.

Properties

IsValid

Gets a value indicating whether this position represents a valid point in the CDC stream.

public abstract bool IsValid { get; }

Property Value

bool

true if this position can be used to resume CDC processing; false if this is an invalid or uninitialized position.

Remarks

Invalid positions typically represent:

  • Uninitialized default positions
  • Positions that have been invalidated (e.g., WAL segment recycled)
  • Sentinel values indicating "start from beginning" or "no checkpoint"

Timestamp

Gets the timestamp associated with this position, if available.

public virtual DateTimeOffset? Timestamp { get; }

Property Value

DateTimeOffset?

The timestamp when the change at this position occurred, or null if the provider does not support position timestamps.

Remarks

Not all providers include timestamps in their position representation. When available, this can be used for time-based CDC resumption or monitoring.

Methods

Equals(ChangePosition?)

Indicates whether the current object is equal to another object of the same type.

public abstract bool Equals(ChangePosition? other)

Parameters

other ChangePosition

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Determines whether the specified object is equal to the current object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

true if the specified object is equal to the current object; otherwise, false.

GetHashCode()

Serves as the default hash function.

public override abstract int GetHashCode()

Returns

int

A hash code for the current object.

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

ToToken()

Converts this position to a string token suitable for storage and resumption.

public abstract string ToToken()

Returns

string

A string representation of this position that can be persisted and later used to resume CDC processing from this point.

Remarks

The token format is provider-specific but must be round-trippable through the corresponding Parse method on the derived type.

Operators

operator ==(ChangePosition?, ChangePosition?)

Determines whether two positions are equal.

public static bool operator ==(ChangePosition? left, ChangePosition? right)

Parameters

left ChangePosition

The first position to compare.

right ChangePosition

The second position to compare.

Returns

bool

true if the positions are equal; otherwise, false.

operator !=(ChangePosition?, ChangePosition?)

Determines whether two positions are not equal.

public static bool operator !=(ChangePosition? left, ChangePosition? right)

Parameters

left ChangePosition

The first position to compare.

right ChangePosition

The second position to compare.

Returns

bool

true if the positions are not equal; otherwise, false.