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，以便在数个客户端计算机上实现高性能方案，请参阅使用 Azure Cosmos DB 进行性能和缩放测试。

若要深入了解如何设计应用程序以实现缩放和高性能，请参阅 Azure Cosmos DB 中的分区和缩放。

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

• 若知道当前数据库工作负载的典型请求速率，请阅读使用 Azure Cosmos DB 容量计划工具估算请求单位