Table of Contents

Interface IMigrationStore

Namespace
Excalibur.Dispatch.Serialization
Assembly
Excalibur.Dispatch.dll

Interface for stores that support serializer migration operations.

public interface IMigrationStore
Extension Methods

Remarks

This interface defines the contract for stores that can participate in serializer migration. Implementations should be provided for:

  • SqlServerOutboxStore
  • MessageInbox (Inbox)
  • SqlServerEventStore

The migration service uses this interface to:

  • Query records by source serializer ID
  • Update payloads with new serialization format
  • Count pending migrations for progress estimation

See the migration strategy documentation.

Properties

StoreName

Gets the name of this store for logging and diagnostics.

string StoreName { get; }

Property Value

string

Remarks

Examples: "OutboxStore", "InboxStore", "EventStore".

Methods

CountPendingMigrationsAsync(byte, CancellationToken)

Counts the total number of records that need migration from a source serializer.

Task<int> CountPendingMigrationsAsync(byte sourceSerializerId, CancellationToken cancellationToken)

Parameters

sourceSerializerId byte

The serializer ID to migrate from.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<int>

The count of records needing migration.

Remarks

This count is used for progress estimation. It may be expensive for large tables, so implementations may choose to return an approximate count or cache the result.

GetBatchForMigrationAsync(byte, byte, int, CancellationToken)

Gets a batch of records that need migration from a source serializer.

Task<IReadOnlyList<IMigrationRecord>> GetBatchForMigrationAsync(byte sourceSerializerId, byte targetSerializerId, int batchSize, CancellationToken cancellationToken)

Parameters

sourceSerializerId byte

The serializer ID to migrate from (magic byte value). Records with this magic byte in their payload will be returned.

targetSerializerId byte

The serializer ID to migrate to. Records already in this format are excluded.

batchSize int

Maximum number of records to return.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<IMigrationRecord>>

A batch of records ready for migration, or empty if no more records need migration.

Remarks

The query should efficiently filter by magic byte. For SQL Server, this means:

WHERE CAST(SUBSTRING(Payload, 1, 1) AS TINYINT) = @SourceSerializerId

Records should be returned in a consistent order (e.g., by ID) to ensure deterministic batch processing.

GetPayloadAsync(string, CancellationToken)

Gets the payload for a specific record (for read-back verification).

Task<byte[]?> GetPayloadAsync(string recordId, CancellationToken cancellationToken)

Parameters

recordId string

The unique identifier of the record.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<byte[]>

The payload bytes, or null if the record doesn't exist.

UpdatePayloadAsync(string, byte[], CancellationToken)

Updates the payload of a record with the new serialized format.

Task<bool> UpdatePayloadAsync(string recordId, byte[] newPayload, CancellationToken cancellationToken)

Parameters

recordId string

The unique identifier of the record to update.

newPayload byte[]

The new payload bytes including the magic byte header for the target serializer.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<bool>

True if the record was updated, false if not found.

Remarks

The update should be atomic and should verify the record still exists. The implementation may use optimistic concurrency if appropriate.