Azure Cosmos DB .NET SDK 的最佳做法

适用范围： NoSQL

本文演示使用 Azure Cosmos DB .NET SDK 的最佳做法。 通过遵循这些做法，可帮助你提高延迟、可用性并提高整体性能。

清单

捕获诊断

SDK 中的所有响应（包括 CosmosException）都具有 Diagnostics 属性。 此属性记录与单一请求相关的所有信息，包括是否发生重试或任何瞬时故障。

诊断以字符串形式返回。 字符串会随每个版本而不断变化并进行改进，以对不同场景进行故障排除。 对于 SDK 的每个版本，字符串对格式设置都有中断性变更。 为避免破坏性变更，请勿解析字符串。 以下代码示例展示了如何使用 .NET SDK 读取诊断日志：

try
{
    ItemResponse<Book> response = await this.Container.CreateItemAsync<Book>(item: testItem);
    if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan)
    {
        // Log the response.Diagnostics.ToString() and add any additional info necessary to correlate to other logs 
    }
}
catch (CosmosException cosmosException)
{
    // Log the full exception including the stack trace with: cosmosException.ToString()
    
    // The Diagnostics can be logged separately if required with: cosmosException.Diagnostics.ToString()
}

// When using Stream APIs
ResponseMessage response = await this.Container.CreateItemStreamAsync(partitionKey, stream);
if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan || !response.IsSuccessStatusCode)
{
    // Log the diagnostics and add any additional info necessary to correlate to other logs with: response.Diagnostics.ToString()
}

适用于 HTTP 连接的最佳做法

无论配置的连接模式如何，.NET SDK 都会使用 HttpClient 来执行 HTTP 请求。

• 在 直接模式 下，HTTP 用于元数据操作。
• 在网关模式下，HTTP 用于数据平面和元数据操作。

HttpClient 的基础知识之一是通过HttpClient来确保 可以响应帐户上的 DNS 更改。 只要共用连接保持打开状态，它们就不会对 DNS 更改做出反应。 此设置强制定期关闭共用连接，确保应用程序对 DNS 更改做出反应。 建议根据 连接模式 和工作负荷自定义此值，以平衡频繁创建新连接的性能效果，并需要响应 DNS 更改（可用性）。 设定一个 5 分钟的时间值将是一个良好的开始，如果它会影响性能，特别是在网关模式下，可以增加此值。

可以通过 CosmosClientOptions.HttpClientFactory 注入自定义 HttpClient，例如：

// Use a Singleton instance of the SocketsHttpHandler, which you can share across any HttpClient in your application
SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
// Customize this value based on desired DNS refresh timer
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5);

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    // Pass your customized SocketHttpHandler to be used by the CosmosClient
    // Make sure `disposeHandler` is `false`
    HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
};

// Use a Singleton instance of the CosmosClient
return new CosmosClient("<connection-string>", cosmosClientOptions);

如果使用 .NET 依赖项注入，则可以简化单一实例过程：

SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
// Customize this value based on desired DNS refresh timer
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5);
// Registering the Singleton SocketsHttpHandler lets you reuse it across any HttpClient in your application
services.AddSingleton<SocketsHttpHandler>(socketsHttpHandler);

// Use a Singleton instance of the CosmosClient
services.AddSingleton<CosmosClient>(serviceProvider =>
{
    SocketsHttpHandler socketsHttpHandler = serviceProvider.GetRequiredService<SocketsHttpHandler>();
    CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
    {
        HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
    };

    return new CosmosClient("<connection-string>", cosmosClientOptions);
});

使用网关模式时的最佳做法

使用网关模式时，增加每台主机的 System.Net MaxConnections。 使用网关模式时，Azure Cosmos DB 请求是通过 HTTPS/REST 发出的。 这些请求受制于每个主机名或 IP 地址的默认连接限制。 可能需要将 MaxConnections 设置为较大的值（从 100 到 1,000），以便客户端库能够同时使用多个连接来访问 Azure Cosmos DB。 在 .NET SDK 1.8.0 及更高版本中，ServicePointManager.DefaultConnectionLimit 的默认值为 50。 若要更改该值，可以将 CosmosClientOptions.GatewayModeMaxConnectionLimit 设置为较高的值。

具有大量写入操作的工作负载的最佳做法

对于需要处理大量创建负载的工作负荷，请将 EnableContentResponseOnWrite 请求选项设置为 false。 该服务不再将已创建或更新的资源返回到 SDK。 通常，因为应用程序具有正在创建的对象，因此不需要服务即可将其返回。 标头值仍可访问，例如请求费用。 禁用内容响应有助于提高性能，因为 SDK 不再需要分配内存或序列化响应正文。 此外还会降低网络带宽的使用率，从而进一步提高性能。

适用于多租户应用的最佳做法

如果多租户在使用多个应用，且每个租户由同一 Azure Cosmos DB 帐户内的不同数据库、容器或分区键表示，则应使用单个客户端实例。 单一客户端实例可与一个帐户中的所有数据库、容器和分区键进行交互，是采用单一实例模式的最佳做法。

不过，当每个租户由不同的 Azure Cosmos DB 帐户表示时，需要为每个帐户创建单独的客户端实例。 虽然单一实例模式仍适用于每个客户端（在应用生命周期内，每个帐户的每个客户端），但如果租户数量较多，则客户端数量可能很难管理。 连接数量可能会超出计算环境的上限，导致连接问题。

此类情况下，建议采取以下做法：

• 了解计算环境的上限（CPU 和连接资源）。 建立在条件允许时，使用拥有至少 4 核与 8GB 内存的虚拟机。
• 根据计算环境的上限来确定单个计算实例可以处理的客户端实例数量，继而确定有多少租户。 可以根据所选的连接模式估算每个客户端打开 的连接数 。
• 评估租户在各实例之间的分布情况。 如果每个实例可以成功处理一定数量的租户，则随着租户数量越来越多，可通过负载均衡以及将租户路由到其他计算实例来进行缩放。
• 如果工作负载零星地分散在各处，请考虑使用“最不常用的”缓存作为结构来保存客户端实例，并清理某个时间范围内未被访问的租户的客户端。 在 .NET 中，选项之一是 MemoryCacheEntryOptions。在此选项中，可以使用 RegisterPostEvictionCallback 来清理非活动客户端，并使用 SetSlidingExpiration 来定义保存非活动连接的最长时间。
• 使用网关模式进行评估以减少网络连接数。
• 使用直接模式时，请考虑在直接模式配置上调整 CosmosClientOptions.IdleTcpConnectionTimeout 和 CosmosClientOptions.PortReuseMode，以关闭未使用的连接并控制连接量。

后续步骤

• 使用基准测试框架衡量 Azure Cosmos DB for NoSQL 性能
• Azure Cosmos DB 中的分区和水平缩放

尝试为迁移到 Azure Cosmos DB 进行容量规划？ 可以使用有关现有数据库群集的信息进行容量规划。

• 如果知道当前数据库工作负荷的典型请求速率，请参阅 使用 Azure Cosmos DB 容量规划器估算 RU/秒