Modify an Object Schema - .NET SDK
On this page
The following examples demonstrate how to add, delete, and modify properties in a schema. First, make the required schema change. Then, create a corresponding migration function to move data from the original schema to the updated schema.
The following page demonstrates how to modify schema properties of a local realm. Learn how to modify schema properties of a synced realm.
Assume that each schema change in this example occurs after an application has used each version for some amount of time. New schema version numbers only apply once you open the realm with an updated schema and explicitly specify the new version number, so in order to get to version 3, you would first need to open the app with versions 1 and 2.
A realm using schema version 1
has a Person
object type:
public class Person : RealmObject { [ ] [ ] public ObjectId Id { get; set; } public string FirstName { get; set; } public int Age { get; set; } }
Add a Property
The following example adds a LastName
property to the
original Person schema:
public class Person : RealmObject { [ ] [ ] public ObjectId Id { get; set; } public string FirstName { get; set; } public string LastName { get; set; } public int Age { get; set; } }
Delete a Property
The following example uses a combined
FullName
property instead of the separate FirstName
and
LastName
property in the original Person schema:
public class Person : RealmObject { [ ] [ ] public ObjectId Id { get; set; } public string FullName { get; set; } public int Age { get; set; } }
Modify a Property Type or Rename a Property
The following example modifies the Age
property in the
original Person schema by
renaming it to Birthday
and changing the type to DateTimeOffset
:
public class Person : RealmObject { [ ] [ ] public ObjectId Id { get; set; } public string FullName { get; set; } public DateTimeOffset Birthday { get; set; } }
Migration Functions
When developing or debugging your application, you may prefer to delete the realm instead of migrating it. Use the ShouldDeleteIfMigrationNeeded flag to delete the database automatically when a schema mismatch would require a migration.
Never release an app to production with this flag set to true
.
To migrate the realm to conform to the updated Person
schema, the
set the realm's schema version to
4
and define a migration function to set the value of
FullName
based on the existing FirstName
and LastName
properties and the value of Birthday
based on Age
:
1 var config = new RealmConfiguration 2 { 3 SchemaVersion = 4, 4 MigrationCallback = (migration, oldSchemaVersion) => 5 { 6 var oldPeople = migration.OldRealm.All<Person>(); 7 var newPeople = migration.NewRealm.All<Person>(); 8 9 // Migrate Person objects 10 for (var i = 0; i < newPeople.Count(); i++) 11 { 12 var oldPerson = oldPeople.ElementAt(i); 13 var newPerson = newPeople.ElementAt(i); 14 15 // Changes from version 1 to 2 (adding LastName) will occur automatically when Realm detects the change 16 17 // Migrate Person from version 2 to 3: replace FirstName and LastName with FullName 18 // LastName doesn't exist in version 1 19 if (oldSchemaVersion < 2) 20 { 21 newPerson.FullName = oldPerson.FirstName; 22 } 23 else if (oldSchemaVersion < 3) 24 { 25 newPerson.FullName = $"{oldPerson.FirstName} {oldPerson.LastName}"; 26 } 27 28 // Migrate Person from version 3 to 4: replace Age with Birthday 29 if (oldSchemaVersion < 4) 30 { 31 var birthYear = DateTimeOffset.UtcNow.Year - oldPerson.Age; 32 newPerson.Birthday = new DateTimeOffset(birthYear, 1, 1, 0, 0, 0, TimeSpan.Zero); 33 } 34 } 35 } 36 }; 37 var realm = Realm.GetInstance(config);
Unity has various scripting restrictions and does not
support the dynamic keyword
when using IL2CPP.
Instead you can cast the Dynamic value to the type you want to use. In the
following example, the retrieved Person
objects are explicitly converted to
an IQueryable<RealmObject>
.
var oldPeople = (IQueryable<RealmObject>)migration.OldRealm.DynamicApi.All("Person"); // store results of retrieved Person objects