Realm .NET SDK

A Realm set is an implementation of ISet<TValue>, ICollection<TValue>, and IEnumerable<TValue>. It functions similarly to a C# HashSet<T>.

Key Rules:

• Supported Types: You can use any Realm-supported type except for other collections.
• Declaration: Define a set using a getter-only ISet<TValue> property.
• Nullability:
  • Objects: Deleting an object from the database automatically removes it from any sets. Therefore, a set of objects will never contain null objects.
  • Primitives: Sets of primitive types can contain null values if using nullable types (e.g., ISet<double?>). To disallow nulls, use non-nullable types (e.g., ISet<double>).
  • Required Attribute: If using the older RealmObject base class or if nullability is not enabled, use the [Required] attribute for sets containing nullable reference types like string or byte[] to ensure they are not null.

public partial class Inventory : IRealmObject
{
    // A Set can contain any Realm-supported type, including
    // objects that inherit from RealmObject
    public ISet<Plant> PlantSet { get; }

    public ISet<double> DoubleSet { get; }

    public ISet<int?> NullableIntsSet { get; }

    public ISet<string> RequiredStrings { get; }
}

The Realm .NET SDK uses C# nullability annotations (?) to determine if a property is required or optional.

• Required Properties: Properties that are not marked as nullable (e.g., int, string, byte[]) are treated as required by Realm.
• Optional Properties: Properties marked with ? (e.g., int?, string?) are treated as optional.

Rules for Realm Object Types

• Realm Objects: Properties that are other Realm object types must be declared as nullable (e.g., public Dog? MyDog { get; set; }).
• Collections: You cannot declare collections (like IList, ISet, IDictionary, or IQueryable backlinks) as nullable themselves. However, the types inside the collections follow specific rules:
  • Primitives: Can be required or nullable (e.g., IList<int> or IList<int?>).
  • Realm Objects in Lists/Sets/Backlinks: The parameter type cannot be nullable (e.g., IList<Dog> is valid, but IList<Dog?> is a compile-time error).
  • Realm Objects in Dictionaries: If the dictionary value is a Realm object, you must declare the value type parameter as nullable (e.g., IDictionary<string, Dog?>).

Legacy/Non-Nullable Contexts

If you are using the older RealmObject base class or have nullability disabled in your project, you must use the [Required] attribute to mark string and byte[] properties as required.

#nullable enable
public partial class Person : IRealmObject
{
    /* Reference Types */
    public string NonNullableName { get; set; } // Required
    public string? NullableName { get; set; }    // Optional

    /* Value Types */
    public int NonNullableInt { get; set; }      // Required
    public int? NullableInt { get; set; }        // Optional

    /* Realm Objects */
    public Dog? NullableDog { get; set; }        // Must be nullable

    /* Collections of Primitives */
    public IList<int> IntListWithNonNullableValues { get; }
    public IList<int?> IntListWithNullableValues { get; }

    /* Collections of Realm Objects */
    public IList<Dog> ListOfNonNullableObjects { get; } // Valid
    // public IList<Dog?> ListOfNullableObjects { get; } // Compile-time error

    public IDictionary<string, Dog?> DictionaryOfNullableObjects { get; } // Must be nullable for Realm objects

    [Backlink(nameof(Dog.Person))]
    public IQueryable<Dog> MyDogs { get; }
}

A Realm dictionary is an implementation of IDictionary<string, TValue> where the key must be a string. The value TValue can be any Realm-supported type except for collections.

To define a dictionary in your model, use a getter-only IDictionary<string, TValue> property.

Key Constraints:

• Keys must be of type string.
• Realm disallows the use of . or $ characters in map keys. If you need to use these characters, you must use percent encoding/decoding to store them.

Nullability:

• Dictionaries of objects can contain null objects.
• Dictionaries of primitive types can contain null values if using nullable types (e.g., IDictionary<string, double?>).
• To disallow null values, use non-nullable types (e.g., IDictionary<string, double>).
• If you are using the older RealmObject base class or do not have nullability enabled, use the [Required] attribute for nullable reference types like string or byte[] to ensure they are treated as required.

public partial class Inventory : IRealmObject
{
    [PrimaryKey]
    [MapTo("_id")]
    public string Id { get; set; }
    
    // Value can be objects inheriting from RealmObject or EmbeddedObject
    public IDictionary<string, Plant?> Plants { get; }

    public IDictionary<string, bool> BooleansDictionary { get; }

    public IDictionary<string, int?> NullableIntDictionary { get; }

    public IDictionary<string, string> RequiredStringsDictionary { get; }
}