Azure Cosmos DB .NET SDK 的最佳做法

適用於：NoSQL

本文將逐步解說使用 Azure Cosmos DB .NET SDK 的最佳做法。 遵循這些做法，將有助於改善延遲、可用性及提升整體效能。

觀看下列影片，以透過 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 用於中繼資料作業，而在閘道模式中，其用於資料平面和中繼資料作業。 其中一個 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 相依性插入，則可以簡化 Singleton 程序：

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。 當您使用網路閘道模式，系統會透過 HTTPS/REST 發出 Azure Cosmos DB 要求。 這些要求受限於每個主機名稱或 IP 位址的預設連線限制。 您可能需要將 MaxConnections 設為較高的值 (100 至 1000)，這樣一來用戶端程式庫就可以使用多個同時連至 Azure Cosmos DB 的連線。 在 .NET SDK 1.8.0 和更新版本中，ServicePointManager.DefaultConnectionLimit 的預設值為 50。 若要變更此值，您可以將 CosmosClientOptions.GatewayModeMaxConnectionLimit 設定為較高的值。

大量寫入工作負載的最佳做法

對於具有大量建立承載的工作負載，請將 EnableContentResponseOnWrite 要求選項設定為 false。 服務就不會再將已建立或已更新的資源傳回至 SDK。 一般來說，因為應用程式具有正在建立的物件，所以不需要服務來傳回物件。 標頭值仍可存取，例如要求費用。 停用內容回應有助於改善效能，因為 SDK 不再需要配置記憶體或序列化回應主體。 這也可減少網路頻寬使用量，進一步提升效能。

多租用戶應用程式的最佳做法

如果應用程式將使用量散發到多個租用戶，而且每個租用戶在相同的 Azure Cosmos DB 帳戶內都是以不同的資料庫、容器或分割區索引鍵表示，則應用程式應該使用單一用戶端執行個體。 單一用戶端執行個體可以與帳戶內的所有資料庫、容器和分割區索引鍵互動，而且最佳做法是使用 Singleton 模式。

不過，每個租用戶都是以不同的 Azure Cosmos DB 帳戶表示時，每個帳戶都必須建立個別的用戶端執行個體。 Singleton 模式仍然適用於每個用戶端 (在應用程式存留期，一個帳戶有一個用戶端)，但如果租用戶數量很高，則可能難以管理用戶端數目。 連線可能會超出計算環境的限制，並導致連線問題。

在這些情況下，建議您：

• 了解計算環境的限制 (CPU 和連線資源)。 建議盡可能使用至少 4 核心和 8 GB 記憶體的 VM。
• 根據計算環境的限制，判斷單一計算執行個體可處理的用戶端執行個體數目 (因此，也會判斷租用戶數目)。 您可以根據所選擇的連線模式來預估連線數目，而這些連線是針對每個用戶端所開啟。
• 評估跨執行個體的租用戶散發。 如果每個計算執行個體都可以成功處理特定有限的租用戶數量，則允許在租用戶數目成長時調整不同計算執行個體的租用戶負載平衡和路由。
• 針對疏鬆工作負載，請考慮使用「最不常用的快取」作為結構來保存用戶端執行個體，並處置尚未在時間範圍內存取的租用戶用戶端。 .NET 中的其中一個選項是 MemoryCacheEntryOptions，其中 RegisterPostEvictionCallback 可以用來處置非使用中用戶端，而且 SetSlidingExpiration 可以用來定義保存非使用中連線的最長時間。
• 評估使用閘道模式來減少網路連線數目。
• 使用直接模式時，請考慮調整直接模式設定上的 CosmosClientOptions.IdleTcpConnectionTimeout 和 CosmosClientOptions.PortReuseMode 來關閉非使用中連線，並控制連線數量。

下一步

如需用來評估 Azure Cosmos DB 在數個用戶端電腦上達到高效能情節的範例應用程式，請參閱 Azure Cosmos DB 的效能和規模測試。

若要深入了解如何針對規模和高效能設計您的應用程式，請參閱 Azure Cosmos DB 的資料分割與調整規模。

正在嘗試為遷移至 Azure Cosmos DB 進行容量規劃嗎？ 您可以使用現有資料庫叢集的相關資訊進行容量規劃。

• 如果您知道目前資料庫工作負載的一般要求率，請參閱使用 Azure Cosmos DB 容量規劃工具來估計要求單位