Dictionaries - .NET SDK

On this page

Overview

Dictionary Types
Usage Example
Watching For Changes

Atlas Device SDKs are deprecated. Refer to the deprecation page for details.

New in version 10.2.0.

Overview

A Realm dictionary is an implementation of IDictionary that has keys of type String and supports values of any Realm type except collections. To define a dictionary, use a getter-only IDictionary<string, TValue> property, where TValue is any of the supported types.

Dictionary Types

A dictionary of objects can contain null objects. Likewise, dictionaries of primitive types can also contain null values. If you do not want to allow null values in a dictionary, then either use non-nullable types in the dictionary declaration (for example, use IDictionary<string, double> instead of IDictionary<string, double?>). If you are using the older schema type definition (your classes derive from the RealmObject base class), or you do not have nullability enabled, use the [Required] attribute if the dictionary contains nullable reference types, such as string or byte[].

Realm disallows the use of . or $ characters in map keys. You can use percent encoding and decoding to store a map key that contains one of these disallowed characters.

Important

Nullable Values Not Supported with Sync

Local-only realms support collections of nullable (optional) values, but Sync does not.

The following code shows examples of dictionary types:

public partial class Inventory : IRealmObject
{
    [PrimaryKey]
    [MapTo("_id")]
    public string Id { get; set; }
    // The key must be of type string; the value can be
    // of any Realm-supported type, including objects
    // that inherit from RealmObject or EmbeddedObject
    public IDictionary<string, Plant?> Plants { get; }
    public IDictionary<string, bool> BooleansDictionary { get; }
    // Nullable types are supported in local-only
    // Realms, but not with Sync
    public IDictionary<string, int?> NullableIntDictionary { get; }
    public IDictionary<string, string> RequiredStringsDictionary { get; }
}

Usage Example

The following code shows how to create, write to, and read from Dictionaries using either a string query (RQL) or LINQ.

var storeInventory = new Inventory()
{
    Id = ObjectId.GenerateNewId().ToString()
};
storeInventory.Plants.Add("Petunia", new Plant());
storeInventory.NullableIntDictionary.Add("random things", 7);
storeInventory.RequiredStringsDictionary.Add("foo", "bar");
var storeInventory2 = new Inventory()
{
    Id = ObjectId.GenerateNewId().ToString()
};
storeInventory2.RequiredStringsDictionary.Add("foo", "Bar");
realm.Write(() =>
{
    realm.Add(storeInventory);
    realm.Add(storeInventory2);
});
// Find all Inventory items that have "Petunia"
// as a key in their Plants dictionary.
var petunias = realm.All<Inventory>()
    .Filter("Plants.@keys == 'Petunia'");
// Find all Inventory items that have at least one value in their
// IntDictionary that is larger than 5 using RQL
var matchesMoreThanFive = realm.All<Inventory>()
    .Filter("NullableIntDictionary.@values > 5");
// Find all Inventory items where the RequiredStringsDictionary has a key
// "Foo", and the value of that key contains the phrase "bar"
// (case insensitive)
var matches = realm.All<Inventory>()
    .Filter("RequiredStringsDictionary['foo'] CONTAINS[c] 'bar'");
// matches.Count() == 2
// Query the Plants dictionary of an Inventory object
// for a specific plant
var myStoreInventory = realm
    .All<Inventory>().FirstOrDefault();
var petunia = myStoreInventory.Plants.AsRealmQueryable()
    .Where(p => p.Name == "Petunia");

Watching For Changes

You can use the INotifyCollectionChanged.CollectionChanged event on a dictionary to watch for changes to the collection, and the INotifyPropertyChanged.PropertyChanged event to watch for changes to specific properties in the dictionary.

In the following code example, we have a class with an IDictionary<string, int> property named IntDictionary. We set up event handlers for both the CollectionChanged and PropertyChanged events:

var dictionary = container.IntDictionary.AsRealmCollection();
dictionary.CollectionChanged += (sender, e) =>
{
    Console.WriteLine($"Collection {sender} changed: {e.Action}");
};
dictionary.PropertyChanged += (sender, e) =>
{
    Console.WriteLine($"Property changed on {sender}: {e.PropertyName}");
};

Back

Lists

Sets