连接选项

本节介绍 .NET/C# 驱动程序支持的 MongoDB 连接和身份验证选项。您可以使用连接 URI 或 MongoClientSettings 对象配置连接。

使用连接 URI

如果将连接 URI 传递给 MongoClient 构造函数，则可以将连接选项作为 <name>=<value> 对包含在字符串中。在以下示例中，连接 URI 包含值为 60000 的 connectTimeoutMS 选项和值为 true 的 tls 选项：

using MongoDB.Driver;
// Sets the connection URIconst string connectionUri = "mongodb+srv://sample.host:27017/?connectTimeoutMS=60000&tls=true";
// Creates a new client and connects to the servervar client = new MongoClient(connectionUri);

运用 `MongoClientSettings`

您可以使用 MongoClientSettings 对象在代码中（而不是在连接 URI 中）配置连接设置。以这种方式配置连接可以更轻松地在运行时更改设置，帮助您在编译期间捕获错误，并提供比连接 URI 更多的配置选项。

要使用 MongoClientSettings对象，请创建该类的实例，设置其属性，并将其作为参数传递给 MongoClient 构造函数：

//const string connectionUri = "mongodb+srv://sample.host:27017/?connectTimeoutMS=60000&tls=true";
// Creates a MongoClientSettings objectvar settings = new MongoClientSettings(){    Scheme = ConnectionStringScheme.MongoDBPlusSrv,    Server = new MongoServerAddress("sample.host", 27017),    ConnectTimeout = new TimeSpan(0, 0, 60),    UseTls = true};
// Creates a new client and connects to the servervar client = new MongoClient(settings);

连接选项

下表列出了 MongoClientSettings 类中可用的每个连接选项，以及如何在连接字符串中实现相同的结果（如可能）。如果 MongoClientSettings 属性映射到连接字符串中的多个选项，则连接 URI 示例将显示所有相关选项。

注意

如果将查询参数用于时间段，其值必须以毫秒为单位。例如，要指定 60 秒，请使用值 60000。如果将 MongoClientSettings 对象用于时间段，请使用相应的 TimeSpan 值。

