Stable API

Overview

在本指南中，您可以了解如何在连接 MongoDB 实例或副本集时指定“Stable API”兼容性。

stable API功能会强制服务器以与您指定的API版本兼容的行为来运行操作。更新驱动程序或服务器时，API 版本会发生变化，这可能会改变这些操作的行为方式。使用stable API可确保服务器响应一致，并为应用程序提供长期的API稳定性。

以下部分介绍如何为MongoDB客户端启用和自定义 Stable API 。有关 Stable API的更多信息，包括其涵盖的命令列表，请参阅 MongoDB参考页面。

在 MongoDB 客户端上启用稳定 API

要启用 Stable API，您必须在 MongoDB 客户端的设置中指定 API 版本。一旦您使用指定的 API 版本实例化 MongoClient实例，您使用客户端运行的所有命令都将使用该版本的 Stable API。

提示

创建 MongoClient 后，就无法更改其 Stable API版本。如果您必须使用多个版本的 Stable API运行命令，请使用该版本实例化一个单独的客户端。

如果必须运行Stable API未涵盖的命令，请确保禁用“strict”选项。有关更多信息，请参阅“稳定API选项”部分。

以下示例展示如何使用 Stable API 版本实例化 MongoClient，并通过以下操作连接到服务器：

构造一个ServerApi实例并指定 Stable API版本。
构造一个 MongoClientSettings 对象并设置 ServerApi 属性。
使用MongoClientSettings对象创建MongoClient 。

var serverApi = new ServerApi(ServerApiVersion.V1);
var settings = new MongoClientSettings { ServerApi = serverApi };
var client = new MongoClient(settings);

警告

如果您指定 API 版本并连接到不支持 Stable API 的 MongoDB 服务器，那么您的代码在 MongoDB 服务器上执行命令时可能会引发异常。如果您使用指定 API 版本的 MongoClient 来查询不支持该版本的服务器，查询可能会失败，并显示包含以下文本的异常消息：

Unrecognized field 'apiVersion' on server...

Stable API 选项

您可以使用下表中的选项自定义stable API的行为。

选项名称	说明
严格	Optional. When `true`, if you call a command that is not part of the declared API version, the driver raises an exception. Default: false
deprecationErrors	Optional. When `true`, if you call a command that is deprecated in the declared API version, the driver raises an exception. Default: false

以下示例展示了如何在构造ServerApi对象时设置这些选项：

var serverApi = new ServerApi(ServerApiVersion.V1, strict: true,
    deprecationErrors: true);

API 文档

有关将stable API与MongoDB .NET / C#驱动程序结合使用的更多信息，请参阅以下API文档：

后退

自定义MongoDB Server选择

来年

连接池