Quick Start - .NET SDK

Overview

This page contains information to get Realm Database integrated into your .NET app.

Import Realm

In the shared code project of your solution, go to Manage NuGet Packages. In the NuGet Package Manager, switch to the Browse tab and then search for Realm. Select the latest version of the Realm package, and then click Add Package.

At the top of each C# file that uses Realm, add the following using statement:

using Realms;

Define Your Object Model

Your application's object model defines the data that you can store within Realm Database. You define an object model by creating a C# class that inherits from the RealmObject class.

Add the following using statement at the top of your C# file:

using MongoDB.Bson;

The following code shows how to define an object model for a Guitar object. In this example, we have marked the Id field as the Primary Key, and marked the Make and Model properties as "Required". Note that the Id is of type ObjectId in this case, and a new Id is generated when an instance of the class is created.

public class Guitar : RealmObject
{
    [PrimaryKey]
    public ObjectId Id { get; set; } = ObjectId.GenerateNewId();
    [Required]
    public string Make { get; set; }
    [Required]
    public string Model { get; set; }
    public double Price { get; set; }
    public string Owner { get; set; }
}

Open a Realm

To open your app's realm, you call either Realm.GetInstance() or Realm.GetInstanceAsync(). 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();

Create Realm 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 realm.Write block:

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

Find, Sort, and Filter Objects

The following code demonstrates how to:

• retrieve a live collection of all Guitar objects in the realm,
• filter the collection by using the Linq syntax,
• sort the collection, and
• find a specific item in the collection by Id:

var allGuitars = realm.All<Guitar>();
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);

Modify an Object

As with writes, any changes to a Realm object must occur within a Write transaction block. To modify an object, you update the object properties:

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

Delete an Object

You can delete an object by calling the Remove() method within a write transaction block:

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

Watch a Collection

If you want your app to respond to changes as they occur in a collection, you can call SubscribeForNotifications() on the collection, as shown in the following code:

// Watch for Guitar collection changes.
var token = realm.All<Guitar>()
    .SubscribeForNotifications((sender, changes, error) =>
    {
        foreach (var i in changes.DeletedIndices)
        {
            // ... handle deletions ...
        }
        foreach (var i in changes.InsertedIndices)
        {
            // ... handle insertions ...
        }
        foreach (var i in changes.NewModifiedIndices)
        {
            // ... handle modifications ...
        }
    });
// Later, when you no longer wish to receive notifications
token.Dispose();