Quick Start - .NET SDK

Install Realm

Follow these steps to add the Realm .NET SDK to your project.

Import Realm

Add the following line to the top of your source files to use Realm:

using Realms;

Define Your Object Model

Your application's object model defines the data that you can store within Realm Database and synchronize to and from App Services.

The following code shows how to define an object model for a Item object. In this example, we have marked the Id field as the Primary Key, marked the Name and Status properties as "required", and are using the MapTo attribute so we can use .NET-friendly casing on our property names when using Device Sync.

using MongoDB.Bson;
using Realms;
namespace Examples.Models
{
    public class Item : RealmObject
    {
        [PrimaryKey]
        [MapTo("_id")]
        public ObjectId Id { get; set; } = ObjectId.GenerateNewId();
        [MapTo("_partition")]
        [Required]
        public string Partition { get; set; }
        [MapTo("assignee")]
        public User Assignee { get; set; }
        [MapTo("name")]
        [Required]
        public string Name { get; set; }
        [MapTo("status")]
        [Required]
        public string Status { get; set; }
    }

Open a Local Realm

In a local-only Realm Database, you open a realm with either the Realm.GetInstance() or Realm.GetInstanceAsync() method. Which method you use depends entirely on if and how you are using asynchronous patterns in your app. The following code shows how to use GetInstance():

var realm = Realm.GetInstance();

For more information, see: Open a Realm.

Create, Read, Update, and Delete Objects

Once you have opened a realm, you can create objects in it. All writes must occur within a Write transaction block.

The following code shows how to create a new Guitar object. In it, we instantiate the Guitar class and then add the new guitar to the realm within a Write() block:

realm.Write(() =>
{
    realm.Add(new Guitar()
    {
        Make = "Gibson",
        Model = "Les Paul Custom",
        Price = 649.99,
        Owner = "N. Young"
    });
});

You can retrieve a live collection of all Guitar objects in the realm:

var allGuitars = realm.All<Guitar>();

You can filter the collection by using the LINQ syntax:

var lessExpensiveGuitars = realm.All<Guitar>().Where(g => g.Price < 400);
var guitarsSortedByMake = realm.All<Guitar>().OrderBy(g => g.Make);
var specifiGuitarById = realm.Find<Guitar>(someGuitarId);

To modify a realm object, update its properties in a write transaction block:

var davidsStrat = realm.All<Guitar>().FirstOrDefault(
    g => g.Owner == "D. Gilmour"
    && g.Make == "Fender"
    && g.Model == "Stratocaster");
realm.Write(() =>
{
    davidsStrat.Price = 1700345.56;
});

Finally, you can delete a todo:

var mostExpensiveGuitar = realm.All<Guitar>()
    .OrderByDescending(g => g.Price).First();
realm.Write(() =>
{
    realm.Remove(mostExpensiveGuitar);
});

Watch for Changes

You can watch a realm, collection, or object for changes with the SubscribeForNotifications() method.

Be sure to retain the notification token returned by SubscribeForNotifications as long as you want to continue watching for changes. When you are done, call the Dispose() method:

var token = fido.Owners.SubscribeForNotifications((sender, changes, error) =>
{
    if (error != null) return;
    if (changes == null) return;
});
token.Dispose();

Add Device Sync (Optional)

If you want to sync Realm data across devices, you can set up an Atlas App Services App and enable Device Sync. For more information on what you can do with App Services, see: Application Services - .NET SDK.

app = App.Create(myRealmAppId);

var user = await app.LogInAsync(Credentials.Anonymous());

await user.LogOutAsync();

var config = new FlexibleSyncConfiguration(app.CurrentUser)
{
    PopulateInitialSubscriptions = (realm) =>
    {
        var myItems = realm.All<Item>().Where(n => n.OwnerId == myUserId);
        realm.Subscriptions.Add(myItems);
    }
};
// The process will complete when all the user's items have been downloaded.
var realm = await Realm.GetInstanceAsync(config);