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..e7b3884408 --- /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 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 ` + +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. 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.