From 3810e868367d9205c11c476e0e03501b99ecfb0d Mon Sep 17 00:00:00 2001 From: mongocaleb Date: Thu, 15 Oct 2020 11:48:53 -0700 Subject: [PATCH 1/3] WIP --- source/dotnet/open-a-realm.txt | 27 +------- source/dotnet/quick-start.txt | 2 + source/dotnet/sync-data.txt | 70 ++++++++++++++++++++ source/dotnet/threading.txt | 2 + source/includes/dotnet-open-synced-realm.rst | 25 +++++++ 5 files changed, 102 insertions(+), 24 deletions(-) create mode 100644 source/dotnet/sync-data.txt create mode 100644 source/includes/dotnet-open-synced-realm.rst diff --git a/source/dotnet/open-a-realm.txt b/source/dotnet/open-a-realm.txt index a4735fd906..2b57548e86 100644 --- a/source/dotnet/open-a-realm.txt +++ b/source/dotnet/open-a-realm.txt @@ -12,33 +12,12 @@ Open and Close a Realm :depth: 2 :class: singlecol +.. _dotnet-open-synced-realm: + Open a Synced Realm ------------------- -To open a synced {+realm+}, call the -:dotnet-sdk:`GetInstanceAsync() ` -method, passing in a -:dotnet-sdk:`SyncConfiguration ` -object that includes the partition name and -the user. The following code demonstrates this: - -.. literalinclude:: /examples/generated/code/start/Examples.codeblock.open-synced-realm.cs - :language: csharp - -In the above example, the code shows how to open the {+realm+} *asynchronously* -by calling ``GetInstanceAsync()``. You can also open a {+realm+} *synchronously* -by calling the -:dotnet-sdk:`GetInstance() ` -method, which is necessary if the device is offline. - -.. literalinclude:: /examples/generated/code/start/Examples.codeblock.open-synced-realm-sync.cs - :language: csharp - -.. note:: - The first time a user logs on to your realm app, you should open the realm - *asynchronously* to sync data from the server to the device. After that initial - connection, you can open a realm *synchronously* to ensure the app works in - an offline state. +.. include:: /includes/dotnet-open-synced-realm.rst Open a Local (Non-Synced) Realm ------------------------------- diff --git a/source/dotnet/quick-start.txt b/source/dotnet/quick-start.txt index ff8ef77ef0..53a22caf7d 100644 --- a/source/dotnet/quick-start.txt +++ b/source/dotnet/quick-start.txt @@ -80,6 +80,8 @@ attribute so we can use .NET-friendly casing on our property names. .. literalinclude:: /examples/generated/code/final/RealmTask.cs :language: csharp +.. _dotnet-quick-start-authenticate: + Authenticate a User ------------------- diff --git a/source/dotnet/sync-data.txt b/source/dotnet/sync-data.txt new file mode 100644 index 0000000000..cb190c431e --- /dev/null +++ b/source/dotnet/sync-data.txt @@ -0,0 +1,70 @@ +.. _dotnet-sync-data: + +========= +Sync Data +========= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. include:: /includes/sync-beta-note.rst + +Prerequisites +------------- + +Before you can access a synced {+realm+} from the client, you must: + +- :ref:`Enable sync ` in the {+ui+}. + +- :ref:`Authenticate a user ` in + your client project. + +Open a Synced Realm +------------------- + +.. include:: /includes/dotnet-open-synced-realm.rst + +The :ref:`partition value ` specifies which subset of your data to sync. +This is typically a user ID, project ID, store ID, or some other category identifier in +your app that has particular relevance to the current user. + +.. seealso:: :ref:`Partition Atlas Data into Realms ` + + +Sync Data +--------- + +The syntax to :ref:`read ` and :ref:`write +` on a synced {+realm+} is identical to the syntax +for non-synced {+realms+}. While you work with local data, a background thread +efficiently integrates, uploads, and downloads changesets. + +.. admonition:: When Using Sync, Avoid Writes on the Main Thread + :class: important + + The fact that {+service-short+} performs sync integrations on a background thread means + that if you write to your {+realm+} on the main thread, there's a small chance your UI + could appear to hang as it waits for the background sync thread to finish a write + transaction. Therefore, it's a best practice :ref:`never to write on the main thread + when using {+sync+} `. + +The following code reads a collection of ``Task`` objects, then writes a +new ``Task`` to the {+realm+}: + +.. TODO + +.. seealso:: :ref:`Threading ` + +Summary +------- + +- Open a synced {+realm+} with the configuration object generated when you pass + a :term:`partition value` to the user object's ``SyncConfiguration`` Builder. +- Compared to using a non-synced {+realm+}, there is no special syntax for reading + from, writing to, or watching objects on a synced {+realm+}. +- You should avoid writing to a synced {+realm+} on the main thread. diff --git a/source/dotnet/threading.txt b/source/dotnet/threading.txt index ba63b1c972..da5ddffc9a 100644 --- a/source/dotnet/threading.txt +++ b/source/dotnet/threading.txt @@ -31,6 +31,8 @@ maintainable multithreaded code that avoids issues like deadlocking and race conditions. {+service+} aims to simplify this for you. +.. _dotnet-threading-three-rules: + Three Rules to Keep in Mind ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/includes/dotnet-open-synced-realm.rst b/source/includes/dotnet-open-synced-realm.rst new file mode 100644 index 0000000000..593b892392 --- /dev/null +++ b/source/includes/dotnet-open-synced-realm.rst @@ -0,0 +1,25 @@ +To open a synced {+realm+}, call the +:dotnet-sdk:`GetInstanceAsync() ` +method, passing in a +:dotnet-sdk:`SyncConfiguration ` +object that includes the partition name and +the user. The following code demonstrates this: + +.. literalinclude:: /examples/generated/code/start/Examples.codeblock.open-synced-realm.cs + :language: csharp + +In the above example, the code shows how to open the {+realm+} *asynchronously* +by calling ``GetInstanceAsync()``. You can also open a {+realm+} *synchronously* +by calling the +:dotnet-sdk:`GetInstance() ` +method, which is necessary if the device is offline. + +.. literalinclude:: /examples/generated/code/start/Examples.codeblock.open-synced-realm-sync.cs + :language: csharp + +.. note:: + + The first time a user logs on to your realm app, you should open the realm + *asynchronously* to sync data from the server to the device. After that initial + connection, you can open a realm *synchronously* to ensure the app works in + an offline state. From f334c77ca453880a6b65de5a953e7c5da0eee57d Mon Sep 17 00:00:00 2001 From: mongocaleb Date: Thu, 15 Oct 2020 12:08:55 -0700 Subject: [PATCH 2/3] add example code --- source/dotnet/sync-data.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/dotnet/sync-data.txt b/source/dotnet/sync-data.txt index cb190c431e..a7c3eb31d0 100644 --- a/source/dotnet/sync-data.txt +++ b/source/dotnet/sync-data.txt @@ -53,10 +53,10 @@ efficiently integrates, uploads, and downloads changesets. transaction. Therefore, it's a best practice :ref:`never to write on the main thread when using {+sync+} `. -The following code reads a collection of ``Task`` objects, then writes a -new ``Task`` to the {+realm+}: +The following code creates a new ``Task`` object and writes it to the {+realm+}: -.. TODO +.. literalinclude:: /examples/generated/code/start/Examples.codeblock.create.cs + :language: csharp .. seealso:: :ref:`Threading ` From c3b3bf0494f2335ea253a55811f072cb9768f8bb Mon Sep 17 00:00:00 2001 From: mongocaleb Date: Thu, 15 Oct 2020 13:15:50 -0700 Subject: [PATCH 3/3] review --- source/dotnet/sync-data.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/dotnet/sync-data.txt b/source/dotnet/sync-data.txt index a7c3eb31d0..e7b3884408 100644 --- a/source/dotnet/sync-data.txt +++ b/source/dotnet/sync-data.txt @@ -66,5 +66,5 @@ Summary - Open a synced {+realm+} with the configuration object generated when you pass a :term:`partition value` to the user object's ``SyncConfiguration`` Builder. - Compared to using a non-synced {+realm+}, there is no special syntax for reading - from, writing to, or watching objects on a synced {+realm+}. + from, writing to, or observing objects on a synced {+realm+}. - You should avoid writing to a synced {+realm+} on the main thread.