Docs 菜单
Docs 主页
/ / /
C#/.NET
/

Stable API

在此页面上

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

注意

Stable API 功能需要 MongoDB Server 5.0 或更高版本。

仅当您要连接的所有 MongoDB Server 都支持此功能时,才应使用 stable API 功能。

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

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

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

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

提示

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

如果您需要运行stable API未涵盖的命令,请确保禁用“strict”选项。 有关更多信息,请参阅有关stable API选项的部分。

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

  1. 构造一个ServerApi实例并指定 Stable API版本。

  2. 构造一个 MongoClientSettings 对象并设置 ServerApi 属性。

  3. 使用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的行为。

选项名称
说明
严格
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);

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

后退

Atlas Search