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。
提示
以下示例展示如何使用 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文档: