4.0.0 - Unified Realm package and move to .NET Standard 2.0

NOTE!!! You will need to upgrade your Realm Object Server to at least version 3.23.1 or use Realm Cloud to use the path-level Permission API (User.ApplyPermissionsAsync, User.GetGrantedPermissionsAsync, etc.). Using them against an older version of ROS will result in 404 NotFound exceptions being thrown.

The Realm.Server and Realm.Database packages have been merged into the main Realm package, so when upgrading, be sure to remove them from your references.

Breaking Changes

• The following deprecated methods and classes have been removed:
  • The SyncConfiguration class has been split into FullSyncConfiguration and QueryBasedSyncConfiguration. Use one of these classes to connect to the Realm Object Server.
  • The TestingExtensions.SimulateProgress method has been removed as it hasn't worked for some time.
  • The Property.IsNullable property has been removed. To check if a property is nullable, check Property.Type for the PropertyType.Nullable flag.
  • The Credentials.Provider class has been removed. Previously, it contained a few constants that were intended for internal use mostly.
  • The User.ConfigurePersistance method has been superseded by SyncConfigurationBase.Initialize.
  • User.LogOut has been removed in favor of User.LogOutAsync.
  • User.GetManagementRealm has been removed in favor of the User.ApplyPermissionsAsync set of wrapper API.
  • User.GetPermissionRealm has been removed in favor of the User.GetGrantedPermissions wrapper API.
• Deprecated the IQueryable<T>.Subscribe(string name) extension method in favor of IQueryable<T>.Subscribe(SubscriptionOptions options).
• Reworked the internal implementation of the permission API. For the most part, the method signatures haven't changed or where they have changed, the API have remained close to the original (e.g. IQueryable<T> has changed to IEnumerable<T>). (Issue #1863)
  • Changed the return type of User.GetGrantedPermissionsAsync from IQueryable<PathPermission> to IEnumerable<PathPermission>. This means that the collection is no longer observable like regular Realm-backed collections. If you need to be notified for changes of this collection, you need to implement a polling-based mechanism yourself.
  • PathPermission.MayRead/MayWrite/MayManage have been deprecated in favor of a more-consistent AccessLevel API.
  • In User.ApplyPermissionsAsync, renamed the realmUrl parameter to realmPath.
  • In User.OfferPermissionsAsync, renamed the realmUrl parameter to realmPath.
  • Removed the PermissionOfferResponse and PermissionChange classes.
  • Removed the IPermissionObject interface.
  • Removed the ManagementObjectStatus enum.
  • Removed the User.GetPermissionChanges and User.GetPermissionOfferResponses methods.
  • The millisecondTimeout argument in User.GetGrantedPermissionsAsync has been removed.
  • The PermissionException class has been replaced by HttpException.
• The AuthenticationException class has been merged into the HttpException class.

Enhancements

