10.2.0 - New datatypes and Unity improvements

[nirinchev]

This release adds SDK support for four new datatatypes - Guid, RealmValue, ISet<TValue>, and IDictionary<string, TValue>.

NOTE: This version upgrades the Realm file format version to add support for the new data types and to adjust how primary keys are handled. Realm files opened will be automatically upgraded and cannot be read by versions older than v10.2.0. This upgrade should be a fairly fast one. Note that we now automatically create a backup of the pre-upgrade Realm.

Enhancements

• Add support for the Guid data type. It can be used as primary key and is indexable. (PR #2120)

• Add support for dictionaries. Currently only string keys are supported, while the value type may be any of the supported types (the primitive types, RealmValue, or custom types that inherit from RealmObject/EmbeddedObject). Lists, sets, or other dictionaries may not be used as the value type. To add a dictionary to your model, define a getter-only property of type IDictionary<string, T>:

  public class MyObject : RealmObject
  {
      public IDictionary<string, decimal> Denominations { get; }
  }
  
  // Realm will automatically manage the underlying dictionary, so there's no need
  // to define a constructor  or assign it to some value.
  
  var obj = new MyObject();
  obj.Denominations.Add("quarter", 0.25d);

• Add support for RealmValue data type. This new type can represent any valid Realm data type, including objects. Collections (lists, sets and dictionaries) of RealmValue are also supported, but RealmValue itself cannot contain collections. Please note that a property of type RealmValue cannot be nullable, but can contain null, represented by the value RealmValue.Null. (PR #2252)

  public class MyObject : RealmObject
  {
      public RealmValue MyValue { get; set; }
  
      public IList<RealmValue> ValuesList { get; }
  
      public ISet<RealmValue> ValuesSet { get; }
  
      public IDictionary<string, RealmValue> ValuesDict { get; }
  }
  
  var obj = new MyObject();
  obj.MyValue = RealmValue.Null;
  obj.MyValue = 1;
  obj.MyValue = "abc";
  
  if (obj.MyValue.Type == RealmValueType.String)
  {
      var myString = obj.MyValue.AsString();
  }

• Add support for sets of objects or primitive values. Sets are unordered collections that ensure uniqueness of their elements. Realm uses its internal equality comparer and it is not possible to customize its behavior by overriding Equals or GetHashCode on your custom classes. Objects will always be compared by db reference - i.e. two distinct objects in the database will always be different, even if their contents are identical, and multiple references to the same database object will always be equal.

  public class MyObject : RealmObject
  {
      public ISet<string> UniqueStrings { get; }
  }
  
  // Realm will automatically manage the underlying set, so there's no need
  // to define a constructor  or assign it to some value.
  
  var obj = new MyObject();
  var didAdd = obj.UniqueStrings.Add("foo"); // true
  didAdd = obj.UniqueStrings.Add("foo"); // false

• Added support for value substitution in string based queries. This enables expressions following this syntax: realm.All<T>().Filter("field1 = $0 && field2 = $1", 123, "some-string-value"). (Issue #1822)

• Reduced the size of the native binaries by ~5%. (PR #2239)

• Added a new class - Logger, which allows you to override the default logger implementation (previously writing to stdout or stderr) with a custom one by setting Logger.Default. This replaces AppConfiguration.CustomLogger and AppConfiguration.LogLevel which will be removed in a future release. The built-in implementations are:

  • Console - uses the System.Console for most projects and UnityEngine.Debug for Unity projects: Logger.Default = Logger.Console;
  • Null - ignores all messages: Logger.Default = Logger.Null;
  • Function - proxies calls to a supplied function: Logger.Default = Logger.Function(message => myExternalLogger.Log(message));

  Custom loggers can derive from the Logger class and provide their own implementation for the Log method or use Function and provide an Action<string>. (PR #2276)

• RealmObjectBase now correctly overrides and implements GetHashCode(). (Issue #1650)

• Added an override of RealmObject.ToString() to output more meaningful information about the object content. It will output the type of the object, the primary key (if one is defined), as well as information whether the object is managed or deleted. (Issue #2347)

• Added new API for dynamically accessing object properties. These are designed to support ahead-of-time compiled platforms, such as Xamarin.iOS and Unity with IL2CPP compilation. The
  intention is to eventually make these the default API, while also supporting the legacy DLR-based API. Example:

  // Make sure to cast away the dynamic immediately on AOT platforms.
  var people = (IQueryable<RealmObject>)realm.DynamicApi.All("Person");
  foreach (var person in people)
  {
      var firstName = person.DynamicApi.Get<string>("FirstName");
      var address = person.DynamicApi.Get<EmbeddedObject>("Address");
      var city = address.DynamicApi.Get<string>("City");
  }
  
  // When casting a dynamic object, always cast first to object and then
  // to the actual object type to remove any callsites being generated.
  var newPerson = (RealmObject)(object)realm.DynamicApi.Create("Person", 123);
  newPerson.DynamicApi.Set("FirstName", "Peter");

• Added a Unity Editor option to enable weaving editor assemblies. This should be "off" unless your project has Editor assemblies that reference Realm - for example, an EditMode test assembly that tests Realm-related functionality. Keeping it "on" may slow down builds a little as more assemblies will need to be evaluated for weaving. (Issue #2346)

• We now make a backup of the realm file prior to any file format upgrade. The backup is retained for 3 months. Backups from before a file format upgrade allows for better analysis of any upgrade failure. We also restore a backup, if a) an attempt is made to open a realm file whith a "future" file format and b) a backup file exist that fits the current file format. (#4166)

Fixed

• Fixed a bug where applying multiple OrderBy clauses on a query would result in the clauses being appended to each other as if they were .ThenBy rather than the last clause replacing the preceding ones. (PR #2255)
• When explicitly specifying SyncConfiguration.ObjectTypes, added a check to validate the schema and ensure all EmbeddedObject classes are reachable from a class inheriting from RealmObject. More info about this subject can be found here. (PR #2259)
• Fixed a bug that would result in an error similar to Undefined symbols for architecture xxx: "_realm_thread_safe_reference_destroy" when building a Unity project for iOS. (Issue #2318)
• The weaver will now emit an error if you try to define a collection of RealmInteger values. This has never been supported, but previously it would fail silently whereas now it'll be a compile time error. (Issue #2308)
• Fixed an issue where using collections of managed objects (lists or results) in a Unity project would result in an invalid compiled binary. (PR #2340)
• Fixed a memory leak when a migration callback is defined, but the Realm didn't actually need to run it (PR #2331)
• Added back 32bit support for iOS builds. (Issue #2429)
• Removed redundant warnings when building a Unity project for device that mentioned that the schema for Realm and Realm.UnityUtils is empty. (Issue #2320)
• Fixed an issue that could cause NullReferenceException to be thrown if you set SyncConfiguration.OnProgress to null shortly after calling Realm.GetInstanceAsync(syncConfig). (Issue #2400)
• When replacing an embedded object, emit a sync instruction that sets the link to the embedded object to null so that it is properly cleared. This resolves an issue that would have manifested itself as Failed to parse, or apply received changeset: ERROR: ArrayInsert: Invalid prior_size (list size = 4, prior_size = 0) (Issue #4740
• Made Linux implementation of ExternalCommitHelper work with new versions of Linux that changed epoll behavior, including Android 12 (Issue #4666)
• The file format is changed in the way that we now - again - have search indexes on primary key columns. This is required as we now stop deriving the ObjKeys from the primary key values, but just use an increasing counter value. This has the effect that all new objects will be created in the same cluster and not be spread out as they would have been before. It also means that upgrading from file format version 11 and earlier formats will be much faster. (Core upgrade)

Compatibility

• Realm Studio: 11.0.0-alpha.0 or later.

Unity support

The Unity packages are very early previews and are considered unstable. We do not recommend using them in production because issues are expected.

---

This discussion was created from the release 10.2.0 - New datatypes and Unity improvements.