diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 9e8102a6..f9049a47 100644 --- a/source/crud/transactions.txt +++ b/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,21 +27,33 @@ 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 ` is a grouping of related read or write operations that you intend to run sequentially. Sessions -enable :manual:`causal consistency -` for a +enable causal consistency for a group of operations or allow you to execute operations in an -:website:`ACID transaction `. MongoDB -guarantees that the data involved in your transaction operations remains -consistent, even if the operations encounter unexpected errors. +:website:`ACID transaction `. 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 @@ -49,6 +61,61 @@ instantiating a new client each time. ``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:``. + | + | **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" ` + 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