Table of Contents

Interface IMigrationDiagnostics

Namespace
KeenEyes.Serialization
Assembly
KeenEyes.Core.dll

Extended migrator interface that provides diagnostic capabilities for migration operations.

public interface IMigrationDiagnostics : IComponentMigrator
Inherited Members

Examples

var diagnostics = serializer as IMigrationDiagnostics;
if (diagnostics is not null)
{
    // Get detailed migration result with timing
    var result = diagnostics.MigrateWithDiagnostics("MyComponent", data, 1, 4);
    Console.WriteLine(result.TotalElapsed);

    // Inspect the migration graph
    var graph = diagnostics.GetMigrationGraph(typeof(MyComponent));
    Console.WriteLine(graph.ToDiagnosticString());
}

Remarks

This interface extends IComponentMigrator with methods for:

  • Migrating with detailed timing and step information
  • Inspecting migration graphs for components
  • Finding migration chain gaps
  • Generating diagnostic reports

Implementations are generated by the source generator when components define migration methods using [MigrateFrom].

Methods

FindAllMigrationGaps()

Finds all gaps in migration chains across all registered components.

IReadOnlyDictionary<string, IReadOnlyList<int>> FindAllMigrationGaps()

Returns

IReadOnlyDictionary<string, IReadOnlyList<int>>

A dictionary mapping component type names to their missing version migrations. Only includes components that have at least one gap.

Remarks

A gap exists when a component at version N is missing a migration from some version V to V+1 (where 1 ≤ V < N).

Use this method to identify incomplete migration chains that would prevent loading older save files.

GenerateDiagnosticReport()

Generates a complete diagnostic report for all migrations.

string GenerateDiagnosticReport()

Returns

string

A multi-line string containing diagnostic information.

Remarks

The report includes:

  • All registered components with migrations
  • Migration graphs for each component
  • Any gaps or issues detected

GetComponentsWithMigrations()

Gets all component types that have migrations defined.

IEnumerable<string> GetComponentsWithMigrations()

Returns

IEnumerable<string>

An enumerable of type names with migrations.

GetMigrationGraph(string)

Gets the migration graph for a component type.

MigrationGraph? GetMigrationGraph(string typeName)

Parameters

typeName string

The fully-qualified type name of the component.

Returns

MigrationGraph

The migration graph for the component, or null if the component has no migrations defined.

Remarks

The returned graph can be used to:

  • Inspect available migration paths
  • Find gaps in the migration chain
  • Generate diagnostic reports

GetMigrationGraph(Type)

Gets the migration graph for a component type.

MigrationGraph? GetMigrationGraph(Type type)

Parameters

type Type

The component type.

Returns

MigrationGraph

The migration graph for the component, or null if the component has no migrations defined.

MigrateWithDiagnostics(string, JsonElement, int, int)

Migrates component data with detailed diagnostic information.

MigrationResult MigrateWithDiagnostics(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.

fromVersion int

The source version of the component data.

toVersion int

The target version to migrate to.

Returns

MigrationResult

A MigrationResult containing the migrated data and timing information.

Remarks

Unlike Migrate(string, JsonElement, int, int), this method captures detailed timing for each migration step and returns a rich result object with diagnostic information.

Use this method when you need to:

  • Profile migration performance
  • Debug slow migrations
  • Get detailed error information on failure

MigrateWithDiagnostics(Type, JsonElement, int, int)

Migrates component data with detailed diagnostic information.

MigrationResult MigrateWithDiagnostics(Type type, JsonElement data, int fromVersion, int toVersion)

Parameters

type Type

The component type.

data JsonElement

The JSON element containing the component data.

fromVersion int

The source version of the component data.

toVersion int

The target version to migrate to.

Returns

MigrationResult

A MigrationResult containing the migrated data and timing information.

Edit this page