Table of Contents

Class SerializerMigrationService

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

Service for migrating data between serialization formats in persistence stores.

public class SerializerMigrationService
Inheritance
SerializerMigrationService
Inherited Members
Extension Methods

Remarks

This service implements Phase 3 of the four-phase migration strategy. It provides methods for bulk migration of existing data from one serializer format to another.

Key Features:

  • Batch processing to prevent memory pressure
  • Progress reporting via IProgress<T>
  • Idempotent execution (safe to re-run)
  • Optional read-back verification
  • Configurable error handling

Usage:

// Migrate outbox from MemoryPack to System.Text.Json
var progress = new Progress<EncryptionMigrationProgress>(p =>
    Console.WriteLine($"Progress: {p}"));

var result = await migrationService.MigrateStoreAsync( outboxMigrationStore, SerializerIds.MemoryPack, SerializerIds.SystemTextJson, progress);

See the serialization migration strategy documentation.

Constructors

SerializerMigrationService(ISerializerRegistry, ILogger<SerializerMigrationService>)

Initializes a new instance of the SerializerMigrationService class.

public SerializerMigrationService(ISerializerRegistry registry, ILogger<SerializerMigrationService> logger)

Parameters

registry ISerializerRegistry

The serializer registry containing registered serializers.

logger ILogger<SerializerMigrationService>

The logger instance.

Exceptions

ArgumentNullException

Thrown when registry or logger is null.

Methods

MigrateStoreAsync(IMigrationStore, byte, byte, CancellationToken, IProgress<EncryptionMigrationProgress>?, MigrationOptions?)

Migrates all records in a store from one serializer format to another.

[RequiresUnreferencedCode("Serializer migration uses runtime type resolution and serialization which may require preserved members.")]
[RequiresDynamicCode("Serializer migration uses runtime type resolution and serialization which may require dynamic code generation.")]
public Task<EncryptionMigrationProgress> MigrateStoreAsync(IMigrationStore store, byte sourceSerializerId, byte targetSerializerId, CancellationToken cancellationToken, IProgress<EncryptionMigrationProgress>? progress = null, MigrationOptions? options = null)

Parameters

store IMigrationStore

The migration store to process.

sourceSerializerId byte

The source serializer ID (magic byte) to migrate from.

targetSerializerId byte

The target serializer ID (magic byte) to migrate to.

cancellationToken CancellationToken

Cancellation token.

progress IProgress<EncryptionMigrationProgress>

Optional progress reporter.

options MigrationOptions

Optional migration options. Uses defaults if not specified.

Returns

Task<EncryptionMigrationProgress>

The final migration progress with total counts.

Remarks

The migration is idempotent - running it multiple times is safe. Records already in the target format are automatically skipped.

The operation processes records in batches to limit memory usage. Progress is reported after each batch is processed.

Exceptions

ArgumentNullException

Thrown when store is null.

InvalidOperationException

Thrown when source or target serializer is not registered.

OperationCanceledException

Thrown when cancellation is requested.