Syncdata (#549)

SyncData

Author: MongoCaleb

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() <reference/Realms.Realm.html#Realms_Realm_GetInstanceAsync_Realms_RealmConfigurationBase_System_Threading_CancellationToken_>` 
-method, passing in a 
-:dotnet-sdk:`SyncConfiguration <reference/Realms.Sync.SyncConfiguration.html>` 
-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() <reference/Realms.Realm.html#Realms_Realm_GetInstance_System_String_>` 
-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
 -------------------------------

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
 -------------------
 

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 <enable-sync>` in the {+ui+}.
+
+- :ref:`Authenticate a user <dotnet-quick-start-authenticate>` in
+  your client project.
+
+Open a Synced Realm
+-------------------
+
+.. include:: /includes/dotnet-open-synced-realm.rst
+
+The :ref:`partition value <partitioning>` 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 <partitioning>`
+
+
+Sync Data
+---------
+
+The syntax to :ref:`read <dotnet-realm-database-reads>` and :ref:`write
+<dotnet-realm-database-writes>` 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+} <dotnet-threading-three-rules>`.
+
+The following code creates a new ``Task`` object and writes it to the {+realm+}:
+
+.. literalinclude:: /examples/generated/code/start/Examples.codeblock.create.cs
+   :language: csharp
+
+.. seealso:: :ref:`Threading <dotnet-client-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 observing objects on a synced {+realm+}.
+- You should avoid writing to a synced {+realm+} on the main thread.

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/includes/dotnet-open-synced-realm.rst

@@ -0,0 +1,25 @@
+To open a synced {+realm+}, call the 
+:dotnet-sdk:`GetInstanceAsync() <reference/Realms.Realm.html#Realms_Realm_GetInstanceAsync_Realms_RealmConfigurationBase_System_Threading_CancellationToken_>` 
+method, passing in a 
+:dotnet-sdk:`SyncConfiguration <reference/Realms.Sync.SyncConfiguration.html>` 
+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() <reference/Realms.Realm.html#Realms_Realm_GetInstance_System_String_>` 
+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.