DOCSP-49811 - ClientSessionOptions (#627)

Author: mongoKart

source/crud/transactions.txt

@@ -1,15 +1,15 @@
 .. _csharp-transactions:
 
-============
-Transactions
-============
+================================
+Batch Operations in Transactions
+================================
 
 .. facet::
    :name: genre
    :values: reference
 
 .. meta::
-   :keywords: code example, multi-document
+   :keywords: code example, multi-document, atomic, acid
 
 .. contents:: On this page
    :local:
@@ -27,28 +27,95 @@ transaction is committed. If any operation in the transaction returns an
 error, the driver cancels the transaction and discards all data changes
 before they ever become visible.
 
+MongoDB guarantees that the data involved in your transaction operations remains
+consistent, even if the operations encounter unexpected errors.
+
+Sessions
+--------
+
 In MongoDB, transactions run within logical **sessions**. A
 :manual:`session </reference/server-sessions/>` is a grouping of related
 read or write operations that you intend to run sequentially. Sessions
-enable :manual:`causal consistency
-</core/read-isolation-consistency-recency/#causal-consistency>` for a
+enable causal consistency for a
 group of operations or allow you to execute operations in an
-:website:`ACID transaction </basics/acid-transactions>`. MongoDB
-guarantees that the data involved in your transaction operations remains
-consistent, even if the operations encounter unexpected errors.
+:website:`ACID transaction </basics/acid-transactions>`.
 
 When using the {+driver-short+}, you can create a new session from a
 ``MongoClient`` instance as an ``IClientSession`` type. We recommend that you reuse
 your client for multiple sessions and transactions instead of
 instantiating a new client each time.
 
+The following example shows how to create a session by calling the ``StartSession()``
+method:
+
+.. code-block:: csharp
+   :copyable: true
+
+   var client = new MongoClient("mongodb://localhost:27017");
+   var session = client.StartSession();
+
 .. warning::
 
    Use an ``IClientSession`` only with the ``MongoClient`` (or associated
    ``MongoDatabase`` or ``MongoCollection``) that created it. Using an
    ``IClientSession`` with a different ``MongoClient`` results in operation
    errors.
 
+ClientSessionOptions
+~~~~~~~~~~~~~~~~~~~~
+
+You can customize the behavior of your session by passing an instance of the
+``ClientSessionOptions`` class to the ``StartSession()`` method. The following table
+describes the properties that you can set on a ``ClientSessionOptions`` object:
+
+.. list-table::
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Property
+     - Description
+
+   * - ``CausalConsistency``
+     - | Specifies whether the session is causally consistent. In a causally consistent session,
+         the driver executes operations in the order they were issued. To learn more, see
+         :ref:`<csharp-causal-consistency>`.
+       |
+       | **Data Type**: {+bool-data-type+}
+       | **Default**: ``true``
+
+   * - ``DefaultTransactionOptions``
+     - | Specifies the default transaction options for the session. This includes the maximum commit
+         time, read concern, read preference, and write concern.
+       |
+       | **Data Type**: `TransactionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.TransactionOptions.html>`__ 
+       | **Default**: ``null``
+   
+   * - ``Snapshot``
+     - | Specifies whether the driver performs snapshot reads. To learn more about snapshot
+         reads, see :manual:`Read Concern "snapshot" </reference/read-concern-snapshot/>`
+         in the {+mdb-server+} manual.
+       |
+       | **Data Type**: {+bool-data-type+}
+       | **Default**: ``false``
+
+The following code example shows how to create a session with custom options:
+
+.. code-block:: csharp
+   :copyable: true
+
+   var client = new MongoClient("mongodb://localhost:27017");
+   var sessionOptions = new ClientSessionOptions
+   {
+       CausalConsistency = true,
+       DefaultTransactionOptions = new TransactionOptions(
+            readConcern:  ReadConcern.Available,
+            writeConcern:   WriteConcern.Acknowledged)
+   };
+
+   var session = client.StartSession(sessionOptions); 
+
+.. _csharp-causal-consistency:
+
 Causal Consistency
 ~~~~~~~~~~~~~~~~~~
 
@@ -94,7 +161,7 @@ tabs to learn about the methods to manage your transaction:
         :tabid: synchronous-methods
 
         .. list-table::
-            :widths: 40 60
+            :widths: 30 70
             :header-rows: 1
 
             * - Method