Dictionaries - .NET SDK
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?>
), or add the
[Required] attribute if the dictionary
contains nullable reference types, such as string
or byte[]
.
Local-only Realm Databases support collections of nullable (optional) values,
but Sync
does not.
The following code shows examples of dictionary types:
public class Inventory : RealmObject { // 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> PlantDict { get; } public IDictionary<string, bool> BooleansDict { get; } // Nullable types are supported in local-only // Realms, but not with Sync public IDictionary<string, int?> NullableIntDict { get; } // For C# types that are implicitly nullable, you can // use the [Required] attribute to prevent storing null values [ ] public IDictionary<string, string> RequiredStringsDict { get; } }
Usage Example
The following code shows how to create, write to, and read from Dictionaries.
You cannot use Linq to query against a Realm Dictionary. Instead, use a string query.
var storeInventory = new Inventory() { Id = ObjectId.GenerateNewId().ToString() }; storeInventory.PlantDict.Add("Petunia", new Plant()); storeInventory.NullableIntDict.Add("random things", 7); storeInventory.RequiredStringsDict.Add("foo", "bar"); var storeInventory2 = new Inventory() { Id = ObjectId.GenerateNewId().ToString() }; storeInventory2.RequiredStringsDict.Add("foo", "Bar"); realm.Write(() => { realm.Add<Inventory>(storeInventory); realm.Add<Inventory>(storeInventory2); }); // Find all Inventory items that have "Petunia" // as a key in their PlantDict. var petunias = realm.All<Inventory>() .Filter("PlantDict.@keys == 'Petunia'"); // Find all Inventory items that have at least one value in their // IntDict that is larger than 5 var matchesMoreThanFive = realm.All<Inventory>() .Filter("NullableIntDict.@values > 5"); // Find all Inventory items where any RequiredStringsDict has a key // "Foo", and the value of that key contains the phrase "bar" // (case insensitive) var matches = realm.All<Inventory>().Filter("RequiredStringsDict['foo'] CONTAINS[c] 'bar'"); // matches.Count() == 2
Data Binding
Like other Realm collections, IDictionary
implements INotifyCollectionChanged
,
so you can use it in data-binding scenarios (for example, when
watching for changes).