• Added Session.Start() and Session.Stop() methods that allow you to pause/resume synchronization with the Realm Object Server. (Issue #138)

• Added an IQueryable<T>.Subscribe(SubscriptionOptions, params Expression<Func<T, IQueryable>>[] includedBacklinks) extension method that allows you to configure additional options for the subscription, such as the name, time to live, and whether it should update an existing subscription. The includedBacklinks argument allows you to specify which backlink properties should be included in the transitive closure when doing query-based sync. For example:

  class Dog : RealmObject
  {
      public Person Owner { get; set; }
  }
  
  class Person : RealmObject
  {
      [Backlink(nameof(Dog.Owner))]
      public IQueryable<Dog> Dogs { get; }
  }
  
  var options = new SubscriptionOptions
  {
      Name = "adults",
      TimeToLive = TimeSpan.FromDays(1),
      ShouldUpdate = true
  };
  
  var people = realm.All<Person>()
                    .Where(p => p.Age > 18)
                    .Subscribe(options, p => p.Dogs);
  
  await people.WaitForSynchronzationAsync();
  // Dogs that have an owner set to a person that is over 18
  // will now be included in the objects synchronized locally.
  var firstPersonDogs = people.Results.First().Dogs;

  (Issue #1838 & Issue #1834)

• Added a Realm.GetAllSubscriptions() extension method that allows you to obtain a collection of all registered query-based sync subscriptions. (Issue #1838)

• Added AccessLevel property to PathPermission to replace the now deprecated MayRead/MayWrite/MayManage. (Issue #1863)

• Added RealmOwnerId property to PathPermission that indicates who the owner of the Realm is. (Issue #1863)

• Added support for building with dotnet build (previously only the msbuild command line was supported). (PR #1849)

• Improved query performance for unindexed string columns when the query has a long chain of OR conditions. (Core upgrade)

• Improved performance of encryption and decryption significantly by utilizing hardware optimized encryption functions. (Core upgrade)

• Compacting a realm into an encrypted file could take a really long time. The process is now optimized by adjusting the write buffer size relative to the used space in the realm. (Core upgrade)

• The string-based query parser (results.Filter("...")) now supports readable timestamps with a 'T' separator in addition to the originally supported "@" separator. For example: startDate > 1981-11-01T23:59:59:1 (Core upgrade)

Fixed

• Fixes an issue where using the StringExtensions.Contains(string, string, StringComparison) extension method inside a LINQ query would result in an exception being thrown on .NET Core 2.1+ or Xamarin.iOS/Android projects.(Issue #1848)
• Creating an object after creating an object with the int primary key of "null" would hit an assertion failure. (Core upgrade)

Compatibility

• Realm Object Server: 3.23.1 or later.

Internal

• Upgraded Sync from 3.14.11 to 4.5.1 and Core 5.12.7 to 5.20.0.

3.4.0

NOTE!!! You will need to upgrade your Realm Object Server to at least version 3.11.0 or use Realm Cloud. If you try to connect to a ROS v3.10.x or previous, you will see an error like Wrong protocol version in Sync HTTP request, client protocol version = 25, server protocol version = 24.

Enhancements

• Download progress is now reported to the server, even when there are no local changes. This allows the server to do history compaction much more aggressively, especially when there are many clients that rarely or never make local changes. (#1772)
• Reduce memory usage when integrating synchronized changes sent by ROS.
• Added ability to supply a custom log function for handling logs emitted by Sync by specifying SyncConfigurationBase.CustomLogger. It must be set before opening a synchronized Realm. (#1824)
• Clients using protocol 25 now report download progress to the server, even when they make no local changes. This allows the server to do history compaction much more aggressively, especially when there are many clients that rarely or never make local changes. (#1772)
• Add a User-Agent header to HTTP requests made to the Realm Object Server. By default, this contains information about the Realm library version and .NET platform. Additional details may be provided (such as the application name/version) by setting SyncConfigurationBase.UserAgent prior to opening a synchronized Realm. If developing a Xamarin app, you can use the Xamarin.Essentials plugin to automate that: SyncConfiguration.UserAgent = $"{AppInfo.Name} ({AppInfo.PackageName} {AppInfo.VersionString})".

Fixed

• Fixed a bug that could lead to crashes with a message such as Assertion failed: ndx < size() with (ndx, size()) = [742, 742].
• Fixed a bug that resulted in an incorrect LogLevel being sent to Sync when setting SyncConfigurationBase.LogLevel. (#1824, since 2.2.0)
• Fixed a bug that prevented Realm.GetInstanceAsync from working when used with QueryBasedSyncConfiguration. (#1827, since 3.1.0)

Breaking Changes

• The deprecated method realm.SubscribeToObjectsAsync has been removed in this version. (#1772)
• User.ConfigurePersistence has been deprecated in favor of SyncConfigurationBase.Initialize.

Compatibility

• Realm Object Server: 3.11.0 or later.
  The sync protocol version has been bumped to version 25. The server is backwards-compatible with clients using protocol version 24 or below, but clients at version 25 are not backwards-compatible with a server at protocol version 24. The server must be upgraded before any clients are upgraded.

Internal

• Upgraded Sync from 3.9.2 to 3.14.11 and Core from 5.8.0 to 5.12.7.

3.3.0 - added progress notifications to GetInstanceAsync

Enhancements

• Exposed an OnProgress property on SyncConfigurationBase. It allows you to specify a progress callback that will be invoked when using Realm.GetInstanceAsync to report the download progress. (#1807)

Fixed

• Trying to call Subscription.WaitForSynchronizationAsync on a background thread (without a SynchronizationContext) would previously hang indefinitely. Now a meaningful exception will be thrown to indicate that this is not supported and this method should be called on a thread with a synchronization context. (dotnet-private#130, since v3.0.0)

Compatibility

• Realm Object Server: 3.0.0 or later.
• APIs are backwards compatible with all previous releases in the 3.x.y series.
• File format: Generates Realms with format v9 (Reads and upgrades all previous formats)

3.2.1 - Fix subscription-related errors

Bug fixes

• Fixed a bug that would typically result in exceptions with a message like An unknown error has occurred. State: *some-number-larger than 127* when subscribing to queries. (dotnet-private#128, since 3.0.0)

3.2.0 - Out-of-the-box Linux certificate validation

Enhancements

• RealmObject inheritors will now raise PropertyChanged after they have been removed from Realm. The property name in the event arguments will be IsValid.
• Bundle some common certificate authorities on Linux so connecting to ROS instances over SSL should work out of the box for most certificates. Notably, it will now work out of the box for Realm Cloud instances.

Bug fixes

• When constructing queries that compare an invalid/unmanaged RealmObject (e.g. realm.All<Foo>().Where(f => f.Bar == someBar)), a meaningful exception will now be thrown rather than an obscure ArgumentNullException.
• Added ShouldCompactOnLaunch to the PCL version of the library. (dotnet-private#125)

3.1.0 - New configuration classes

Enhancements

• Exposed a ChangeSet.NewModifiedIndices collection that contains information about the indices of the objects that changed in the new version of the collection (i.e. after accounting for the insertions and deletions).
• Update Fody to 3.0.

Bug fixes

• WriteAsync will no longer perform a synchronous Refresh on the main thread. (#1729)
• Trying to add a managed Realm Object to a different instance of the same on-disk Realm will no longer throw an exception.
• Removed the IList compliance for Realm collections. This fixes an issue which would cause the app to hang on Android when deselecting an item from a ListView bound to a Realm collection.

Breaking Changes

• SyncConfiguration is now deprecated and will be removed in a future version. Two new configuration classes have been exposed - [QueryBasedSyncConfiguration](https://docs.realm.io/platform/using-synced realms/syncing-data#using-query-based-synchronization) and FullSyncConfiguration. If you were using a SyncConfiguration with IsPartial = true, then change your code to use QueryBasedSyncConfiguration. Similarly, if IsPartial was not set or was set to false, use FullSyncConfiguration.
• Removed the IList compliance for Realm collections. This will prevent automatic updates of ListViews databound to Realm collections in UWP projects.

3.0.0 - Realm Platform 3.0

Enhancements

• Allow [MapTo] to be applied on classes to change the name of the table corresponding to that class. (#1712)
• Added an improved API for adding subscriptions in partially-synchronized Realms. IQueryable<T>.Subscribe can be used
  to subscribe to any query, and the returned Subscription<T> object can be used to observe the state of the subscription
  and ultimately remove the subscription. See the documentation
  for more information. (#1679)
• Added a fine-grained permissions system for use with partially-synchronized Realms. This allows permissions to be
  defined at the level of individual objects or classes. See the
  documentation
  for more information. (#1714)
• Exposed a string-based IQueryable<T>.Filter(predicate) method to enable more advanced querying
  scenarios such as:
  • Following links: realm.All<Dog>().Filter("Owner.FirstName BEGINSWITH 'J'").
  • Queries on collections: realm.All<Child>().Filter("Parents.FirstName BEGINSWITH 'J'") - find all
    children who have a parent whose name begins with J or realm.All<Child>().Filter("Parents.@avg.Age > 50") -
    find all children whose parents' average age is more than 50.
  • Subqueries: realm.All<Person>().Filter("SUBQUERY(Dogs, $dog, $dog.Vaccinated == false).@count > 3") - find all
    people who have more than 3 unvaccinated dogs.
  • Sorting: realm.All<Dog>().Filter("TRUEPREDICATE SORT(Owner.FirstName ASC, Age DESC)") - find all dogs and
    sort them by their owner's first name in ascending order, then by the dog's age in descending.
  • Distinct: realm.All<Dog>().Filter("TRUEPREDICATE DISTINCT(Age) SORT(Name)") - find all dogs, sort them
    by their name and pick one dog for each age value.
  • For more examples, check out the
    javascript query language docs -
    the query syntax is identical - or the NSPredicate Cheatsheet.
• The SyncConfiguration constructor now accepts relative Uris. (#1720)
• Added the following methods for resetting the user's password and confirming their email:
  RequestPasswordResetAsync, CompletePasswordResetAsync, RequestEmailConfirmationAsync, and ConfirmEmailAsync.
  These all apply only to users created via Credentials.UsernamePassword who have provided their email as
  the username. (#1721)

Bug fixes

• Fixed a bug that could cause deadlocks on Android devices when resolving thread safe references. (#1708)

Breaking Changes

• Uses the Sync 3.0 client which is incompatible with ROS 2.x.
• Permission has been renamed to PathPermission to more closely reflect its purpose.
  Furthermore, existing methods to modify permissions only work on full Realms. New methods
  and classes are introduced to configure access to a partially synchronized Realm.
• The type of RealmConfiguration.DefaultConfiguration has changed to RealmConfigurationBase to allow
  any subclass to be set as default. (#1720)
• The SyncConfiguration constructor arguments are now optional. The user value will default to the
  currently logged in user and the serverUri value will default to realm://MY-SERVER-URL/default where
  MY-SERVER-URL is the host the user authenticated against. (#1720)
• The serverUrl argument in User.LoginAsync(credentials, serverUrl) and User.GetLoggedInUser(identity, serverUrl)
  has been renamed to serverUri for consistency. (#1721)

2.2.0 - Deprecating Feature Tokens

Enhancements

• Added an IsDynamic property to RealmConfigurationBase, allowing you to open a Realm file and read its schema from disk. (#1637)
• Added a new InMemoryConfiguration class that allows you to create an in-memory Realm instance. (#1638)
• Allow setting elements of a list directly - e.g. foo.Bars[2] = new Bar() or foo.Integers[3] = 5. (#1641)
• Added Json Web Token (JWT) credentials provider. (#1655)
• Added Anonymous and Nickname credentials providers. (#1671)

Bug fixes

• Fixed an issue where initial collection change notification is not delivered to all subscribers. (#1696)
• Fixed a corner case where RealmObject.Equals would return true for objects that are no longer managed by Realm. (#1698)

Breaking Changes

• SyncConfiguration.SetFeatureToken is deprecated and no longer necessary in order to use Sync on Linux or server-side features. (#1703)

2.1.0 - Server Side .NET

This release brings bug fixes and a new server-side package: Realm.Server. It allows you to create server-side change handlers that observe hundreds or thousands of Realms and get notifications when any of those changes. Read the full announcement here or head over to the documentation.

Enhancements

• Added an [Explicit] attribute that can be applied to classes or assemblies. If a class is decorated with it, then it will not be included in the default schema for the Realm (i.e. you have to explicitly set RealmConfiguration.ObjectClasses to an array that contains that class). Similarly, if it is applied to an assembly, all classes in that assembly will be considered explicit. This is useful when developing a 3rd party library that depends on Realm to avoid your internal classes leaking into the user's schema. (#1602)

Bug fixes

• Fixed a bug that would prevent writing queries that check if a related object is null, e.g. realm.All<Dog>().Where(d => d.Owner == null). (#1601)
• Addressed an issue that would cause the debugger to report an unobserved exception being thrown when "Just My Code" is disabled. (#1603)
• Calling Realm.DeleteRealm on a synchronized Realm will now properly delete the realm.management folder. (#1621)
• Fixed a crash when accessing primitive list properties on objects in realms opened with a dynamic schema (e.g. in migrations). (#1629)

2.0.0 - Sync for Windows, partial sync, lists of primitives

This is a major release that includes numerous improvements as well as several highly requested new features. This release is incompatible with the Realm Object Server 1.x series. Comprehensive documentation on migrating an app that uses synchronized Realms from 1.x to 2.x will be published shortly. Apps that are using offline realms only are not affected and can upgrade safely.

• We're releasing sync for Windows (UWP, .NET Core, and classic desktop) as beta. It has a few rough edges, but we believe it's stable enough to start experimenting with and use it in your development workflow. The stable release of Sync for Windows is expected later this month.
• Partial Sync is released as a technical preview and not meant to be used in production. It allows you to specify a query and only objects matching that query will be downloaded by the Realm Object Server. The API is very much work in progress and we expect to change it to something more idiomatic for .NET at a later point. A stable release of Partial Sync is expected early next year.
• We have dropped the constraints of persisted IList<T> properties and you can now specify primitive values as well as RealmObject subtypes.

Below is the full list of changes and enhancements.

Enhancements

• Added support for collections of primitive values. You can now define properties as IList<T> where T can be any
  type supported by Realm, except for another IList. As a result, a lot of methods that previously had constraints on
  RealmObject now accept any type and may throw a runtime exception if used with an unsupported type argument.
  (#1517)
• Added HelpLink pointing to the relevant section of the documentation to most Realm exceptions. (#1521)
• Added RealmObject.GetBacklinks API to dynamically obtain all objects referencing the current one. (#1533)
• Added a new exception type, PermissionDeniedException, to denote permission denied errors when working with synchronized Realms that
  exposes a method - DeleteRealmUserInfo - to inform the binding that the offending Realm's files should be kept or deleted immediately.
  This allows recovering from permission denied errors in a more robust manner. (#1543)
• The keychain service name used by Realm to manage the encryption keys for sync-related metadata on Apple platforms is now set to the
  bundle identifier. Keys that were previously stored within the Realm-specific keychain service will be transparently migrated to the
  per-application keychain service. (#1522)
• Added a new exception type - IncompatibleSyncedFileException - that allows you to handle and perform data migration from a legacy (1.x) Realm file
  to the new 2.x format. It can be thrown when using Realm.GetInstance or Realm.GetInstanceAsync and exposes a GetBackupRealmConfig method
  that allows you to open the old Realm file in a dynamic mode and migrate any required data. (#1552)
• Enable encryption on Windows. (#1570)
• Enable Realm compaction on Windows. (#1571)
• UserInfo has been significantly enhanced. It now contains metadata about a user stored on the Realm Object Server, as well as a list of all user
  account data associated with that user. (#1573)
• Introduced a new method - User.LogOutAsync to replace the now-deprecated synchronous call. (#1574)
• Exposed BacklinksCount property on RealmObject that returns the number of objects that refer to the current object via a to-one or a to-many relationship. (#1578)
• String primary keys now support null as a value. (#1579)
• Add preview support for partial synchronization. Partial synchronization allows a synchronized Realm to be opened in such a way
  that only objects requested by the user are synchronized to the device. You can use it by setting the IsPartial property on a
  SyncConfiguration, opening the Realm, and then calling Realm.SubscribeToObjectsAsync with the type of object you're interested in,
  a string containing a query determining which objects you want to subscribe to, and a callback which will report the results. You may
  add as many subscriptions to a synced Realm as necessary. (#1580)
• Ensure that Realm collections (IList<T>, IQueryable<T>) will not change when iterating in a foreach loop. (#1589)

Bug fixes

• Realm.GetInstance will now advance the Realm to the latest version, so you no longer have to call Refresh manually after that. (#1523)
• Fixed an issue that would prevent iOS Share Extension projects from working. (#1535)

Breaking Changes

• This release requires Realm Object Server 2.x.
• Realm.CreateObject(string className) now has additional parameter object primaryKey. You must pass that when creating a new object using the dynamic API. If the object you're creating doesn't have primary key declared, pass null. (#1381)
• AcceptPermissionOfferAsync now returns the relative rather than the absolute url of the Realm the user has been granted permissions to. (#1595)