/ /

/ /

在C#中使用事务

Overview

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

在 MongoDB 中，事务在逻辑会话中运行。会话是一组要按顺序运行的相关读取或写入操作。会话可以实现一组操作的因果一致性，或支持在 ACID 事务中执行操作。MongoDB 保证事务操作中涉及的数据保持一致，即使操作遇到意外错误。

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

警告

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

方法

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

方法	说明
`StartTransaction()`	在该会话上启动使用给定选项配置的新事务。如果会话已存在正在进行的事务，则抛出异常。要了解有关该方法的更多信息，请参阅服务器手册中的startTransaction() 页面。参数：`TransactionOptions` （可选）
`AbortTransaction()`	终止此会话的活动事务。如果会话没有活动事务，或事务已提交或结束，则抛出异常。要了解有关此方法的更多信息，请参阅服务器手册中的 abortTransaction() 页面。参数：`CancellationToken`
`CommitTransaction()`	提交此会话的活动事务。如果此会话没有活动事务或事务已结束，则抛出异常。要了解有关此方法的更多信息，请参阅服务器手册中的 commitTransaction() 页面。参数：`CancellationToken`
`WithTransaction()`	在此会话上启动事务并运行给定的回调。要了解有关此方法的更多信息，请参阅服务器手册中的 withTransaction() 页面。重要提示：在 `WithTransaction()`使用的回调函数中捕获异常时，必须在退出 try-catch区块之前重新抛出异常。否则可能会导致无限循环。有关如何处理这种情况下的异常的更多详细信息，请参阅《服务器》手册中的“事务”，并从语言下拉列表中选择 C#以查看示例。参数：`Func <IClientSessionHandle, CancellationToken, Task<TResult>>`、`TransactionOptions`、`CancellationToken` 返回类型：`Task <TResult>`

方法	说明
`StartTransaction()`	在该会话上启动使用给定选项配置的新事务。如果会话已存在正在进行的事务，则抛出异常。要了解有关该方法的更多信息，请参阅服务器手册中的startTransaction() 页面。参数：`TransactionOptions` （可选）
`AbortTransactionAsync()`	终止此会话的活动事务。如果会话没有活动事务，或事务已提交或结束，则抛出异常。要了解有关此方法的更多信息，请参阅服务器手册中的 abortTransaction() 页面。参数：`CancellationToken` 返回类型：`Task`
`CommitTransactionAsync()`	提交此会话的活动事务。如果此会话没有活动事务或事务已结束，则抛出异常。要了解有关此方法的更多信息，请参阅服务器手册中的 commitTransaction() 页面。参数：`CancellationToken` 返回类型：`Task`
`WithTransactionAsync()`	在此会话上启动事务并运行给定的回调。要了解有关此方法的更多信息，请参阅服务器手册中的 withTransaction() 页面。重要提示：在 `WithTransactionAsync()`使用的回调函数中捕获异常时，必须在退出 try-catch区块之前重新抛出异常。否则可能会导致无限循环。有关如何处理这种情况下的异常的更多详细信息，请参阅《服务器》手册中的“事务”，并从语言下拉列表中选择 C#以查看示例。参数：`Func <IClientSessionHandle, CancellationToken, Task<TResult>>`、`TransactionOptions`、`CancellationToken` 返回类型：`Task <TResult>`

事务选项

要配置单个ACID 事务，请将 TransactionOptions实例传递给 StartTransaction() 或 WithTransaction() 方法。本节中的示例将读关注（read concern）设置为 ReadConcern.Majority，写关注（write concern）为 WriteConcern.WMajority。

您可以使用以下属性配置 TransactionOptions对象：

属性	说明
`MaxCommitTime`	单个 `commitTransaction` 命令可以运行的最长时间。如果提交超过此限制，MongoDB Server 将返回 `MaxTimeMSExpired` 错误并不提交事务。如果您省略此属性，MongoDB Server 将应用默认事务运行时间限制。数据类型：`TimeSpan?`
`ReadConcern`	事务的读关注（read concern）。要了解更多信息，请参阅 MongoDB Server 手册中的读关注（read concern）。数据类型：ReadConcern
`ReadPreference`	事务的读取偏好（read preference）。要了解更多信息，请参阅 MongoDB Server 手册中的读取偏好（read preference）。数据类型：ReadPreference
`WriteConcern`	事务的写关注（write concern）。要学习更多信息，请参阅 MongoDB Server 手册中的写关注（write concern）。数据类型：WriteConcern

例子

此示例展示了如何通过以下步骤创建会话、配置ACID 事务选项、创建ACID 事务以及将文档插入到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!");
}

Successfully committed transaction!

注意

不支持并行操作

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

在C#中使用事务

Overview

警告

方法

事务选项

例子

注意

不支持并行操作

更多信息

API 文档