稳定API

本页内容

概述

在MongoDB客户端上启用稳定API
稳定API选项
API文档

注意

稳定API功能需要MongoDB服务器5.0或更高版本。

只有在你连接的所有MongoDB服务器都支持此功能时，才应使用稳定API功能。

概述

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

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

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

在MongoDB客户端上启用稳定API

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

提示

创建MongoClient之后，您不能更改其稳定API版本。如果您需要使用多个稳定API版本运行命令，请使用具有该版本的单独客户端。

如果您需要运行稳定API未涵盖的命令，请确保禁用了“严格”选项。有关更多信息，请参阅稳定API选项部分。

以下示例显示了如何实例化一个具有稳定API版本的MongoClient并通过以下操作连接到服务器

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

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

警告

如果您指定了一个API版本并连接到一个不支持稳定API的MongoDB服务器，当在您的MongoDB服务器上执行命令时，您的代码可能会抛出异常。如果您使用一个指定API版本以查询不支持该版本的 MongoClient，则查询可能会因包含以下文本的异常消息而失败

Unrecognized field 'apiVersion' on server...

稳定API选项

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

选项名称	描述
Strict	可选。当设置为 `true` 时，如果您调用不属于声明API版本的命令，驱动程序将抛出异常。默认值：false
DeprecationErrors	可选。当设置为 `true` 时，如果您调用在声明API版本中已弃用的命令，驱动程序将抛出异常。默认值：false

以下示例显示了如何构建 ServerApi 对象时设置这些选项

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

API文档

有关使用MongoDB .NET/C# Driver的稳定API的更多信息，请参阅以下API文档

Atlas搜索

下一步

身份验证