menu_bookDocumentation
Component Versioning: JsonUpgrader for Breaking Property Changes in s&box
s&box Component Versioning lets you define upgraders for breaking changes like property renames or data structure changes. Upgrades are chained — if a component is multiple versions behind, all missed upgrades run in sequence.
Implementation
Set ComponentVersion and define [JsonUpgrader] static methods:
CSHARP
public sealed class MyComponent : Component
{
[Property] public string[] StringPropertyArray { get; set; }
public override int ComponentVersion => 2;
// Version 1: Rename StringProperty → NewStringProperty
[JsonUpgrader( typeof( MyComponent ), 1 )]
private static void StringPropertyUpgrader( JsonObject json )
{
json.Remove( "StringProperty", out var newNode );
json["NewStringProperty"] = newNode;
}
// Version 2: Convert NewStringProperty → StringPropertyArray
[JsonUpgrader( typeof( MyComponent ), 2 )]
private static void StringPropertyIntoArray( JsonObject json )
{
json.Remove( "NewStringProperty", out var newNode );
var jsonArray = new JsonArray { newNode };
json["StringPropertyArray"] = jsonArray;
}
}Key Points
- Default ComponentVersion is 0 — set it to your newest version
- Each [JsonUpgrader] receives the raw JsonObject for manipulation
- Upgrades chain automatically (version 0 → 1 → 2 runs both upgraders)
- Useful for renaming properties, changing types, restructuring data, or migrating to new formats
Was this helpful?