/ /

事务中的批量操作

Overview

在本指南中，您可以学习如何使用 MongoDB .NET/C# 驱动程序来执行事务。事务允许您运行一系列操作，这些操作在提交事务之前不会更改任何数据。如果事务中的任何操作返回错误，驱动程序就会取消事务，并在所有数据更改变得可见之前将其丢弃。

MongoDB 保证事务操作中涉及的数据保持一致，即使操作遇到意外错误。

会话

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.

使用 .NET/C# 驱动程序时，可以从 MongoClient 实例创建一个新会话，并将其类型定义为 IClientSession。我们建议您将客户端重复用于多个会话和事务，而不是每次都实例化新客户端。

以下示例展示了如何通过调用 StartSession() 方法来创建会话：

var client = new MongoClient("mongodb://localhost:27017");
var session = client.StartSession();

警告

仅应将 IClientSession 与创建它的 MongoClient（或关联的 MongoDatabase 或 MongoCollection）一起使用。将 IClientSession 与其他 MongoClient 一起使用会导致操作错误。

ClientSessionOptions

您可以通过将 ClientSessionOptions 类的实例传递给 StartSession() 方法来自定义会话行为。下表描述了可以在 ClientSessionOptions对象上设立的属性：

属性	说明
`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 Causal Consistency. Data Type: `boolean` 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 Default: `null`
`Snapshot`	Specifies whether the driver performs snapshot reads. To learn more about snapshot reads, see Read Concern "snapshot" in the MongoDB Server manual. Data Type: `boolean` Default: `false`
`SnapshotTime`	Specifies the cluster time at which the driver reads all data in the session. You must set `Snapshot` to `true` when setting this property. To learn more, see Read Concern "snapshot" in the MongoDB Server manual. Data Type: BsonTimestamp Default: `null`

DefaultTransactionOptions属性接受 TransactionOptions 类的实例。下表描述了可以在 TransactionOptions对象上设立的属性：

属性	说明
`MaxCommitTime`	Maximum amount of time that a single `commitTransaction` command can run. If the commit exceeds this limit, MongoDB Server returns a `MaxTimeMSExpired` error and doesn't commit the changes in the transaction. The driver doesn't retry the commit after this error. If you omit this property, MongoDB Server applies the default transaction runtime limit. Data Type: `TimeSpan?` Default: `null`
`ReadConcern`	Read concern for each transaction in the session. To learn more, see Read Concern in the MongoDB Server manual. If you omit this property, the transactions use the session-level read concern, if you set one. If you also omit the session-level read concern, the transactions use the client-level read concern. Data Type: ReadConcern Default: `null`
`ReadPreference`	Read preference for each transaction in the session. To learn more, see Read Preference in the MongoDB Server manual. If you omit this property, the transactions use the session-level read preference, if you set one. If you also omit the session-level read preference, the transactions use the client-level read preference. Data Type: ReadPreference Default: `null`
`WriteConcern`	Write concern for each transaction in the session. To learn more, see Write Concern in the MongoDB Server manual. If you omit this property, the transactions use the session-level write concern, if you set one. If you also omit the session-level write concern, the transactions use the client-level write concern. Data Type: WriteConcern Default: `null`

以下代码示例展示了如何使用自定义选项创建会话：

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

因果一致性(Causal Consistency)

MongoDB在某些客户端会话中实现因果一致性。因果一致性模型ACID 一致性保证在分布式系统中，会话中的操作按因果顺序运行。客户端观察到的结果与因果关系或操作之间的依赖关系一致。示例，如果您执行一系列操作，其中一个操作在逻辑上依赖于另一个操作的结果，则任何后续读取都会反映这种依赖关系。

为了保证因果一致性，客户端端会话必须满足以下要求：

启动会话时，驱动程序必须启用因果一致性选项。该选项默认启用。
操作必须在单个线程的单个会话中运行。否则，会话或线程必须相互传达optime和集群时间值。要查看传达这些值的两个会话的示例，请参阅MongoDB Server手册中的因果一致性示例。
您必须使用 ReadConcern.Majority读关注（read concern）。
您必须使用 WriteConcern.WMajority写关注（write concern）。这是默认的写关注（write concern）值。

下表描述了因果一致会话提供的ACID 一致性保证：

保证	说明
读取写入操作	读取操作会反映之前写入操作的结果。
单调读取	读取操作不会返回反映比先前读取操作更早的数据状态的结果。
单调写入	如果写入操作必须先于其他写入操作，则服务器会先运行此写入操作。示例，如果调用 `InsertOne()` 插入文档，然后调用 `UpdateOne()` 修改插入的文档，则服务器首先运行插入操作。
读取后写入	如果写入操作必须在其他读取操作之后执行，服务器会先执行读取操作。示例，如果您调用 `Find()` 来检索文档，然后调用 `DeleteOne()` 来删除检索到的文档，则服务器会先运行查找操作。

提示

要学习；了解有关本节中提到的概念的更多信息，请参阅以下MongoDB Server手册条目：

方法

在 MongoClient 实例上使用同步 StartSession() 或异步 StartSessionAsync() 方法创建 IClientSession。然后，您可以使用 IClientSession 接口提供的方法集来修改会话状态。从以下 Synchronous Methods 和 Asynchronous Methods 标签页中进行选择，了解管理事务的方法：

方法	说明
`StartTransaction()`	Starts a new transaction, configured with the given options, on this session. Throws an exception if there is already a transaction in progress for the session. To learn more about this method, see the startTransaction() page in the Server manual. Parameter: `TransactionOptions` (optional)
`AbortTransaction()`	Ends the active transaction for this session. Throws an exception if there is no active transaction for the session or the transaction has been committed or ended. To learn more about this method, see the abortTransaction() page in the Server manual. Parameter: `CancellationToken`
`CommitTransaction()`	Commits the active transaction for this session. Throws an exception if there is no active transaction for the session or if the transaction was ended. To learn more about this method, see the commitTransaction() page in the Server manual. Parameter: `CancellationToken`
`WithTransaction()`	在此会话上启动事务并运行给定的回调。要了解有关此方法的更多信息，请参阅服务器手册中的 withTransaction() 页面。 IMPORTANT: When catching exceptions within the callback function used by `WithTransaction()`, you must rethrow the exception before exiting the try-catch block. Failing to do so can result in an infinite loop. For further details on how to handle exceptions in this case, see Transactions in the Server manual and select C# from the language dropdown to view the example. 参数：`Func <IClientSessionHandle, CancellationToken, Task<TResult>>`、`TransactionOptions`、`CancellationToken` 返回类型：`Task <TResult>`

方法	说明
`StartTransaction()`	Starts a new transaction, configured with the given options, on this session. Throws an exception if there is already a transaction in progress for the session. To learn more about this method, see the startTransaction() page in the Server manual. Parameter: `TransactionOptions` (optional)
`AbortTransactionAsync()`	Ends the active transaction for this session. Throws an exception if there is no active transaction for the session or the transaction has been committed or ended. To learn more about this method, see the abortTransaction() page in the Server manual. Parameter: `CancellationToken` Return Type: `Task`
`CommitTransactionAsync()`	Commits the active transaction for this session. Throws an exception if there is no active transaction for the session or if the transaction was ended. To learn more about this method, see the commitTransaction() page in the Server manual. Parameter: `CancellationToken` Return Type: `Task`
`WithTransactionAsync()`	在此会话上启动事务并运行给定的回调。要了解有关此方法的更多信息，请参阅服务器手册中的 withTransaction() 页面。 IMPORTANT: When catching exceptions within the callback function used by `WithTransactionAsync()`, you must rethrow the exception before exiting the try-catch block. Failing to do so can result in an infinite loop. For further details on how to handle exceptions in this case, see Transactions in the Server manual and select C# from the language dropdown to view the example. 参数：`Func <IClientSessionHandle, CancellationToken, Task<TResult>>`、`TransactionOptions`、`CancellationToken` 返回类型：`Task <TResult>`

提示

配置事务

您可以通过将 TransactionOptions 类的实例传递给 StartTransaction() 或 WithTransaction() 方法来自定义单个事务的行为。您在此处设立的选项会覆盖您在 ClientSessionOptions对象上设立的默认ACID 事务选项。

例子

此示例展示了如何通过以下步骤创建会话、创建事务以及将文档插入到事务中的多个集合中：

使用 StartSession() 方法从客户端创建会话。
创建 TransactionOptions对象以配置ACID 事务。
使用 StartTransaction() 方法启动事务。
将文档插入 books 和 films 集合。
使用 CommitTransaction() 方法提交事务。

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!");
}

注意

不支持并行操作

.NET/ C#驱动程序不支持在单个ACID 事务中运行并行操作。

如果您使用的是MongoDB Server v8.0 或更高版本，则可以使用 BulkWrite() 或 BulkWriteAsync() 方法在单个ACID 事务中对多个命名空间执行写入操作。有关更多信息，请参阅批量写入操作。

事务中的批量操作

Overview

会话

ClientSessionOptions

因果一致性(Causal Consistency)

方法

例子

更多信息

API 文档