Use Transactions in C#

Overview

In this guide, you can learn how to use the MongoDB .NET/C# Driver to perform transactions. Transactions allow you to run a series of operations that do not change any data until the 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.

In MongoDB, transactions run within logical sessions. A session is a grouping of related read or write operations that you intend to run sequentially. Sessions enable causal consistency for a group of operations or allow you to execute operations in an ACID transaction. MongoDB guarantees that the data involved in your transaction operations remains consistent, even if the operations encounter unexpected errors.

When using the .NET/C# Driver, 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.

Methods

Create an IClientSession by using either the synchronous StartSession() or the asynchronous StartSessionAsync() method on your MongoClient instance. You can then modify the session state by using the method set provided by the IClientSession interface. Select from the following Synchronous Methods and Asynchronous Methods tabs to learn about the methods to manage your transaction:

Transaction Options

To configure an individual transaction, pass a TransactionOptions instance to the StartTransaction() or WithTransaction() method. The example in this section sets the read concern to ReadConcern.Majority and the write concern to WriteConcern.WMajority.

You can configure a TransactionOptions object with the following properties:

Example

This example shows how you can create a session, configure transaction options, create a transaction, and insert documents into multiple collections within the transaction through the following steps:

1. Create a session from the client by using the StartSession() method.

2. Create a TransactionOptions object to configure the transaction.

3. Use the StartTransaction() method to start a transaction.

4. Insert documents into the books and films collections.

5. Commit the transaction by using the CommitTransaction() method.

var books = database.GetCollection<Book>("books");
var films = database.GetCollection<Film>("films");
// Begins transaction
using (var session = mongoClient.StartSession())
{
    // Configures transaction options
    var transactionOptions = new TransactionOptions(
        readConcern: ReadConcern.Majority,
        writeConcern: WriteConcern.WMajority
    );
    session.StartTransaction(transactionOptions);
    try
    {
        // Creates sample data
        var book = new Book
        {
            Title = "Beloved",
            Author = "Toni Morrison",
            InStock = true
        };
        var film = new Film
        {
            Title = "Star Wars",
            Director = "George Lucas",
            InStock = true
        };
        // Inserts sample data
        books.InsertOne(session, book);
        films.InsertOne(session, film);
        // Commits our transaction
        session.CommitTransaction();
    } 
    catch (Exception e)
    {
        Console.WriteLine("Error writing to MongoDB: " + e.Message);
        return;
    }
    // Prints a success message if no error thrown
    Console.WriteLine("Successfully committed transaction!");
}

Successfully committed transaction!

Additional Information

To learn more about the concepts mentioned in this guide, see the following pages in the Server manual:

• Transactions

• Server Sessions

• Read Isolation, Consistency, and Recency