Partition-Based Sync - .NET SDK

Partition Value

When you select Partition-Based Sync for your backend App configuration, your client implementation must include a partition value. This is the value of the partition key field you select when you configure Partition-Based Sync.

The partition value determines which data the client application can access. You pass in the partition value when you open a synced realm.

Open a Partition-Based Sync Realm While Online

The steps for opening a synced realm while online are:

1. Your app code walks the user through authenticating.

2. Create a PartitionSyncConfiguration object that includes the partition value and the User object.

3. Open a synced realm by calling the GetInstanceAsync() method, passing in the PartitionSyncConfiguration object.

The following code demonstrates these steps:

user = await app.LogInAsync(
    Credentials.EmailPassword("caleb@mongodb.com", "MySekritPwd"));
config = new PartitionSyncConfiguration("myPart", user);
try
{
    realm = await Realm.GetInstanceAsync(config);
}
catch (Exception ex)
{
    Console.WriteLine($@"Error creating or opening the
        realm file. {ex.Message}");
}

In the above example, the code shows how to open the realm asynchronously by calling GetInstanceAsync(). You can also open a realm synchronously by calling the GetInstance() method:

var synchronousRealm = Realm.GetInstance(config);

Open a Partition-Based Sync Realm While Offline

Once a user authenticates, the User object persists on the device until the user logs off. This allows your app to retrieve an existing user and open a synced realm in an offline state. Changes that occur while offline will be synced by the SDK once the device reconnects to your App.

The following code shows how to check if there is an existing User object. If none is found, it uses the process outlined about to obtain a user. If the device already has a user, it opens the synced realm with that user:

if (app.CurrentUser == null)
{
    // App must be online for user to authenticate
    user = await app.LogInAsync(
        Credentials.EmailPassword("caleb@mongodb.com", "MySekritPwd"));
    config = new PartitionSyncConfiguration("_part", user);
    realm = await Realm.GetInstanceAsync(config);
}
else
{
    // This works whether online or offline
    user = app.CurrentUser;
    config = new PartitionSyncConfiguration("_part", user);
    realm = Realm.GetInstance(config);
}

Migrate from Partition-Based Sync to Flexible Sync

You can migrate your App Services Device Sync Mode from Partition-Based Sync to Flexible Sync. Migrating is an automatic process that does not require any changes to your application code. Automatic migration requires Realm .NET SDK version 11.1.0 or newer.

Migrating enables you to keep your existing App Services users and authentication configuration. Flexible Sync provides more versatile permissions configuration options and more granular data synchronization.

For more information about how to migrate your App Services App from Partition-Based Sync to Flexible Sync, refer to Migrate Device Sync Modes.

Migrate from Non-Synced Realms to Synced Realms

You can convert a non-synced realm to a synced realm (with partition-based sync). To convert from a non-synced realm to one that uses partition-based sync, you do the following:

1. Open the existing realm.

2. Create a configuration for a new realm.

3. Call the WriteCopy() method on the existing realm to copy the data to the new realm.

In the following code, we open a non-synced realm, create a new PartitionSyncConfiguration object and then copy the existing realm to the new realm. We then delete the existing realm and open the new realm.

var existingConfig = new RealmConfiguration("example.realm");
var existingRealm = Realm.GetInstance(existingConfig);
var app = App.Create("my-app-id");
var user = await app.LogInAsync(
    Credentials.EmailPassword("email@example.com", "password"));
var syncConfig = new PartitionSyncConfiguration("user_partition", user);
existingRealm.WriteCopy(syncConfig);
// You can now delete the nonsynced realm:
Realm.DeleteRealm(existingConfig);
// You can now use the synced realm:
var syncedRealm = Realm.GetInstance(syncConfig);