MongoClientSettings 属性	说明
AllowInsecureTls	指定是否尽可能放宽 TLS 约束。这可以包括允许无效证书或主机名错配。如果将此属性设置为 `true`，并将 `SslSettings.CheckCertificateRevocation` 设置为 `false`，则 .NET/C# 驱动程序将引发异常。数据类型：`boolean` 默认：`false` 连接 URI 示例：`tlsInsecure=true`
ApplicationName	驱动程序在连接握手过程中作为客户端元数据的一部分传递给服务器的应用名称。连接建立后，服务器会将此值打印到 MongoDB 日志中。该值还会记录在慢速查询日志和配置文件集合中。数据类型：`string` 默认：`null` 连接 URI 示例：`appName=yourApp`
AutoEncryptionOptions	客户端自动加密的设置。数据类型：AutoEncryptionOptions 默认：`null` 连接 URI 示例：N/A
ClusterConfigurator	套接字、TLS、集群等项目的低级配置选项。数据类型：Action<ClusterBuilder> 默认：`null` 连接 URI 示例：N/A
compressors	首选的压缩类型（按顺序），用于发送到或从服务器接收的传输协议消息。驱动程序使用服务器支持的第一个压缩类型。数据类型：CompressorConfiguration 默认：`null` 连接 URL 示例：`compressors=snappy,zstd`
ConnectTimeout	驱动程序在超时前尝试与服务器建立单个 TCP 套接字连接的时间长度。数据类型：`TimeSpan` 默认：30 秒连接 URI 示例：`connectTimeoutMS=0`
凭证	驱动程序如何对服务器进行身份验证的设置。这包括身份验证凭证、机制、源和其他设置。如果您未指定身份验证机制，驱动程序将使用 `SCRAM-SHA-1` 或`SCRAM-SHA-256` ，具体取决于服务器版本。有关可用的身份验证机制，请参阅身份验证机制。数据类型：MongoCredential 默认：`null` 连接 URI 示例： `mongodb://user1:password1&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:other,REALM:otherrealm&authSource=$external`
DirectConnection	指定是否强制将所有操作分派到托管。如果指定此选项，驱动程序将不接受 DNS 种子列表连接格式。必须使用标准连接 URI 格式。如果指定多个托管名，则必须将此属性设置为`false` 。数据类型：`boolean` 默认：`false` 连接 URI 示例：`directConnection=true`
HeartbeatInterval	定期服务器监控检查之间的时间间隔。必须大于或等于 500 毫秒。数据类型：`TimeSpan` 默认：10 秒连接 URI 示例：`heartbeatFrequencyMS=5000`
HeartbeatTimeout	监控套接字在超时之前可处于空闲状态的时间长度。数据类型：`TimeSpan` 默认：与 `ConnectTimeout` 相同连接 URI 示例：`heartbeatTimeoutMS=5000`
IPv6	指定托管地址是否为 IPv6 格式。数据类型：`boolean` 默认：`false` 连接 URI 示例：`ipv6=true`
IsFrozen	表示设置是否已冻结。无法更改冻结的设置。此选项为只读。数据类型：`boolean` 默认：`false` 连接 URI 示例：N/A
LinqProvider	要使用的 LINQ 提供商。数据类型：LinqProvider 默认：`LinqProvider.V3` 连接 URI 示例：N/A
LoadBalanced	指定驱动程序是否连接到负载均衡器。只有在以下情况下，您才能将此属性设置为 `true`：仅指定一个主机名。您没有连接到副本集。您没有使用 `SrvMaxHosts` 属性。您没有使用 `DirectConnection` 属性。数据类型：`boolean` 默认：`false` 连接 URI 示例：`loadBalanced=true`
LocalThreshold	服务器资格的延迟窗口。如果服务器的往返时间长于最快服务器的往返时间加上此值，则该服务器没有资格被选中。数据类型：`TimeSpan` 默认：15 毫秒连接 URI 示例：`localThresholdMS=0`
LoggingSettings	用于日志记录的设置。数据类型：LoggingSettings 默认：`null` 连接 URI 示例：N/A
MaxConnecting	驱动程序的连接池可以同时建立的最大连接数。数据类型：`integer` 默认：`2` 连接 URI 示例：`maxConnecting=3`
MaxConnectionIdleTime	在驱动程序关闭连接之前，该连接可以处于空闲状态的时间长度。数据类型：`TimeSpan` 默认：10 分钟连接 URI 示例：`maxIdleTimeMS=300000`
MaxConnectionLifeTime	连接在过期前可以建立连接池的时间长度。数据类型：`TimeSpan` 默认：30 分钟连接 URI 示例：`maxLifetimeMS=50000`
MaxConnectionPoolSize	驱动程序可在其连接池中创建的客户端或连接的最大数量。此计数包括正在使用的连接。数据类型：`integer` 默认：`100` 连接 URI 示例：`maxPoolSize=150`
MinConnectionPoolSize	驱动程序应创建并保持在连接池中的连接数，即使没有操作发生。此计数包括使用中的连接。数据类型：`integer` 默认：`0` 连接 URI 示例：`minPoolSize=1`
readConcern	客户端的默认读关注（read concern）。有关详细信息，请参阅读关注（read concern）。数据类型：ReadConcern 默认：`ReadConcern.Default` 连接 URI 示例：`readConcernLevel=local`
ReadEncoding	用于 string 反序列化的 UTF-8 编码。当遇到无效的 UTF-8 字节序列时，严格编码会抛出异常。数据类型：`UTF8Encoding` 默认：严格编码连接 URI 示例：不适用
读取偏好	客户端的默认读取偏好（read preference）设置。`MaxStaleness`表示从节点(secondary node from replica set)可以经历的最长复制延迟（以挂钟时间为单位），并且仍符合服务器选择条件。指定`-1` 意味着没有最大值。有关更多信息，请参阅读取偏好（read preference）。数据类型：ReadPreference 默认：`ReadPreference.Primary` 连接 URL 示例： `readPreference=primaryPreferred&maxStalenessSeconds=90&readPreferenceTags=dc:ny,rack:1` 您可以在连接 URI 中多次包含 `readPreferenceTags` 参数。如果这样做，客户端会将每个实例视为一个单独的标签集。URI 中标签的顺序决定了读取偏好的顺序。只有当读取偏好模式不是 `primary` 时，才可以使用此参数。
ReplicaSetName	要连接的副本集的名称。数据类型：`string` 默认：`null` 连接 URI 示例：`replicaSet=yourReplicaSet`
retryReads	允许重试读取。数据类型：`boolean` 默认：`true` 连接 URI 示例：`retryReads=false`
retryWrites	启用可重试写入。数据类型：`boolean` 默认：`true` 连接 URI 示例：`retryWrites=false`
有关	指定是使用标准连接字符串格式 (`MongoDB`) 还是 DNS 种子列表格式 (`MongoDBPlusSrv`)。有关连接字符串格式的更多信息，请参阅《MongoDB 手册》。如果将`DirectConnection` 属性设置为`true` ，并且您尝试使用 DNS 种子列表格式，则 .NET/C# 驱动程序将抛出异常。数据类型：ConnectionStringScheme 默认：`ConnectionStringScheme.MongoDB` 连接 URI 示例：`mongodb+srv://`
服务器	运行 MongoDB 的托管和端口号。数据类型：MongoServerAddress 默认：`localhost:27017` 连接 URI 示例：`mongodb://sample.host:27017`
ServerApi	允许选择 Stable API 版本控制。有关 Stable API 版本控制的更多信息，请参阅 MongoDB 手册。数据类型：ServerApi 默认：`null` 连接 URI 示例：N/A
ServerMonitoringMode	指定要使用的服务器监控协议。当此选项设置为`Auto` 时，监控模式由驱动程序运行的环境决定。该驱动程序在功能即服务 (FaaS) 环境中使用轮询模式，例如 Amazon Web Services Lambda，在其他环境中使用流媒体模式。数据类型: ServerMonitoringMode 默认: `Auto` 连接 URL 示例: `serverMonitoringMode=poll`
服务器	运行 MongoDB 的集群节点。数据类型：IEnumerable<MongoServerAddress> 默认：`localhost:27017` 连接 URI 示例：`mongodb://sample.host1:27017,sample.host2:27017`
ServerSelectionTimeout	驱动程序在超时之前尝试选择服务器的时间长度。数据类型：`TimeSpan` 默认：30 秒连接 URI 示例：`serverSelectionTimeoutMS=15000`
SocketTimeout	驱动程序在超时前尝试在套接字上发送或接收的时间长度。数据类型：`TimeSpan` 默认值：OS 默认值连接 URI 示例：`socketTimeoutMS=0`
SrvMaxHosts	初始填充种子列表或在 SRV 轮询期间向拓扑结构添加新主机时要随机选择的 SRV 结果的最大数量。仅当连接字符串模式设置为时才可以使用此属性。 `ConnectionStringScheme.MongoDBPlusSrv`连接到副本集时不能使用它。数据类型：`integer` 默认：`0` 连接 URI 示例：`srvMaxHosts=3`
SrvServiceName	SRV 资源记录的服务名称，驱动程序会检索该服务名称以构建您的种子列表。此属性会覆盖发现和轮询中 SRV 查找的默认服务名称。仅当连接字符串模式设置为 `ConnectionStringScheme.MongoDBPlusSrv` 时才可以使用此属性。连接到副本集时不能使用它。数据类型：`string` 默认：`"mongodb"` 连接 URI 示例：`srvServiceName="customname"`
SslSettings	TLS/SSL 选项，包括客户端证书、撤销处理以及启用和禁用的 TLS/SSL 协议。如果将`SslSettings.CheckCertificateRevocation` 设置为`false` ，并将 `AllowInsecureTls` 设置为`true` ，则 .NET/C# 驱动程序会抛出异常。数据类型：SslSettings 默认：`null` 连接 URI 示例：`tlsDisableCertificateRevocationCheck=false`
UseTls	指定是否需要 TLS 来连接到服务器。如果使用 `"mongodb+srv"` 方案或指定其他 TLS 选项，则此选项默认为 `true`。数据类型：`boolean` 默认值：`false` 连接 URL 示例：`tls=true`
WaitQueueTimeout	驱动程序在超时之前尝试从服务器的连接池检出连接的时间长度。数据类型：`TimeSpan` 默认：2 分钟连接 URI 示例：`waitQueueTimeoutMS=0`
writeConcern	客户端的默认写关注（write concern）设置，包括写入超时和日志记录。有关详细信息，请参阅写关注（write concern）。数据类型：WriteConcern 默认：`WriteConcern.Acknowledged` 连接 URI 示例：`w=majority&wTimeoutMS=0&journal=true`
WriteEncoding	指定 UTF-8 string 序列化是严格的还是宽松的。在严格编码情况下，当驱动程序遇到无效的 UTF-8 字节序列时，会抛出异常。数据类型：`UTF8Encoding` 默认：严格编码连接 URL 示例：不适用

连接选项

使用连接 URI

运用 MongoClientSettings

连接选项

运用 `MongoClientSettings`