Releases: realm/realm-dotnet
10.20.0
10.20.0 (2023-02-10)
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
User.GetPushClient
has been deprecated as it will be disabled soon on the server. (Issue #3073)
Enhancements
-
The realm file will be shrunk if the larger file size is no longer needed. (Core 13.0.0)
-
Most of the file growth caused by version pinning is eliminated. (Core 13.0.0)
-
Improve performance of acquiring read locks when a read lock for that version is already held. This speeds up many operations related to change notifications, and particularly refreshing a Realm which has change notifiers registered. (Core 13.2.0)
-
Upgrade OpenSSL from 1.1.1n to 3.0.7. (Core 13.2.0)
-
Converting flexible sync realms to bundled and local realms is now supported (Core 13.2.0)
-
Add support for nested classes for source generated classes. (Issue #3031)
-
Enhanced support for nullable reference types in the model definition for source generated classes. This allows to use realm models as usual when nullable context is active, and removes the need to use of the
Required
attribute to indicate required properties, as this information will be inferred directly from the nullability status. There are some considerations regarding the nullability of properties that link to realm object:- Properties that link to a single realm object are inherently nullable, and thus the type must be defined as nullable.
- List, Sets and Backlinks cannot contain null objects, and thus the type parameter must be non-nullable.
- Dictionaries can contain null values, and thus the type parameter must be nullable.
Defining the properties with a different nullability annotation than what has been outlined here will raise a diagnostic error. For instance:
public partial class Person: IRealmObject { //Single values public Dog? MyDog { get; set; } //Correct public Dog MyDog { get; set; } //Error //List public IList<Dog> MyDogs { get; } //Correct public IList<Dog?> MyDogs { get; } //Error //Set public ISet<Dog> MyDogs { get; } //Correct public ISet<Dog?> MyDogs { get; } //Error //Dictionary public IDictionary<string, Dog?> MyDogs { get; } //Correct public IDictionary<string, Dog> MyDogs { get; } //Error //Backlink [Realms.Backlink("...")] public IQueryable<Dog> MyDogs { get; } //Correct [Realms.Backlink("...")] public IQueryable<Dog?> MyDogs { get; } //Error }
We realise that some developers would still prefer to have more freedom in the nullability annotation of such properties, and it is possible to do so by setting
realm.ignore_objects_nullability = true
in a global configuration file (more information about global configuration files can be found in the .NET documentation). If this is enabled, all the previous properties will be considered valid, and the nullability annotations for properties linking to objects will be ignored. -
Improved performance of
PropertyChanged
andCollectionChanged
notifications. (Issue #3112) -
Added support for tvOS in Xamarin/MAUI and Unity applications. (Issue #3161)
-
Improve the performance of
Realm.Freeze()
. (Core 13.3.0)
Fixed
ISet<RealmValue>
consider string and binary data equivalent. This could cause the client to be inconsistent with the server if a string and some binary data with equivalent content was inserted from Atlas. (Core 13.0.0)- Fixed wrong assertion on query error that could result in a crash. (Core 13.1.0)
- Fixed an issue preventing opening an encrypted file on a device with a page size bigger than the one on which the file was produced. (Core 13.1.1)
- Fixed possible segfault in sync client where async callback was using object after being deallocated (Core 13.2.0)
- Fixed crash when using client reset with recovery and flexible sync with a single subscription (Core 13.2.0)
- Added a more descriptive error message when a model's property is unsupported. It'll now suggest that the target type may need to inherit from
RealmObject
. (Issue #3162) - Disposing a Realm instance while an active transaction is running will now correctly roll back the transaction. (Issue #2924)
- Fixed an issue that would cause
PropertyChanged
notifications to be delivered for collection properties when the content of the collection was modified even if the collection itself was not replaced. (Issue #3112) - Fixed an issue where weaving assemblies on Unity could result in
System.InvalidOperationException
. (Issue #3199) Session.Stop
will now correctly keep the session stopped untilSession.Start
is called. Previously, there were a number of circumstances that could cause the session to be resumed, even if not explicitly requested. (Core 13.3.0)- When client reset with recovery is used and the recovery does not actually result in any new local commits, the sync client may have gotten stuck in a cycle with a A fatal error occured during client reset: 'A previous 'Recovery' mode reset from did not succeed, giving up on 'Recovery' mode to prevent a cycle' error message. (Core 13.3.0)
- Fixed diverging history in flexible sync if writes occur during bootstrap to objects that just came into view. (Core 13.3.0)
- Fix several data races when opening cached frozen Realms. New frozen Realms were added to the cache and the lock released before they were fully initialized, resulting in races if they were immediately read from the cache on another thread. (Core 13.3.0)
- If a client reset w/recovery or discard local is interrupted while the "fresh" realm is being downloaded, the sync client may crash with a MultpleSyncAgents exception. (Core 13.3.0)
- Changesets from the server sent during FLX bootstrapping that are larger than 16MB can cause the sync client to crash with a LogicError. (Core 13.3.0)
- Sharing Realm files between a Catalyst app and Realm Studio did not properly synchronize access to the Realm file. (Core 13.4.0)
Compatibility
- Realm Studio: 13.0.0 or later.
Internal
10.19.0
10.19.0 (2023-01-06)
Enhancements
-
Removed redundant serialization/deserialization of arguments in CallAsync. (Issue #3079)
-
Added a field
Transaction.State
which describes the current state of the transaction. (Issue #2551) -
Improved error message when null is passed as argument to params for EmailPasswordAuth.CallResetPasswordFunctionAsync. (Issue #3011)
-
Removed backing fields of generated classes' properties which should provide minor improvements to memory used by Realm Objects (Issue #2647)
-
Added two extension methods on
IDictionary
to get anIQueryable
collection wrapping the dictionary's values:dictionary.AsRealmQueryable()
allows you to get aIQueryable<T>
fromIDictionary<string, T>
that can be then treated as a regular queryable collection and filtered/ordered with LINQ orFilter(string)
.dictionary.Filter(query, arguments)
will filter the list and return a filtered collection of dictionary's values. It is roughly equivalent todictionary.AsRealmQueryable().Filter(query, arguments)
.
The resulting queryable collection will behave identically to the results obtained by calling
realm.All<T>()
, i.e. it will emit notifications when it changes and automatically update itself. (Issue #2647) -
Improve performance of client reset with automatic recovery and converting top-level tables into embedded tables. (Core upgrade)
-
Flexible sync will now wait for the server to have sent all pending history after a bootstrap before marking a subscription as Complete. (Core upgrade)
-
Slightly improve performance of
Realm.RemoveAll()
which removes all objects from an open Realm database. (Issue #2233) -
Improve error messages when not setting a BaseFilePath for realm or app configuration. (Issue 2863)
-
Added diagnostic error for nested classes used with the source generator syntax, as they are not yet supported. (Issue #3130)
-
Added
IList
implementation to all Realm collections to allow for UWP ListView databinding. (Issue #1759)
Fixed
- Fixed issue where Realm parameters' initialization would get run twice, resulting in unexpected behavior.
- Prevented
IEmbeddedObject
s andIAsymmetricObject
s from being used asRealmValue
s when added to a realm, and displaying more meaningful error messages. - Fix a use-after-free if the last external reference to an encrypted Realm was closed between when a client reset error was received and when the download of the new Realm began. (Core upgrade)
- Fixed an assertion failure during client reset with recovery when recovering a list operation on an embedded object that has a link column in the path prefix to the list from the top level object. (Core upgrade)
- Opening an unencrypted file with an encryption key would sometimes report a misleading error message that indicated that the problem was something other than a decryption failure. (Core upgrade)
- Fix a rare deadlock which could occur when closing a synchronized Realm immediately after committing a write transaction when the sync worker thread has also just finished processing a changeset from the server. (Core upgrade)
- Fix a race condition which could result in "operation cancelled" errors being delivered to async open callbacks rather than the actual sync error which caused things to fail. (Core upgrade)
- Bootstraps will not be applied in a single write transaction - they will be applied 1MB of changesets at a time, or as configured by the SDK. (Core upgrade)
- Fix database corruption and encryption issues on apple platforms. (Core upgrade)
- Added fully qualified names for source generated files, to avoid naming collisions. (Issue #3099
- Fixed an issue that would cause an exception when using unmanaged objects in bindings (Issue #3094)
- Fixed an issue where fetching a user's profile while the user logs out would result in an assertion failure. (Core upgrade)
- Removed the ".tmp_compaction_space" file being left over after compacting a Realm on Windows. (Core upgrade)
- Fixed a crash that would occur if you close a synchronized Realm while waiting for
SubscriptionSet.WaitForSynchronizationAsync
. (Issue #2952) - Avoid calling the setter on UI-bound properties in case the new value of the property is the same as the current one. This avoids some issue with MAUI, that seems to be calling the setter of bound properties unnecessarily when CollectionView/ListView are shown on screen. This is problematic if the object does not belong to the current user's permissions, as it will cause a compensanting write. In some limited cases this could cause an error loop (verified on iOS) when recycling of cells is involved. (Issue #3128)
- Fixes an issue with where the source generator will not add the namespace for types used in properties' initializers. (Issue #3135)
- Fixed an issue that would prevent Realm from working correctly in Unity applications that have Domain Reloading turned off. (Issue #2898)
- Fixed a bug when using
string.Contains
in .NET 2.1 or later where the search string is not a literal. (Issue #3134) - Added
[Obsolete]
notice for a fewErrorCode
enum members that are no longer in use. (Issue #3155
Compatibility
- Realm Studio: 12.0.0 or later.
Internal
- Using Core 12.13.0.
- Replaced
Realm.RefreshAsync
with a native implementation. (PR #2995)
10.18.0
10.18.0 (2022-11-02)
Enhancements
-
Introduced
Realm.SourceGenerator
, a Source Generator that can generate Realm model classes. This is part of our ongoing effort to modernize the Realm library, and will allow to introduce certain language level features easier in the future.
In order to use the source generation the model classes need to be declared implementing one of the base interfaces (IRealmObject
,IEmbeddedObject
orIAsymmetricObject
) and be declared partial. For example:public partial class Person: IRealmObject { public int Age { get; set; } public string Name { get; set; } public PhoneNumber Phone { get; set; } } public partial class PhoneNumber: IEmbeddedObject { public string Number { get; set; } public string Prefix { get; set; } }
The source generator will then take care of adding the full implementation for the interfaces.
Most of the time converting the "classic" Realm model classes (classes derived from
RealmObject
,EmbeddedObject
orAsymmetricObject
) to use the new source generation means just defining the class as partial and switching out the base class for the corresponding interface implementation.
The classic Realm model definition will still be supported, but will be phased out in the future.Please note that the source generator is still in beta, so let us know if you experience any issue while using them.
Some additional notes:OnManaged
andOnPropertyChanged
are now partial methods.- Inheritance is not supported, so the Realm models cannot derive from any other class.
- Nested classes are not supported.
Fixed
- Fixed a NullReferenceException being thrown when subscribing to
PropertyChanged
notifications on aSession
instance that is then garbage collected prior to unsubscribing. (PR #3061) - Removed bitcode support from the iOS binary as it's no longer accepted for App Store submissions. (Issue #3059)
- Slightly increased performance and reduced allocations when creating an enumerator for frozen collections (Issue #2815).
Compatibility
- Realm Studio: 11.0.0 or later.
Internal
10.17.0
10.17.0 (2022-10-06)
Enhancements
- Prioritize integration of local changes over remote changes - shorten the time users may have to wait when committing local changes. Stop storing downloaded changesets in history. (Core upgrade)
- Greatly improve the performance of sorting or distincting a Dictionary's keys or values. The most expensive operation is now performed O(log N) rather than O(N log N) times, and large Dictionaries can see upwards of 99% reduction in time to sort. (Core upgrade)
- Seamlessly handle migrating an App Services application deployment model. (Core upgrade)
Fixed
- Fix a use-after-free when a sync session is closed and the app is destroyed at the same time. (Core upgrade)
- Fixed a
NullReferenceException
occurring inRealmObjectBase
's finalizer whenever an exception is thrown before the object gets initialized. (Issue #3045)
Compatibility
- Realm Studio: 11.0.0 or later.
Internal
- Using Core 12.9.0
10.16.0
10.16.0 (2022-10-03)
Enhancements
-
Introduced
AsymmetricObject
intended for write-heavy workloads, where high performance is generally important. This new object:- syncs data unidirectionaly, from the clients to the server
- can't be queried, deleted, or modified once added to the Realm
- is only usable with flexible sync
- can't be the receiveing end of any type of relationship
- can contain
EmbeddedObject
s but cannot link toRealmObject
orAsymmetricObject
.
In the same write transaction, it is legal to add
AsymmetricObject
s andRealmObject
sclass Measurement : AsymmetricObject { [PrimaryKey, MapTo("_id")] public Guid Id { get; private set; } = Guid.NewGuid(); public double Value { get; set; } public DataTimeOffset Timestamp { get; private set; } = DateTimeOffset.UtcNow; } class Person : RealmObject { //............ } //..... var measurement = new Measurement { Value = 9.876 }; realm.Write(() => { realm.Add(measurement); realm.Add(new Person()); }); _ = asymmetricObject.Value; // runtime error _ = realm.All<Measurement>(); // compile time error
-
Added two client reset handlers,
RecoverUnsyncedChangesHandler
andRecoverOrDiscardUnsyncedChangesHandler
, that try to automatically merge the unsynced local changes with the remote ones in the event of a client reset. Specifically withRecoverOrDiscardUnsyncedChangesHandler
, you can fallback to the discard local strategy in case the automatic merge can't be performed as per your server's rules. These new two stragegies simplify even more the handling of client reset events when compared toDiscardUnsyncedChangesHandler
.RecoverOrDiscardUnsyncedChangesHandler
is going to be the default from now on. An example is as follows -
Added two client reset handlers,
RecoverUnsyncedChangesHandler
andRecoverOrDiscardUnsyncedChangesHandler
, that try to automatically merge the unsynced local changes with the remote ones in the event of a client reset. Specifically withRecoverOrDiscardUnsyncedChangesHandler
, you can fallback to the discard unsynced strategy in case the automatic merge can't be performed as per your server's rules. These new two stragegies simplify even more the handling of client reset events when compared toDiscardUnsyncedChangesHandler
.RecoverOrDiscardUnsyncedChangesHandler
is going to be the default from now on. More info on the aforementioned strategies can be found in our docs page. An example usage of one of the new handler is as follows:var conf = new PartitionSyncConfiguration(partition, user) { ClientResetHandler = new RecoverOrDiscardUnsyncedChangesHandler { // As always, the following callbacks are optional OnBeforeReset = (beforeFrozen) => { // executed right before a client reset is about to happen }, OnAfterRecovery = (beforeFrozen, after) => { // executed right after an automatic recovery from a client reset has completed }, OnAfterDiscard = (beforeFrozen, after) => { // executed after an automatic recovery from a client reset has failed but the DiscardUnsyncedChanges fallback has completed }, ManualResetFallback = (session, err) => { // handle the reset manually } } };
(PR #2745)
-
Introducing string query support for constant list expressions such as
realm.All<Car>().Filter("Color IN {'blue', 'orange'}")
. This also includes general query support for list vs list matching such asrealm.All<Car>().Filter("NONE Features IN {'ABS', 'Seat Heating'}")
. (Core upgrade) -
Improve performance when a new Realm file connects to the server for the first time, especially when significant amounts of data has been written while offline. (Core upgrade)
-
Shift more of the work done on the sync worker thread out of the write transaction used to apply server changes, reducing how long it blocks other threads from writing. (Core upgrade)
-
Improve the performance of the sync changeset parser, which speeds up applying changesets from the server. (Core upgrade)
Fixed
- Added a more meaningful error message whenever a project doesn't have
[TargetFramework]
defined. (Issue #2843) - Opening a read-only Realm for the first time with a
SyncConfiguration
did not set the schema version, which could lead tom_schema_version != ObjectStore::NotVersioned
assertion failures. (Core upgrade) - Upload completion callbacks (i.e.
Session.WaitForUploadAsync
) may have called before the download message that completed them was fully integrated. (Core upgrade) - Fixed an exception "fcntl() with F_BARRIERFSYNC failed: Inappropriate ioctl for device" when running with MacOS on an exFAT drive. (Core upgrade)
- Syncing of a Decimal128 with big significand could result in a crash. (Core upgrade)
Realm.Refresh()
did not actually advance to the latest version in some cases. If there was a version newer than the current version which did not require blocking it would advance to that instead, contrary to the documented behavior. (Core upgrade)- Several issues around notifications were fixed. (Core upgrade)
- Fix a data race on RealmCoordinator::m_sync_session which could occur if multiple threads performed the initial open of a Realm at once.
- If a SyncSession outlived the parent Realm and then was adopted by a new Realm for the same file, other processes would not get notified for sync writes on that file.
- Fix one cause of QoS inversion warnings when performing writes on the main thread on Apple platforms. Waiting for async notifications to be ready is now done in a QoS-aware ways.
- If you set a subscription on a link in flexible sync, the server would not know how to handle it (#5409, since v11.6.1)
- If a case insensitive query searched for a string including an 4-byte UTF8 character, the program would crash. (Core upgrade)
- Added validation to prevent adding a removed object using Realm.Add. (Issue #3020)
Compatibility
- Realm Studio: 12.0.0 or later.
Internal
- Using Core 12.7.0.
10.15.1
10.15.1 (2022-08-08)
Fixed
- Fixed an issue introduced in 10.15.0 that would prevent non-anonoymous user authentication against Atlas App Services. (Issue #2987)
- Added override to
User.ToString()
that outputs the user id and provider. (PR #2988) - Added == and != operator overloads to
User
that matches the behavior ofUser.Equals
. (PR #2988)
Compatibility
- Realm Studio: 12.0.0 or later.
Internal
- Using Core x.y.z.
10.15.0
10.15.0 (2022-08-05)
Enhancements
- Preview support for .NET 6 with Mac Catalyst and MAUI. (PR #2959)
- Reduce use of memory mappings and virtual address space (Core upgrade)
Fixed
- Fix a data race when opening a flexible sync Realm (Core upgrade).
- Fixed a missing backlink removal when setting a
RealmValue
from aRealmObject
to null or any other non-RealmObject value. Users may have seen exception of "key not found" or assertion failures such asmixed.hpp:165: [realm-core-12.1.0] Assertion failed: m_type
when removing the destination object. (Core upgrade) - Fixed an issue on Windows that would cause high CPU usage by the sync client when there are no active sync sessions. (Core upgrade)
- Improved performance of sync clients during integration of changesets with many small strings (totalling > 1024 bytes per changeset) on iOS 14, and devices which have restrictive or fragmented memory. (Core upgrade)
- Fix exception when decoding interned strings in realm-apply-to-state tool. (Core upgrade)
- Fix a data race when committing a transaction while multiple threads are waiting for the write lock on platforms using emulated interprocess condition variables (most platforms other than non-Android Linux). (Core upgrade)
- Fix some cases of running out of virtual address space (seen/reported as mmap failures) (Core upgrade)
- Decimal128 values with more than 110 significant bits were not synchronized correctly with the server (Core upgrade)
Compatibility
- Realm Studio: 11.0.0 or later.
Internal
- Using Core 12.4.0.
10.14.0
10.14.0 (2022-06-02)
Enhancements
- Added a more efficient replacement for
Realm.WriteAsync
. The previous API would start a background thread, open the Realm there and run a synchronous write transaction on the background thread. The new API will asynchronously acquire the write lock (begin transaction) and asynchronously commit the transaction, but the actual write block will execute on the original thread. This means that objects/queries captured before the block can be used inside the block without relying on threadsafe references. Importantly, you can mix and match async and sync calls. And when calling anyRealm.WriteAsync
on a background thread the call is just run synchronously, so you should useRealm.Write
for readability sake. The new API is made ofRealm.WriteAsync<T>(Func<T> function, CancellationToken cancellationToken)
,Realm.WriteAsync(Action action, CancellationToken cancellationToken)
,Realm.BeginWriteAsync(CancellationToken cancellationToken)
andTransaction.CommitAsync(CancellationToken cancellationToken)
. While theTransaction.Rollback()
doesn't need an async counterpart. The deprecated API calls areRealm.WriteAsync(Action<Realm> action)
,Real.WriteAsync<T>(Func<Realm, IQueryable<T>> function)
,Realm.WriteAsync<T>(Func<Realm, IList<T>> function)
andRealm.WriteAsync<T>(Func<Realm, T> function)
. Here is an example of usage:(PR #2899)using Realms; var person = await _realm.WriteAsync(() => { return _realm.Add( new Person { FirstName = "Marco" }); }); // you can use/modify person now // without the need of using ThreadSafeReference
- Added the method
App.DeleteUserFromServerAsync
to delete a user from the server. It will also invalidate the user locally as well as remove all their local data. It will not remove any data the user has uploaded from the server. (Issue #2675) - Added boolean property
ChangeSet.IsCleared
that is true when the collection gets cleared. Also Realm collections now raiseCollectionChanged
event with actionReset
instead ofRemove
when the collections is cleared. Please note that this will work only with collection properties, such asIList
andISet
. (Issue #2856) - Added
PopulateInitialSubscriptions
toFlexibleSyncConfiguration
- this is a callback that will be invoked the first time a Realm is opened. It allows you to create the initial subscriptions that will be added to the Realm before it is opened. (Issue #2913) - Bump the SharedInfo version to 12. This requires update of any app accessing the file in a multiprocess scenario, including Realm Studio.
- The sync client will gracefully handle compensating write error messages from the server and pass detailed info to the SDK's sync error handler about which objects caused the compensating write to occur. (#5528)
Fixed
- Adding an object to a Set, deleting the parent object, and then deleting the previously mentioned object causes crash (#5387)
- Flexible sync would not correctly resume syncing if a bootstrap was interrupted (#5466)
- Flexible sync will now ensure that a bootstrap from the server will only be applied if the entire bootstrap is received - ensuring there are no orphaned objects as a result of changing the read snapshot on the server (#5331)
- Partially fix a performance regression in write performance on Apple platforms. Committing an empty write transaction is ~10x faster than 10.13.0, but still slower than pre-10.7.1 due to using more crash-safe file synchronization (since v10.7.1). (Swift issue #7740).
Compatibility
- Realm Studio: 11.0.0 or later.
Internal
- Using Core 12.1.0.
10.13.0
10.13.0 (2022-05-18)
Enhancements
- Adds the functionality to convert Sync Realms into Local Realms and Local Realms into Sync Realms. (Issue #2746)
- Added support for a new client reset strategy, called Discard Unsynced Changes. This new stragegy greatly simplifies the handling of a client reset event on a synchronized Realm.
This addition makesSession.Error
deprecated. In order to temporarily contiue using the currentSession.Error
the following must be done:In order to take advantage of the new Discard Unsynced Changes feature, the following should be done (all callbacks are optional):var conf = new PartitionSyncConfiguration(partition, user) { ClientResetHandler = new ManualRecoveryHandler(); };
If, instead, you want to continue using the manual solution even after the end of the deprecation period, the following should be donevar conf = new PartitionSyncConfiguration(partition, user) { ClientResetHandler = new DiscardLocalResetHandler { OnBeforeReset = (beforeFrozen) => { // executed right before a client reset is about to happen }, OnAfterReset = (beforeFrozen, after) => { // executed right after a client reset is has completed }, ManualResetFallback = (session, err) => { // handle the reset manually } } };
var conf = new PartitionSyncConfiguration(partition, user) { ClientResetHandler = new ManualRecoveryHandler((sender, e) => { // user's code for manual recovery });
Fixed
- Fixed a
System.DllNotFoundException
being thrown by Realm APIs at startup on Xamarin.iOS (Issue #2926, since 10.12.0)
Compatibility
- Realm Studio: 11.0.0 or later.
Internal
- Using Core 11.14.0.
10.12.0
10.12.0 (2022-05-05)
Note for Xamarin.iOS targets: This release has a regression that causes Realm to fail to find the native binaries on iOS when using the Xamarin toolchain (not MAUI), resulting in a System.DllNotFoundException
the first time a Realm API is used. Since the release only contains MAUI-related changes, it is safe to roll back to 10.11.2. The fix for the regression will be released in 10.13.0.
Enhancements
- Preview support for .NET 6 with iOS, Android, and MAUI.
We've added tentative support for the new .NET 6 Mobile workloads (except MacCatalyst, which will be enabled later). The .NET tooling itself is still in preview so we don't have good test coverage of the new platforms just yet. Please report any issues you find at https://github.com/realm/realm-dotnet/issues/new/choose.
Compatibility
- Realm Studio: 11.0.0 or later.
Internal
- Using Core 11.14.0.