Docs Menu
Docs Home
/ /
Atlas Device SDKs
/ /

Partition-Based Sync - .NET SDK

On this page

  • Partition Value
  • Open a Partition-Based Sync Realm While Online
  • Open a Partition-Based Sync Realm While Offline
  • Migrate from Partition-Based Sync to Flexible Sync
  • Updating Client Code After Migration
  • Migrate from Non-Synced Realms to Synced Realms

Partition-Based Sync is an older mode for using Atlas Device Sync with the Realm .NET SDK. We recommend using Flexible Sync for new apps. The information on this page is for users who are still using Partition-Based Sync.

Tip

Realm .NET SDK v11.1.0 and newer supports the ability to migrate from Partition-Based Sync to Flexible Sync. For more information, refer to: Migrate from Partition-Based Sync to Flexible Sync. We recommend you migrate your older Partition-Based Sync apps to use Flexible Sync.

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.

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);

Tip

See also:

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);
}

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.

The automatic migration from Partition-Based Sync to Flexible Sync does not require any changes to your client code. However, to support this functionality, Realm automatically handles the differences between the two Sync Modes by:

  • Automatically creating Flexible Sync subscriptions for each object type where partitionKey == partitionValue.

  • Injecting a partitionKey field into every object if one does not already exist. This is required for the automatic Flexible Sync subscription.

If you need to make updates to your client code after migration, consider updating your client codebase to remove hidden migration functionality. You might want update your client codebase when:

  • You add a new model or change a model in your client codebase

  • You add or change functionality that involves reading or writing Realm objects

  • You want to implement more fine-grained control over what data you sync

Make these changes to convert your Partition-Based Sync client code to use Flexible Sync:

  • Change your PartitionSyncConfiguration to a FlexibleSyncConfiguration.

  • Add relevant properties to your object models to use in your Flexible Sync subscriptions. For example, you might add an ownerId property to enable a user to sync only their own data.

  • Remove automatic Flexible Sync subscriptions and manually create the relevant subscriptions.

For examples of Flexible Sync permissions strategies, including examples of how to model data for these strategies, refer to Device Sync Permissions Guide.

When you migrate from Partition-Based Sync to Flexible Sync, Realm automatically creates hidden Flexible Sync subscriptions for your app. The next time you add or change subscriptions, we recommend that you:

  1. Remove the automatically-generated subscriptions.

  2. Manually add the relevant subscriptions in your client codebase.

This enables you to see all of your subscription logic together in your codebase for future iteration and debugging.

For more information about the automatically-generated Flexible Sync subscriptions, refer to Migrate Client App to Flexible Sync.

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);

Note

Partition-Based Sync Only

This method only supports converting between a non-sync realm and Partition-Based Sync. If your app uses Flexible Sync, you must manually iterate through the objects in one realm and copy them into the other realm.

Back

Stream Data to Atlas

Next

Use the SDK in a Console App