Docs Menu

Open a Realm - .NET SDK

On this page

  • Local Realms
  • In-Memory Realms
  • Synced Realms
  • Open a Synced Realm While Online
  • Open a Synced Realm While Offline
  • Scoping the Realm
  • Class Subsets

When opening a local (non-synced) realm, pass a RealmConfiguration object to either GetInstanceAsync() or GetInstance(). The following example creates a RealmConfiguration object with a local file path, sets the IsReadOnly property to true, and then opens a local realm with that configuration information:

var config = new RealmConfiguration(pathToDb + "/my.realm")
{
IsReadOnly = true,
};
Realm localRealm;
try
{
localRealm = Realm.GetInstance(config);
}
catch (RealmFileAccessErrorException ex)
{
Console.WriteLine($@"Error creating or opening the
realm file. {ex.Message}");
}

With an InMemoryConfiguration object, you can create a realm that runs entirely in memory (that is, without the data written to disk.) The following example shows how to do this:

var config = new InMemoryConfiguration("some-identifier");
var realm = Realm.GetInstance(config);

In-memory realms might still use disk space if memory is running low, but all files created by an in-memory realm will be deleted when the realm is closed. When creating an in-memory realm, the identifier must be unique to all realms, including both in-memory and persisted realms.

Important

When an in-memory realm is disposed or garbage-collected, the data is lost. To keep an in-memory realm “alive” throughout your app’s execution, be sure to hold a reference to realm.

To open a synced realm, you must have an authenticated User object. To obtain an initial User instance, you need to authenticate against the Realm backend, which requires the device to be online the first time a user logs in. Once initial authentication has occurred, you can retrieve an existing user while offline.

Note

The first time a user logs on to your app, you should open the realm asynchronously to sync data from the server to the device in a background thread. After that initial sync, you can open a realm synchronously to ensure the app works in an offline state.

The steps for opening a synced realm while online are:

  1. Your app code walks the user through authenticating.
  2. Create a SyncConfiguration object that includes the partition name and the User object.
  3. Open a synced realm by calling the GetInstanceAsync() method, passing in the SyncConfiguration object.

The following code demonstrates these steps:

config = new SyncConfiguration("myPart", user);
var realm = await Realm.GetInstanceAsync(config);

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 Realm once the device is reconnected.

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", "shhhItsASektrit!"));
config = new SyncConfiguration("_part", user);
realm = await Realm.GetInstanceAsync(config);
}
else
{
// This works whether online or offline
user = app.CurrentUser;
config = new SyncConfiguration("_part", user);
realm = Realm.GetInstance(config);
}

The realm instance implements IDisposable to ensure native resources are freed up. You should dispose of a realm object immediately after use, especially on background threads. The simplest way to do this is by declaring the realm object with a using statement, or wrapping the code that interacts with a realm in a using (...) statement:

config = new SyncConfiguration("myPart", user);
using (var realm = Realm.GetInstance(config))
{
var allTasks = realm.All<Task>();
}

If you require a realm object to be shared outside of a single method, be sure to manage its state by calling the Dispose() method:

realm.Dispose();
Note

As a general rule, you should dispose of the realm only on background threads, because disposing of a realm invalidates all objects associated with that instance. If you are data binding the realm objects on the main thread, for example, you should not call Dispose().

By default, all RealmObject classes are stored in a realm. In some scenarios, you may want to limit the classes that get stored, which you can do with the ObjectClasses property of the RealmConfiguration object. The following code demonstrates how you specify two classes you want stored in the realm:

var config = new RealmConfiguration()
{
ObjectClasses = new Type[]
{
typeof(AClassWorthStoring),
typeof(AnotherClassWorthStoring)
}
};
Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.