/ /

连接选项

本节介绍 .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 示例：不适用

ClusterConfigurator

套接字、TLS、集群等的低级配置选项。数据类型：Action

默认值：null
连接 URI 示例：不适用

compressors

按顺序排列的首选压缩类型，适用于发送到服务器接收的线协议消息。驾驶员使用服务器支持的第一种压缩类型。数据类型：CompressorConfiguration
默认值：null
连接 URI 示例：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 示例：不适用

LoadBalanced

指定驱动程序是否连接到负载均衡器。只有在以下情况下，您才能将此
属性设置为 true：

仅指定一个主机名。
您没有连接到副本集。
您没有使用 SrvMaxHosts 属性。
您没有使用 DirectConnection 属性。

数据类型：boolean
默认：false
连接 URI 示例：loadBalanced=true

LocalThreshold

服务器资格的延迟窗口。

如果服务器的往返时间长于最快服务器的往返时间加上此值，则该服务器没有资格被选中。

数据类型：TimeSpan
默认：15 毫秒
连接 URI 示例：localThresholdMS=0

LoggingSettings

用于日志记录的设置。数据类型：LoggingSettings
默认值：null
连接 URI 示例：不适用

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

The client's default read concern.
See read concern for more information.

Data Type: ReadConcern
Default: ReadConcern.Default
Connection URI Example: readConcernLevel=local

ReadEncoding

用于 string 反序列化的 UTF-8 编码。
当遇到无效的 UTF-8
字节序列时，严格编码会抛出异常。

数据类型：UTF8Encoding
默认：严格编码
连接 URI 示例：不适用

读取偏好

客户端的默认读取偏好设置。MaxStaleness 表示从节点(secondary
node from replica
set)可能出现但仍有资格进行服务器选择的最长复制延迟（以挂钟时间为单位）。指定意味着没有最大值。有关更多信息，请读取偏好（read-1

preference）。数据类型：ReadPreference
默认值：ReadPreference.Primary
连接 URI 示例：

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 示例：不适用

ServerMonitoringMode

指定要使用的服务器监控协议。当此选项设立为
Auto
时，监控模式由驾驶员运行的环境决定。驾驶员在函数即服务
(FaaS)
环境（例如 AWS Lambda

）中使用轮询模式，在其他环境中使用流媒体模式。数据类型：ServerMonitoringMode
默认值：Auto
连接 URI 示例：serverMonitoringMode=poll

服务器

The cluster members where MongoDB is running.

Data Type: IEnumerable<MongoServerAddress>
Default: localhost:27017
Connection URI Example: 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

The service name of the SRV resource records
that the driver retrieves to construct your seedlist. This
property overrides the default service name for SRV lookup in
discovery and polling.

You can use this property only if the connection-string scheme is set
to ConnectionStringScheme.MongoDBPlusSrv. You cannot use it when connecting
to a replica set.

Data Type: string
Default: "mongodb"
Connection URI Example: 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）。数据类型：WriteConcern
默认值：WriteConcern.Acknowledged
连接 URI 示例：w=majority&wTimeoutMS=0&journal=true

WriteEncoding

指定 UTF-8 string 序列化是严格的还是宽松的。
在严格编码情况下，当驱动程序遇到无效的
UTF-8 字节序列时，会抛出异常。

数据类型：UTF8Encoding
默认：严格编码
连接 URL 示例：不适用

连接选项

使用连接 URI

运用 MongoClientSettings

连接选项

运用 `MongoClientSettings`