Table of Contents

Interface IComponentMigrator

Namespace
KeenEyes.Serialization
Assembly
KeenEyes.Core.dll

Interface for AOT-compatible component migration.

public interface IComponentMigrator

Examples

// Use generated migrator during snapshot restoration
var migrator = new ComponentMigrator();  // Generated class

if (migrator.CanMigrate("MyComponent", fromVersion: 1, toVersion: 3))
{
    var migratedData = migrator.Migrate("MyComponent", oldData, fromVersion: 1, toVersion: 3);
    // Use migratedData to deserialize the component
}

Remarks

This interface is implemented by generated code when components define migration methods using the [MigrateFrom(version)] attribute. The source generator creates a strongly-typed implementation that chains migration methods automatically.

The migration pipeline invokes migrations sequentially for multi-version upgrades. For example, migrating from v1 to v4 calls: v1→v2, v2→v3, v3→v4.

Methods

CanMigrate(string, int, int)

Checks if a migration path exists for a component type.

bool CanMigrate(string typeName, int fromVersion, int toVersion)

Parameters

typeName string

The fully-qualified type name of the component.

fromVersion int

The source version of the component data.

toVersion int

The target version to migrate to.

Returns

bool

true if all migration steps from fromVersion to toVersion are available; false otherwise.

Remarks

This method checks that a complete migration chain exists. For example, to migrate from v1 to v3, migrations for v1→v2 and v2→v3 must both be defined.

Returns false if:

  • The component type is not registered
  • No migration is defined for any version step
  • fromVersion >= toVersion

CanMigrate(Type, int, int)

Checks if a migration path exists for a component type.

bool CanMigrate(Type type, int fromVersion, int toVersion)

Parameters

type Type

The component type.

fromVersion int

The source version of the component data.

toVersion int

The target version to migrate to.

Returns

bool

true if all migration steps from fromVersion to toVersion are available; false otherwise.

GetMigrationVersions(string)

Gets all registered migration source versions for a component type.

IEnumerable<int> GetMigrationVersions(string typeName)

Parameters

typeName string

The fully-qualified type name of the component.

Returns

IEnumerable<int>

An enumerable of version numbers that have migrations defined, or an empty enumerable if the type has no migrations or is not registered.

Remarks

This method is useful for diagnostics and determining which versions can be migrated. For example, if a component at v3 has migrations defined for v1 and v2, this returns [1, 2].

GetMigrationVersions(Type)

Gets all registered migration source versions for a component type.

IEnumerable<int> GetMigrationVersions(Type type)

Parameters

type Type

The component type.

Returns

IEnumerable<int>

An enumerable of version numbers that have migrations defined, or an empty enumerable if the type has no migrations or is not registered.

Migrate(string, JsonElement, int, int)

Migrates component data from one version to another.

JsonElement? Migrate(string typeName, JsonElement data, int fromVersion, int toVersion)

Parameters

typeName string

The fully-qualified type name of the component.

data JsonElement

The JSON element containing the component data at fromVersion.

fromVersion int

The source version of the component data.

toVersion int

The target version to migrate to.

Returns

JsonElement?

A JsonElement containing the migrated component data at toVersion, or null if migration is not possible.

Remarks

For multi-version migrations, this method chains the individual migration steps. For example, migrating from v1 to v3 internally calls the v1→v2 migration, serializes the result to JSON, then calls the v2→v3 migration.

The returned JsonElement is suitable for deserialization using Deserialize(string, JsonElement).

Exceptions

ComponentVersionException

Thrown when a migration step fails or when no migration path exists.

Migrate(Type, JsonElement, int, int)

Migrates component data from one version to another.

JsonElement? Migrate(Type type, JsonElement data, int fromVersion, int toVersion)

Parameters

type Type

The component type.

data JsonElement

The JSON element containing the component data at fromVersion.

fromVersion int

The source version of the component data.

toVersion int

The target version to migrate to.

Returns

JsonElement?

A JsonElement containing the migrated component data at toVersion, or null if migration is not possible.

Exceptions

ComponentVersionException

Thrown when a migration step fails or when no migration path exists.

Edit this page