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
registryISerializerRegistryThe serializer registry containing registered serializers.
loggerILogger<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
storeIMigrationStoreThe migration store to process.
sourceSerializerIdbyteThe source serializer ID (magic byte) to migrate from.
targetSerializerIdbyteThe target serializer ID (magic byte) to migrate to.
cancellationTokenCancellationTokenCancellation token.
progressIProgress<EncryptionMigrationProgress>Optional progress reporter.
optionsMigrationOptionsOptional 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.