优化 Azure Cosmos DB .NET SDK v3 的连接配置

项目
10/23/2024

重要

本文中的信息仅适用于 Azure Cosmos DB .NET SDK v3。有关详细信息，请参阅 Azure Cosmos DB SQL SDK 连接模式、Azure Cosmos DB .NET SDK v3 发行说明、Nuget 存储库和 Azure Cosmos DB .NET SDK v3 故障排除指南。如果你当前使用的是早于 v3 的版本，请参阅迁移到 Azure Cosmos DB .NET SDK v3 指南，获取升级到 v3 的相关帮助。

Azure Cosmos DB 是一个快速、弹性的分布式数据库，可以在提供延迟与吞吐量保证的情况下无缝缩放。凭借 Azure Cosmos DB，无需对体系结构进行重大更改或编写复杂的代码即可缩放数据库。扩展和缩减操作就像执行单个 API 调用或 SDK 方法调用一样简单。但是，由于 Azure Cosmos DB 通过网络调用进行访问，因此，使用 Azure Cosmos DB .NET SDK v3 时，可以通过连接配置优化来获得最佳性能。

连接配置

注意

在 Azure Cosmos DB .NETS SDK v3 中，直接模式在大多数情况下是为大多数工作负荷改善数据库性能的最佳选择。

若要详细了解不同的连接性选项，请参阅连接性模式一文。

直接连接模式

.NET SDK 的默认连接模式是直接连接模式。在直接模式下，使用 TCP 协议发出请求。在内部，直接模式使用特殊的体系结构来动态管理网络资源并获得最佳性能。在直接模式下采用的客户端体系结构使得网络利用率可预测，并实现对 Azure Cosmos DB 副本的多路访问。若要了解有关体系结构的详细信息，请参阅直接模式连接体系结构。

在 CosmosClientOptions 中创建 CosmosClient 实例时，可以配置连接模式。

CosmosClient client = new CosmosClient(
  "<nosql-account-endpoint>",
  tokenCredential
  new CosmosClientOptions
  {
      ConnectionMode = ConnectionMode.Gateway // ConnectionMode.Direct is the default
  }
);

自定义直接连接模式

可以通过传递给 CosmosClient 构造函数的 CosmosClientOptions 自定义直接模式。我们建议用户避免修改这些设置，除非用户明白其中的利弊关系，并且必需这样做。

配置选项	默认	建议	详细信息
EnableTcpConnectionEndpointRediscovery	true	true	表示启用检测从服务器关闭的连接的标志。
IdleTcpConnectionTimeout	默认情况下，空闲连接会无限期地保持为打开状态。	20 分钟 -24 小时	表示关闭未使用的连接之后的空闲时间。建议值介于 20 分钟到 24 小时之间。
MaxRequestsPerTcpConnection	30	30	表示通过单个 TCP 连接同时允许的请求数。当更多请求同时处于未完成状态时，直接/TCP 客户端会打开额外的连接。请勿将此值设置为低于每个连接四个请求或高于每个连接 50-100 个请求。对于每个连接具有较大并行度、具有大量请求或响应、或者延迟要求严格的应用程序，每个连接 8-16 个请求可能会获得更好的性能。
MaxTcpConnectionsPerEndpoint	65535	65535	表示可以打开到每个 Cosmos DB 后端的最大 TCP 连接数。此设置与 MaxRequestsPerTcpConnection 配合使用，限制同时发送到单个 Cosmos DB 后端 (MaxRequestsPerTcpConnection x MaxTcpConnectionPerEndpoint) 的请求数。值必须大于或等于 16。
OpenTcpConnectionTimeout	5 秒	1 秒	表示尝试建立连接所允许的时间。经过该时间后，将取消尝试并返回错误。较长的超时会延迟重试和失败。
PortReuseMode	PortReuseMode.ReuseUnicastPort	PortReuseMode.ReuseUnicastPort	表示传输堆栈使用的客户端端口重用策略。

注意

另请参阅直接连接模式的网络性能提示

自定义网关连接模式

可以通过传递给 CosmosClient 构造函数的 CosmosClientOptions 自定义网关模式。我们建议用户避免修改这些设置，除非用户明白其中的利弊关系，并且必需这样做。

配置选项	默认	建议	详细信息
GatewayModeMaxConnectionLimit	50	50	表示 Azure Cosmos DB 服务中目标服务终结点允许的最大并发连接数。
WebProxy	Null	Null	表示用于 Web 请求的代理信息。

注意

另请参阅使用 Azure Cosmos DB NET SDK v3 网关模式时的最佳做法。

后续步骤

若要详细了解 .NET SDK 的性能提示，请参阅 Azure Cosmos DB NET SDK v3 性能提示。

如果你只知道现有数据库群集中的 vCore 和服务器数量，请阅读根据 vCore 或 vCPU 数量估算请求单位数
若知道当前数据库工作负载的典型请求速率，请阅读使用 Azure Cosmos DB 容量计划工具估算请求单位

通过