diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 6cf5082a3b..3519f3ccd9 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,6 +13,14 @@ Add links to every SDK's pages where you got the SDK-specific information: - [PAGE_NAME](https://www.mongodb.com/docs/atlas/device-sdks/LIVE-DOCS-LINK) +### Release Notes + + + ### PR Author Checklist Before requesting a review for your PR, please check these items: diff --git a/.github/workflows/netflify-preview-links.yml b/.github/workflows/netflify-preview-links.yml index 97e8985e79..a37b6b78f3 100644 --- a/.github/workflows/netflify-preview-links.yml +++ b/.github/workflows/netflify-preview-links.yml @@ -23,7 +23,7 @@ jobs: id: build_page_links run: | new_links="" - base_link='https://deploy-preview-${{ github.event.number }}--docs-realm.netlify.app' + base_link='https://deploy-preview-${{ github.event.number }}--device-sdk.netlify.app' changed_files=${{ steps.changed-files.outputs.all_changed_files }} files=$(echo $changed_files | tr "," "\n") for file in $files; do diff --git a/examples/dotnet/Examples/WorkWithRealm.cs b/examples/dotnet/Examples/WorkWithRealm.cs index 3eac893253..ec821ff164 100644 --- a/examples/dotnet/Examples/WorkWithRealm.cs +++ b/examples/dotnet/Examples/WorkWithRealm.cs @@ -205,6 +205,33 @@ public void Notifications() }); //:snippet-end: + NotificationCallbackDelegate notificationCallback + = new NotificationCallbackDelegate((sender,changes) => {}); + //:snippet-start:field-notifications + var query = realm.All(); + KeyPathsCollection kpc; + + // Use one of these equivalent declarations to + // specify the fields you want to monitor for changes: + + kpc = KeyPathsCollection.Of("Email", "Name"); + kpc = new List {"Email", "Name"}; + + // To get all notifications for top-level properties + // and 4 nested levels of properties, use the `Full` + // static value: + + kpc = KeyPathsCollection.Full; + + // To receive notifications for changes to the + // collection only and none of the properties, + // use the `Shallow` static value: + + kpc = KeyPathsCollection.Shallow; + + query.SubscribeForNotifications(notificationCallback, kpc); + //:snippet-end: + //:snippet-start:unsub-collection-notifications // Watch for collection notifications. // Call Dispose() when you are done observing the diff --git a/source/examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs b/source/examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs new file mode 100644 index 0000000000..52f43827ab --- /dev/null +++ b/source/examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs @@ -0,0 +1,22 @@ +var query = realm.All(); +KeyPathsCollection kpc; + +// Use one of these equivalent declarations to +// specify the fields you want to monitor for changes: + +kpc = KeyPathsCollection.Of("Email", "Name"); +kpc = new List {"Email", "Name"}; + +// To get all notifications for top-level properties +// and 4 nested levels of properties, use the `Full` +// static value: + +kpc = KeyPathsCollection.Full; + +// To receive notifications for changes to the +// collection only and none of the properties, +// use the `Shallow` static value: + +kpc = KeyPathsCollection.Shallow; + +query.SubscribeForNotifications(notificationCallback, kpc); diff --git a/source/sdk/dotnet/react-to-changes.txt b/source/sdk/dotnet/react-to-changes.txt index bacb979025..a5eeb113d0 100644 --- a/source/sdk/dotnet/react-to-changes.txt +++ b/source/sdk/dotnet/react-to-changes.txt @@ -90,9 +90,6 @@ notification handler on the collection or handle the `CollectionChanged `__ event. -Register a Collection Change Listener -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - You can register a notification handler on a specific collection within a realm. The collection can be of realm objects (like ``realm.All()``) or a collection property on a @@ -107,7 +104,10 @@ Realm emits an initial notification when a subscription is added. After the initial notification, Realm delivers notifications asynchronously whenever a write transaction adds, modifies, or removes objects in the collection. -Specifically, the notification contains a :dotnet-sdk:`ChangeSet ` +Notification ChangeSets +~~~~~~~~~~~~~~~~~~~~~~~ + +The notification contains a :dotnet-sdk:`ChangeSet ` with 6 properties: - ``DeletedIndices`` is an ``int[]`` that contains the indices of the objects that were @@ -126,6 +126,20 @@ with 6 properties: structs that contain the previous and new index of an object moved within the collection. +.. important:: Order Matters + + In collection notification handlers, always apply changes + in the following order: + + 1. deletions + #. insertions + #. modifications + + Handling insertions before deletions may result in unexpected behavior. + +Get Notified of All Collection Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + To subscribe to collection notifications, call the :dotnet-sdk:`SubscribeForNotifications ` method. ``SubscribeForNotifications`` returns a subscription token which can be @@ -136,16 +150,17 @@ The following code shows how to observe a collection for changes. .. literalinclude:: /examples/generated/dotnet/WorkWithRealm.snippet.collection-notifications.cs :language: csharp -.. important:: Order Matters - - In collection notification handlers, always apply changes - in the following order: +Limit Notifications +~~~~~~~~~~~~~~~~~~~ - 1. deletions - #. insertions - #. modifications - - Handling insertions before deletions may result in unexpected behavior. +The SDK provides also provides a +:dotnet-sdk:`KeyPathsCollection `, which +provides a way to filter the fields that will trigger a notification. You pass +the ``KeyPathsCollection`` to the ``SubscribeForNotifications`` method. +The following code shows how to observe specific fields: + +.. literalinclude:: /examples/generated/dotnet/WorkWithRealm.snippet.field-notifications.cs + :language: csharp .. _dotnet-unregister-a-change-listener: