12.1.0

12.1.0 (2024-05-01)

Enhancements

• Added an experimental API to update the base url for an application at runtime - App.UpdateBaseUriAsync(). This intended to be used for roaming between edge server and cloud. (Issue #3521)

Fixed

• The returned value from MongoClient.Collection.FindOneAsync is now a nullable document to more explicitly convey that null may be returned in case no object matched the filter. (PR #3586)
• Fixed crash when integrating removal of already removed dictionary key. (Core 14.5.2)
• App.AllUsers included logged out users only if they were logged out while the App instance existed. It now always includes all logged out users. (Core 14.6.0)
• Fixed several issues around encrypted file portability (copying a "bundled" encrypted Realm from one device to another): (Core 14.6.0)
  • Fixed Assertion failed: new_size % (1ULL << m_page_shift) == 0 when opening an encrypted Realm less than 64Mb that was generated on a platform with a different page size than the current platform.
  • Fixed a DecryptionFailed exception thrown when opening a small (<4k of data) Realm generated on a device with a page size of 4k if it was bundled and opened on a device with a larger page size.
  • Fixed an issue during a subsequent open of an encrypted Realm for some rare allocation patterns when the top ref was within ~50 bytes of the end of a page. This could manifest as a DecryptionFailed exception or as an assertion: encrypted_file_mapping.hpp:183: Assertion failed: local_ndx < m_page_state.size().
• Schema initialization could hit an assertion failure if the sync client applied a downloaded changeset while the Realm file was in the process of being opened. (Core 14.6.0)
• Improve perfomance of "chained OR equality" queries for UUID/ObjectId types and RQL parsed "IN" queries on string/int/uuid/objectid types. (Core 14.6.0)
• Fixed a bug when running a IN query (or a query of the pattern x == 1 OR x == 2 OR x == 3) when evaluating on a string property with an empty string in the search condition. Matches with an empty string would have been evaluated as if searching for a null string instead. (Core 14.6.1)

Compatibility

• Realm Studio: 15.0.0 or later.

Internal

• Using Core 14.6.1.

12.0.0

12.0.0 (2024-04-17)

File format version bumped. Old files will be automatically upgraded but cannot be downgraded and opened with older versions of the .NET SDK.

Breaking Changes

• Added automatic serialization and deserialization of Realm classes when using methods on MongoClient.Collection, without the need to annotate classes with MongoDB.Bsonattributes. This feature required to change the default serialization for various types (including DateTimeOffset). If you prefer to use the previous serialization, you need to call Realm.SetLegacySerialization before any kind of serialization is done, otherwise it may not work as epxected. #3459
• SyncProgress.TransferredBytes and SyncProgress.TransferableBytes have been removed in favour of SyncProgress.ProgressEstimate, a double value between 0.0 and 1.0 that expresses the percentage estimate of the current progress. (Issue #3478)
• Support for upgrading from Realm files produced by RealmCore v5.23.9 (Realm .NET v5.0.1) or earlier is no longer supported. (Core 14.0.0)
• String and byte[] are now strongly typed for comparisons and queries. This change is especially relevant when querying for a string constant on a RealmValue property, as now only strings will be returned. If searching for binary data is desired, then that type must be specified by the constant. In RQL (.Filter()) the new way to specify a binary constant is to use RealmValueProp = bin('xyz') or RealmValueProp = binary('xyz'). (Core 14.0.0)
• Sorting order of strings has changed to use standard unicode codepoint order instead of grouping similar english letters together. A noticeable change will be from "aAbBzZ" to "ABZabz". (Core 14.0.0)
• In RQL (Filter()), if you want to query using @type operation, you must use objectlink to match links to objects. object is reserved for dictionary types. (Core 14.0.0)
• Opening realm with file format 23 or lower (Realm .NET versions earlier than 12.0.0) in read-only mode will crash. (Core 14.0.0)

Enhancements

• Reduced memory usage of RealmValue. (PR #3441)

• Add support for passing a key paths collection (KeyPathsCollection) when using IRealmCollection.SubscribeForNotifications. Passing a KeyPathsCollection allows to specify which changes in properties should raise a notification.

  A KeyPathsCollection can be obtained by:

  • building it explicitly by using the methods KeyPathsCollection.Of or KeyPathsCollection.Of<T>;
  • building it implicitly with the conversion from a List or array of KeyPath or strings;
  • getting one of the static values Full and Shallow for full and shallow notifications respectively.

  A KeyPath can be obtained by implicit conversion from a string or built from an expression using the KeyPath.ForExpression<T> method.

  For example:

  var query = realm.All<Person>();
  
  KeyPath kp1 = "Email";
  KeyPath kp2 = KeyPath.ForExpression<Person>(p => p.Name);
  
  KeyPathsCollection kpc;
  
  //Equivalent declarations
  kpc = KeyPathsCollection.Of("Email", "Name");
  kpc = KeyPathsCollection.Of<Person>(p => p.Email, p => p.Name);
  kpc = new List<KeyPath> {"Email", "Name"};
  kpc = new List<KeyPath> {kp1, kp2};
  
  query.SubscribeForNotifications(NotificationCallback, kpc);

  (PR #3501 )

• Added the MongoClient.GetCollection<T> method to get a collection of documents from MongoDB that can be deserialized in Realm objects. This methods works the same as MongoClient.GetDatabase(dbName).GetCollection(collectionName), but the database name and collection name are automatically derived from the Realm object class. #3414

• Improved performance of RQL (.Filter()) queries on a non-linked string property using: >, >=, <, <=, operators and fixed behaviour that a null string should be evaulated as less than everything, previously nulls were not matched. (Core 13.27.0)

• Updated bundled OpenSSL version to 3.2.0. (Core 13.27.0)

• Storage of Decimal128 properties has been optimised so that the individual values will take up 0 bits (if all nulls), 32 bits, 64 bits or 128 bits depending on what is needed. (Core 14.0.0)

• Add support for collection indexes in RQL (Filter()) queries.
  For example:

  var people = realm.All<Person>();
  
  //People whose first dog is called "Fluffy"
  var query1 = people.Filter("ListOfDogs[FIRST].Name = $0", "Fluffy")
  
  //People whose last dog is called "Fluffy"
  var query2 = people.Filter("ListOfDogs[LAST].Name = $0", "Fluffy")
  
  //People whose second dog is called "Fluffy"
  var query3 = people.Filter("ListOfDogs[2].Name = $0", "Fluffy")
  
  //People that have a dog called "Fluffy"
  var query4 = people.Filter("ListOfDogs[*].Name = $0", "Fluffy")
  
  //People that have 3 dogs
  var query5 = people.Filter("ListOfDogs[SIZE] = $0", 3)

  (Core 14.0.0)

• Added support for indexed RealmValue properties. (PR #3544)

• Improve performance of object notifiers with complex schemas and very simple changes to process by as much as 20%. (Core 14.2.0)

• Improve performance with very large number of notifiers as much as 75%. (Core 14.2.0)

• Improve file compaction performance on platforms with page sizes greater than 4k (for example arm64 Apple platforms) for files less than 256 pages in size. (Core 14.4.0)

• The default base url in AppConfiguration has been updated to point to services.cloud.mongodb.com. See https://www.mongodb.com/docs/atlas/app-services/domain-migration/ for more information. (Issue #3551)

Fixed

• Fixed RQL (.Filter()) queries like indexed_property == NONE {x} which mistakenly matched on only x instead of not x. This only applies when an indexed property with equality (==, or IN) matches with NONE on a list of one item. If the constant list contained more than one value then it was working correctly. (Core 13.27.0)
• Uploading the changesets recovered during an automatic client reset recovery may lead to 'Bad server version' errors and a new client reset. (Core 13.27.0)
• Fixed crash in fulltext index using prefix search with no matches. (Core 13.27.0)
• Fixed a crash with Assertion failed: m_initiated during sync session startup. (Core 13.27.0)
• Fixed a TSAN violation where the user thread could race to read m_finalized with the sync event loop. (Core 13.27.0)
• Fix a minor race condition when backing up Realm files before a client reset which could have lead to overwriting an existing file. (Core 13.27.0)
• Boolean property ChangeSet.IsCleared that is true when the collection gets cleared is now also raised for IDictionary, aligning it to ISet and IList. (Core 14.0.0)
• Fixed equality queries on RealmValue properties with an index. (Core 14.0.0)
• Fixed a crash that would happen when more than 8388606 links were pointing to a specific object.
• Fixed wrong results when querying for NULL value in IDictionary. (Core 14.0.0)
• A Realm generated on a non-apple ARM 64 device and copied to another platform (and vice-versa) were non-portable due to a sorting order difference. This impacts strings or binaries that have their first difference at a non-ascii character. These items may not be found in a set, or in an indexed column if the strings had a long common prefix (> 200 characters). (Core 14.0.0)
• Fixed an issue when removing items from a LnkLst that could result in invalidated links becoming visable which could cause crashes or exceptions when accessing those list items later on. This affects sync Realms where another client had previously removed a link in a linklist that has over 1000 links in it, and then further local removals from the same list caused the list to have fewer than 1000 items. (Core 14.2.0)
• Fix a spurious crash related to opening a Realm on background thread while the process was in the middle of exiting. (Core 14.3.0)
• Fix opening realm with cached user while offline results in fatal error and session does not retry connection. (Core 14.4.0)
• Fix an assertion failure "m_lock_info && m_lock_info->m_file.get_path() == m_filename" that appears to be related to opening a Realm while the file is in the process of being closed on another thread. (Core 14.5.0)
• Fixed diverging history due to a bug in the replication code when setting default null values (embedded objects included). (Core 14.5.0)
• Null pointer exception may be triggered when logging out and async commits callbacks not executed. (Core 14.5.0)

Compatibility

• Realm Studio: 15.0.0 or later.

Internal

• Using Core 14.5.1.

11.7.0

11.7.0 (2024-02-05)

Enhancements

• Automatic client reset recovery now does a better job of recovering changes when changesets were downloaded from the server after the unuploaded local changes were committed. If the local Realm happened to be fully up to date with the server prior to the client reset, automatic recovery should now always produce exactly the same state as if no client reset was involved. (Core 13.24.1)
• Exceptions thrown during bootstrap application will now be surfaced to the user rather than terminating the program with an unhandled exception. (Core 13.25.0)
• Allow the using >, >=, <, <= operators in Realm.Filter() queries for string constants. This is a case sensitive lexicographical comparison. Improved performance of RQL (.Filter()) queries on a non-linked string property using: >, >=, <, <=, operators and fixed behaviour that a null string should be evaluated as less than everything, previously nulls were not matched. (Core 13.26.0-14-gdf25f)

Fixed

• Automatic client reset recovery would duplicate insertions in a list when recovering a write which made an unrecoverable change to a list (i.e. modifying or deleting a pre-existing entry), followed by a subscription change, followed by a write which added an entry to the list. (Core 13.24.0)
• During a client reset recovery a Set of links could be missing items, or an exception could be thrown that prevents recovery. (Core 13.24.0)
• During a client reset with recovery when recovering a move or set operation on a IList<RealmObject> or IList<RealmValue> that operated on indices that were not also added in the recovery, links to an object which had been deleted by another client while offline would be recreated by the recovering client. But the objects of these links would only have the primary key populated and all other fields would be default values. Now, instead of creating these zombie objects, the lists being recovered skip such deleted links. (Core 13.24.0)
• Errors encountered while reapplying local changes for client reset recovery on partition-based sync Realms would result in the client reset attempt not being recorded, possibly resulting in an endless loop of attempting and failing to automatically recover the client reset. (Core 13.24.0)
• Changesets have wrong timestamps if the local clock lags behind 2015-01-01T00:00:00Z. The sync client now throws an exception if that happens. (Core 13.24.1)
• If the very first open of a flexible sync Realm triggered a client reset, the configuration had an initial subscriptions callback, both before and after reset callbacks, and the initial subscription callback began a read transaction without ending it (which is normally going to be the case), opening the frozen Realm for the after reset callback would trigger a BadVersion exception. (Core 13.24.1)
• Automatic client reset recovery on flexible sync Realms would apply recovered changes in multiple write transactions, releasing the write lock in between. (Core 13.24.1)
• Having a class name of length 57 would make client reset crash as a limit of 56 was wrongly enforced. (Core 13.24.1)
• Fixed several causes of "decryption failed" exceptions that could happen when opening multiple encrypted Realm files in the same process while using Apple/linux and storing the Realms on an exFAT file system. (Core 13.24.1)
• Fixed several errors that could cause a crash of the sync client. (Core 13.25.0)
• Bad performance of initial Sync download involving many backlinks. (Core 13.25.1)
• Explicitly bumped the minimum version of System.Net.Security to 4.3.2 as 4.3.0 has been marked as vulnerable (more details can be found in the deprecation notice on the NuGet page).
• Handle EOPNOTSUPP when using posix_fallocate() and fallback to manually consume space. This should enable android users to open a Realm on restrictive filesystems. (Core 13.26.0)
• Application may crash with incoming_changesets.size() != 0 when a download message is mistaken for a bootstrap message. This can happen if the synchronization session is paused and resumed at a specific time. (Core 13.26.0)
• Fixed errors complaining about missing symbols such as __atomic_is_lock_free on ARMv7 Linux (Core 13.26.0)
• Uploading the changesets recovered during an automatic client reset recovery may lead to 'Bad server version' errors and a new client reset. (Core 13.26.0-14-gdf25f)
• Fixed invalid data in error reason string when registering a subscription change notification after the subscription has already failed. (Core 13.26.0-14-gdf25f)

Compatibility

• Realm Studio: 13.0.0 or later.

Internal

• Using Core v13.26.0-14-gdf25f.

11.6.1

11.6.1 (2023-11-17)

Fixed

• Fixed FLX subscriptions not being sent to the server if the session was interrupted during bootstrapping. (Core 13.23.3)
• Fixed FLX subscriptions not being sent to the server if an upload message was sent immediately after a subscription was committed but before the sync client checks for new subscriptions. (Core 13.23.3)
• Fixed application crash with 'KeyNotFound' exception when subscriptions are marked complete after a client reset. (Core 13.23.3)
• A crash at a very specific time during a DiscardLocal client reset on a FLX Realm could leave subscriptions in an invalid state. (Core 13.23.4)
• Fixed an error "Invalid schema change (UPLOAD): cannot process AddColumn instruction for non-existent table" when using automatic client reset with recovery in dev mode to recover schema changes made locally while offline. (Core 13.23.4)

Compatibility

• Realm Studio: 13.0.0 or later.

Internal

• Using Core 13.23.4.

11.6.0

11.6.0 (2023-11-03)

Enhancements

• Added the App.EmailPasswordAuth.RetryCustomConfirmationAsync method to be able to run again the confirmation function on the server for a given email. (Issue #3463)

• Added User.Changed event that can be used to notify subscribers that something about the user changed - typically this would be the user state or the access token. (Issue #3429)

• Added support for customizing the ignore attribute applied on certain generated properties of Realm models. The configuration option is called realm.custom_ignore_attribute and can be set in a global configuration file (more information about global configuration files can be found in the .NET documentation). The Realm generator will treat this as an opaque string, that will be appended to the IgnoreDataMember and XmlIgnore attributes already applied on these members. The attributes must be fully qualified unless the namespace they reside in is added to a global usings file. For example, this is how you would add JsonIgnore from System.Text.Json:

  realm.custom_ignore_attribute = [System.Text.Json.Serialization.JsonIgnore]
  

  (Issue #2579)

• The Realm source generator will now error out in case a collection in the model classes is assigned to a non-null value either in a property initializer or in a constructor. Realm collections are initialized internally and assigning non-null values to the property is not supported, where the null! assignment is only useful to silence nullable reference type warnings, in reality the collection will never be null. (Issue #3455)

• Made WebSocket error logging more verbose when using AppConfiguration.UseManagedWebSockets = true. #3459

Fixed

• Added an error that is raised when interface based Realm classes are used with a language version lower than 8.0. At the same time, removed the use of not in the generated code, so that it's compatible with a minumum C# version of 8.0. (Issue #3265)
• Logging into a single user using multiple auth providers created a separate SyncUser per auth provider. This mostly worked, but had some quirks:
  • Sync sessions would not necessarily be associated with the specific SyncUser used to create them. As a result, querying a user for its sessions could give incorrect results, and logging one user out could close the wrong sessions.
  • Existing local synchronized Realm files created using version of Realm from August - November 2020 would sometimes not be opened correctly and would instead be redownloaded.
  • Removing one of the SyncUsers would delete all local Realm files for all SyncUsers for that user.
  • Deleting the server-side user via one of the SyncUsers left the other SyncUsers in an invalid state.
  • A SyncUser which was originally created via anonymous login and then linked to an identity would still be treated as an anonymous users and removed entirely on logout.
    (Core 13.21.0)
• If a user was logged out while an access token refresh was in progress, the refresh completing would mark the user as logged in again and the user would be in an inconsistent state (Core 13.21.0).
• If querying over a geospatial dataset that had some objects with a type property set to something other than 'Point' (case insensitive) an exception would have been thrown. Instead of disrupting the query, those objects are now just ignored. (Core 13.21.0)
• Receiving a write_not_allowed error from the server would have led to a crash. (Core 13.22.0)
• Updating subscriptions did not trigger Realm autorefreshes, sometimes resulting in async refresh hanging until another write was performed by something else. (Core 13.23.1)
• Fix interprocess locking for concurrent realm file access resulting in a interprocess deadlock on FAT32/exFAT filesystems. (Core 13.23.1)

Compatibility

• Realm Studio: 13.0.0 or later.

Internal

• Using Core 13.20.1.

11.5.0

11.5.0 (2023-09-15)

Enhancements

• Streamlined some of the error codes reported in SessionException. A few error codes have been combined and some have been deprecated since they are no longer reported by the server. (Issue #3295)

Fixed

• Fixed the message of the MissingMemberException being thrown when attempting to access a non-existent property with the dynamic API. (PR #3432)
• Fixed a Cannot marshal generic Windows Runtime types with a non Windows Runtime type as a generic type argument build error when using .NET Native. (Issue #3434, since 11.4.0)

Compatibility

• Realm Studio: 13.0.0 or later.

Internal

• Using Core x.y.z.

11.4.0

11.4.0 (2023-08-16)

Enhancements

• Added IQueryable.SubscribeAsync API as a shorthand for using SubscriptionSet.Add. It is a syntax sugar that roughly translates to:

  realm.Subscriptions.Update(() =>
  {
    realm.Subscriptions.Add(query);
  });
  
  await realm.Subscriptions.WaitForSynchronization();
  
  // This can now be expressed as
  await query.SubscribeAsync();

  It offers a parameter to control whether to wait every time for synchronization or just the first time a subscription is added, as well as cancellation token support. (PR #3403)
• Added an optional cancellationToken argument to Session.WaitForDownloadAsync/WaitForUploadAsync. (PR #3403)
• Added an optional cancellationToken argument to SubscriptionSet.WaitForSynchronization. (PR #3403)
• Fixed a rare corruption of files on streaming format (often following compact, convert or copying to a new file). (Core 13.17.1)
• Trying to search a full-text indexes created as a result of an additive schema change (i.e. applying the differences between the local schema and a synchronized realm's schema) could have resulted in an IllegalOperation error with the error code Column has no fulltext index. (Core 13.17.1)
• Sync progress for DOWNLOAD messages from server state was updated wrongly. This may have resulted in an extra round-trip to the server. (Core 13.17.1)
• Added option to use managed WebSockets (System.Net.WebSockets.ClientWebSocket) instead of Realm's built-in WebSocket client for Sync traffic. Managed WebSockets offer improved support for proxies and firewalls that require authentication. This feature is currently opt-in and can be enabled by setting AppConfiguration.UseManagedWebSockets to true. Managed WebSockets will become the default in a future version. (PR #3412).
• Fixed an issue that would make realm.SyncSession garbage collected even when there are subscribers to realm.SyncSession.PropertyChanged.

Fixed

• Fixed a race condition between canceling an async write transaction and closing the Realm file, which could result in an ObjectDisposedException : Safe handle has been closed being thrown. (PR #3400)
• Fixed an issue where in the extremely rare case that an exception is thrown by Realm.RefreshAsync, that exception would have been ignored and false would have been returned. (PR #3400)
• Fixed the nullability annotation of SubscriptionSet.Find to correctly indicate that null is returned if the subscription doesn't exist in the subscription set. (PR #3403)
• Fixed an issue where executing Filter queries using remapped properties would only work with the native name rather than the managed one. Now both will work - e.g.:

  partial class MyModel : IRealmObject
  {
    [MapTo("Bar")]
    public int Foo { get; set; }
  }
  
  // Both of these are valid now
  realm.All<MyModel>().Filter("Foo > 5");
  realm.All<MyModel>().Filter("Bar > 5");

  (Issue #3149)

Compatibility

• Realm Studio: 13.0.0 or later.

Internal

• Using Core 13.17.1

11.3.0

11.3.0 (2023-07-26)

Breaking Changes

• AppConfiguration.LocalAppName and AppConfiguration.LocalAppVersion have been deprecated and will be removed in a future version. They have never had an effect as the values supplied by the SDK was never sent to the server. (PR #3387)

Enhancements

• Added App.BaseFilePath, App.BaseUri, and App.Id properties that return the values supplied in AppConfiguration. (PR #3385)
• Added AppConfiguration.UseAppCache property that controls whether the App instance returned from App.Create should be cached or not. The general recommendation is to not set it (i.e. leave the default value of true), but it can be useful when writing unit tests. (Issue #3382).

Fixed

• Fixed a Unity Editor crash when the domain is reloaded while a Realm.GetInstanceAsync operation is in progress. (Issue #3344)
• Fixed the implementation App.Equals and App.GetHashCode to return correct results, particularly when the App instance is cached. (PR #3385)
• Fixed an issue where building for Android on Unity would fail with "Could not analyze the user's assembly. Object reference not set to an instance of an object". (Issue #3380)
• A GeoBox is now just a shortcut for the equivilent GeoPolygon. This provides consistent query results and error checking. (Core 13.15.2)
• Fixed several corner cases (eg. around the poles) where invalid points matched a geoWithin query. (Core 13.15.2)
• Fixed an error during async open and client reset if properties have been added to the schema. This fix applies to PBS to FLX migration if async open is used. (Core 13.16.1)

Compatibility

• Realm Studio: 13.0.0 or later.

Internal

• Using Core 13.17.0

11.2.0

11.2.0 (2023-07-07)

Enhancements

• Added validation checks to the geospatial type constructors. This means that an exception will now be thrown when constructing an invalid geospatial shape rather than when using it in a query. (PR #3362)
• Relaxed some validations when invoking IndexOf(null) on a collection of non-nullable types. Previously, this would throw an ArgumentNullException whereas now it will return -1. This is particularly useful for data-binding scenarios where the binding engine might invoke it as IndexOf(SelectedItem) which would throw an exception when SelectedItem is null. (PR #3369)
• Changed RealmSet.IndexOf implementation to return the actual result rather than throw a NotSupportedException. The order of persisted sets is still non-deterministic, but is stable between write transactions. Again, this is mostly useful for data-binding scenarios where the set is passed as a binding context to a collection control. (PR #3369)

Fixed

• Fixed an issue on Unity on Windows when the weaver would trigger excessive terminal windows to open. (Issue #3364
• Fixed an issue on Unity on CI where weaving would fail with the following error: Could not analyze the user's assembly. Cannot access a closed Stream.. (Issue #3364
• Fixed a NullReferenceException when weaving classes on Unity in batch mode. (Issue #3363)

Compatibility

• Realm Studio: 13.0.0 or later.

Internal

• Using Core 13.15.0

11.1.2

11.1.2 (2023-06-20)

Fixed

• Fixed a namespacing issue that would cause Maui Android projects to fail to build due to 'Realm' is a namespace but is used like a type. (Issue #3351)

Compatibility

• Realm Studio: 13.0.0 or later.

Internal

• Using Core 13.15.0