Table of Contents

Class Change<T>

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

Represents a single data change captured from a Change Data Capture (CDC) source.

public sealed record Change<T> : IEquatable<Change<T>>

Type Parameters

T

The type of the data entity that changed.

Inheritance
Change<T>
Implements
Inherited Members
Extension Methods

Examples

// Processing changes from an IChangeDataCapture source
await foreach (var change in cdc.GetChangesAsync(lastPosition, cancellationToken))
{
    switch (change.Type)
    {
        case ChangeType.Insert:
            await HandleInsertAsync(change.After!);
            break;
        case ChangeType.Update:
            await HandleUpdateAsync(change.Before, change.After!);
            break;
        case ChangeType.Delete:
            await HandleDeleteAsync(change.Before!);
            break;
    }

    // Checkpoint after processing
    await stateStore.SavePositionAsync(change.Position);
}

Remarks

This record provides a provider-agnostic representation of a data change event. The generic type parameter allows strongly-typed access to the before/after data.

State Availability by Change Type:

ChangeTypeBefore/After Availability
InsertBefore is null; After contains inserted data
UpdateBefore contains previous state (if supported); After contains new state
DeleteBefore contains deleted data (if supported); After is null

Before-Image Support: Not all providers support before-images for updates and deletes:

  • SQL Server: Requires CDC "all columns" tracking mode
  • Postgres: Requires REPLICA IDENTITY FULL or appropriate index
  • MongoDB: Requires explicit pre-image recording (changeStreamPreAndPostImages)
  • CosmosDB: Does not support before-images
  • DynamoDB: Requires NEW_AND_OLD_IMAGES stream view type

Constructors

Change(ChangeType, T?, T?, ChangePosition, DateTimeOffset)

Represents a single data change captured from a Change Data Capture (CDC) source.

public Change(ChangeType Type, T? Before, T? After, ChangePosition Position, DateTimeOffset Timestamp)

Parameters

Type ChangeType

The type of change that occurred.

Before T

The state of the entity before the change, or null for inserts or when before-images are not available.

After T

The state of the entity after the change, or null for deletes.

Position ChangePosition

The position in the CDC stream where this change occurred. Used for checkpointing and resumption.

Timestamp DateTimeOffset

The timestamp when this change was committed to the source database.

Examples

// Processing changes from an IChangeDataCapture source
await foreach (var change in cdc.GetChangesAsync(lastPosition, cancellationToken))
{
    switch (change.Type)
    {
        case ChangeType.Insert:
            await HandleInsertAsync(change.After!);
            break;
        case ChangeType.Update:
            await HandleUpdateAsync(change.Before, change.After!);
            break;
        case ChangeType.Delete:
            await HandleDeleteAsync(change.Before!);
            break;
    }

    // Checkpoint after processing
    await stateStore.SavePositionAsync(change.Position);
}

Remarks

This record provides a provider-agnostic representation of a data change event. The generic type parameter allows strongly-typed access to the before/after data.

State Availability by Change Type:

ChangeTypeBefore/After Availability
InsertBefore is null; After contains inserted data
UpdateBefore contains previous state (if supported); After contains new state
DeleteBefore contains deleted data (if supported); After is null

Before-Image Support: Not all providers support before-images for updates and deletes:

  • SQL Server: Requires CDC "all columns" tracking mode
  • Postgres: Requires REPLICA IDENTITY FULL or appropriate index
  • MongoDB: Requires explicit pre-image recording (changeStreamPreAndPostImages)
  • CosmosDB: Does not support before-images
  • DynamoDB: Requires NEW_AND_OLD_IMAGES stream view type

Properties

After

The state of the entity after the change, or null for deletes.

public T? After { get; init; }

Property Value

T

Before

The state of the entity before the change, or null for inserts or when before-images are not available.

public T? Before { get; init; }

Property Value

T

HasAfterImage

Gets a value indicating whether this change includes after-image data.

public bool HasAfterImage { get; }

Property Value

bool

true if After is not null; otherwise, false.

HasBeforeImage

Gets a value indicating whether this change includes before-image data.

public bool HasBeforeImage { get; }

Property Value

bool

true if Before is not null; otherwise, false.

Position

The position in the CDC stream where this change occurred. Used for checkpointing and resumption.

public ChangePosition Position { get; init; }

Property Value

ChangePosition

Timestamp

The timestamp when this change was committed to the source database.

public DateTimeOffset Timestamp { get; init; }

Property Value

DateTimeOffset

Type

The type of change that occurred.

public ChangeType Type { get; init; }

Property Value

ChangeType

Methods

GetKey<TKey>(Func<T, TKey>)

Gets the entity key or identifier from the available before/after data.

public TKey GetKey<TKey>(Func<T, TKey> keySelector)

Parameters

keySelector Func<T, TKey>

A function that extracts the key from an entity.

Returns

TKey

The key extracted from After if available; otherwise, the key from Before.

Type Parameters

TKey

The type of the entity key.

Exceptions

InvalidOperationException

Thrown when both Before and After are null.