Class ScyllaMigrationAttribute

Marks a static method as a schema migration handler that upgrades serialized data from one schema version to another during deserialization.

Inheritance
object
Attribute
ScyllaMigrationAttribute
Inherited Members
Namespace: Scylla.Core.Util.Serialization
Assembly: ScyllaCore.dll
Syntax
[AttributeUsage(AttributeTargets.Method, Inherited = false)]
public sealed class ScyllaMigrationAttribute : Attribute
Remarks

When the Scylla serialization engine deserializes an object whose stored $version is lower than the current schema version declared on the type's ScyllaSerializableAttribute, it discovers all methods on the declaring type that carry [ScyllaMigration] and applies them in ascending version order, chaining the output of each step into the next. For example, if stored data is at version 1 and the current type is version 3, the engine runs the v1-to-v2 migration first, then feeds the result into the v2-to-v3 migration.

The decorated method must satisfy all of the following requirements, which the engine validates at metadata-discovery time; methods that do not conform are silently ignored:

  • The method must be static.
  • The method must accept exactly one parameter whose type matches the declaring class or struct.
  • The method's return type must match the declaring class or struct.

The canonical method signature is: private static T MigrateName(T instance)

Migration methods are discovered on the type using BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static, so they may be private, internal, or public. Using private is the recommended convention to keep migration logic encapsulated.

The declaring type must also be annotated with ScyllaSerializableAttribute specifying the current schema version; without it, the engine has no version information and migrations are never triggered. 

[ScyllaSerializable(version: 3)]
public class PlayerData
{
    public string Name { get; set; }
    public int Health { get; set; }
    public int MaxHealth { get; set; }  // Added in v2
    public int Shield { get; set; }     // Added in v3

[ScyllaMigration(1, 2)]
private static PlayerData MigrateV1ToV2(PlayerData old)
{
    old.MaxHealth = 100;
    return old;
}

[ScyllaMigration(2, 3)]
private static PlayerData MigrateV2ToV3(PlayerData old)
{
    old.Shield = 0;
    return old;
}



}

Constructors

ScyllaMigrationAttribute(int, int)

Initializes a new instance of the ScyllaMigrationAttribute class with the specified source and target schema versions.

Declaration
public ScyllaMigrationAttribute(int fromVersion, int toVersion)
Parameters
Type Name Description
int fromVersion

The schema version that the decorated method migrates from. Must be at least 1. This value is stored in FromVersion.
int toVersion

The schema version that the decorated method migrates to. Must be strictly greater than fromVersion. This value is stored in ToVersion.
Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown if fromVersion is less than 1, or if toVersion is less than or equal to fromVersion.

Properties

FromVersion

Gets the schema version that the decorated migration method upgrades from.

Declaration
public int FromVersion { get; }
Property Value
Type Description
int

A positive integer (minimum 1) representing the source schema version. The engine invokes this migration when deserializing an object stored at this exact version and the chain requires a step to ToVersion.

ToVersion

Gets the schema version that the decorated migration method produces as output.

Declaration
public int ToVersion { get; }
Property Value
Type Description
int

A positive integer strictly greater than FromVersion. After the migration method runs, the engine treats the instance as being at this version and continues applying subsequent migrations if further upgrades are needed.

Extension Methods

See Also