/ /

连接选项

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

使用连接 URI

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

using MongoDB.Driver;
// Sets the connection URI
const string connectionUri = "mongodb+srv://sample.host:27017/?connectTimeoutMS=60000&tls=true";
// Creates a new client and connects to the server
var 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 object
var 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 server
var 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 示例：不适用

后退

连接指南

来年

配置 TLS

连接选项

使用连接 URI

运用 MongoClientSettings

连接选项

注意

运用 `MongoClientSettings`