Azure Cosmos DB .NET SDK'sı için en iyi yöntemler

  • Makale

UYGULANANLAR: NOSQL

Bu makalede, Azure Cosmos DB .NET SDK'sını kullanmaya yönelik en iyi yöntemler açıklanmaktadır. Bu uygulamaları izleyerek gecikme sürenizi, kullanılabilirliğinizi iyileştirmeye ve genel performansı artırmaya yardımcı olur.

Azure Cosmos DB mühendisinden .NET SDK'sını kullanma hakkında daha fazla bilgi edinmek için aşağıdaki videoyu izleyin!

Denetim Listesi

İşaretli Konu Ayrıntılar/Bağlantılar
SDK Sürümü En iyi performans için her zaman Azure Cosmos DB SDK'sının en son sürümünü kullanın.
Singleton İstemcisi Daha iyi performans için uygulamanızın ömrü boyunca tek bir örneğiniCosmosClient kullanın.
Bölgeler Gecikme süresini azaltmak için mümkün olduğunda uygulamanızı Azure Cosmos DB hesabınızla aynı Azure bölgesinde çalıştırdığınızdan emin olun. En iyi kullanılabilirlik için 2-4 bölgeyi etkinleştirin ve hesaplarınızı birden çok bölgede çoğaltarak. Üretim iş yükleri için hizmet tarafından yönetilen yük devretmeyi etkinleştirin. Bu yapılandırma olmadığında, el ile yük devretmenin bölge bağlantısı olmaması nedeniyle başarılı olmayacağından, hesap yazma bölgesi kesintisinin tüm süresi boyunca yazma kullanılabilirliği kaybıyla karşılaşır. .NET SDK'sını kullanarak birden çok bölge eklemeyi öğrenmek için burayı ziyaret edin
Kullanılabilirlik ve Yük Devretmeler v3 SDK'sında ApplicationPreferredRegions veya ApplicationRegion'ı ve tercih edilen bölgeler listesini kullanarak v2 SDK'sında PreferredLocations'ı ayarlayın. Yük devretmeler sırasında yazma işlemleri geçerli yazma bölgesine, tüm okumalar ise tercih ettiğiniz bölgeler listesindeki ilk bölgeye gönderilir. Bölgesel yük devretme mekaniği hakkında daha fazla bilgi için kullanılabilirlik sorunlarını giderme kılavuzuna bakın.
CPU İstemci makinenizde kaynak olmaması nedeniyle bağlantı/kullanılabilirlik sorunlarıyla karşılaşabilirsiniz. Azure Cosmos DB istemcisini çalıştıran düğümlerde CPU kullanımınızı izleyin ve kullanım yüksekse ölçeği artırma/genişletme.
Barındırma Mümkün olduğunda en iyi performans için Windows 64 bit konak işlemeyi kullanın. Doğrudan mod gecikmeye duyarlı üretim iş yükleri için mümkün olduğunda en az 4 çekirdekli ve 8 GB bellekli VM'ler kullanmanızı kesinlikle öneririz.
Bağlantı Modları En iyi performans için Doğrudan modunu kullanın. Bunun nasıl yapılacağını açıklayan yönergeler için V3 SDK belgelerine veya V2 SDK belgelerine bakın.
Ağ Uygulamanızı çalıştırmak için bir sanal makine kullanıyorsanız, yüksek trafik nedeniyle oluşan performans sorunlarına yardımcı olmak ve gecikme süresini veya CPU değişimini azaltmak için VM'nizde Hızlandırılmış Ağ'ı etkinleştirin. Maksimum CPU kullanımının %70'in altında olduğu daha yüksek bir uç Sanal Makine kullanmayı da düşünebilirsiniz.
Kısa Ömürlü Bağlantı Noktası Tükenmesi Seyrek veya düzensiz bağlantılar için ve PortReuseModePrivatePortPooldeğerini olarak ayarlarızIdleConnectionTimeout. IdleConnectionTimeout özelliği, kullanılmayan bağlantıların kapatıldığı süreyi denetlemeye yardımcı olur. Bu, kullanılmayan bağlantı sayısını azaltır. Varsayılan olarak, boştaki bağlantılar süresiz olarak açık tutulur. Değer kümesi 10 dakikadan büyük veya buna eşit olmalıdır. 20 dakika ile 24 saat arasında değerler önerilir. özelliği, PortReuseMode SDK'nın çeşitli Azure Cosmos DB hedef uç noktaları için kısa ömürlü bağlantı noktaları içeren küçük bir havuz kullanmasına olanak tanır.
Async/Await Kullanma Çağrıları engellemekten kaçının: Task.Result, Task.Waitve Task.GetAwaiter().GetResult(). Zaman uyumsuz/await desenlerinden yararlanmak için çağrı yığınının tamamı zaman uyumsuzdur . Birçok zaman uyumlu engelleme çağrısı , İş Parçacığı Havuzu'na açlığa ve yanıt sürelerinin düşmesine neden olur.
Uçtan Uca Zaman Aşımları Uçtan uca zaman aşımlarını almak için hem CancellationToken hem de RequestTimeout parametrelerini kullanmanız gerekir. Daha fazla ayrıntı için zaman aşımı sorun giderme kılavuzumuzu ziyaret edin.
Yeniden Deneme Mantığı Yeniden denenecek hatalar ve SDK'lar tarafından yeniden denenen hatalar hakkında daha fazla bilgi için bkz. tasarım kılavuzu. Birden çok bölgeyle yapılandırılmış hesaplar için, SDK'nın diğer bölgelerde otomatik olarak yeniden deneyeceği bazı senaryolar vardır. .NET'e özgü uygulama ayrıntıları için SDK kaynak deposunu ziyaret edin.
Veritabanı/koleksiyon adlarını önbelleğe alma Yapılandırmadan veritabanlarınızın ve kapsayıcılarınızın adlarını alın veya başlangıçta önbelleğe alın. veya ReadDocumentCollectionAsyncCreateDatabaseQueryCreateDocumentCollectionQuery veya gibi ReadDatabaseAsync çağrılar, sisteme ayrılmış RU sınırından kullanan hizmete meta veri çağrılarına neden olur. CreateIfNotExist ayrıca veritabanını ayarlamak için yalnızca bir kez kullanılmalıdır. Genel olarak, bu işlemlerin seyrek gerçekleştirilmesi gerekir.
Toplu Destek Gecikme süresini iyileştirmeniz gerekmeyebilecek senaryolarda, büyük hacimli verilerin dökümünü almak için Toplu desteği etkinleştirmenizi öneririz.
Paralel Sorgular Azure Cosmos DB SDK'sı, sorgularınızda daha iyi gecikme süresi ve aktarım hızı için sorguların paralel çalıştırılmasını destekler. içindeki QueryRequestsOptions özelliğini sahip olduğunuz bölüm sayısına ayarlamanızı MaxConcurrency öneririz. Bölüm sayısını bilmiyorsanız, en iyi gecikme süresini sağlamak için komutunu kullanarak int.MaxValuebaşlayın. Ardından, yüksek CPU sorunlarını önlemek için ortamın kaynak kısıtlamalarına uyana kadar sayıyı azaltın. Ayrıca, önceden hazırlanan sonuçların sayısını sınırlamak için değerini döndürülen beklenen sonuç sayısına ayarlayın MaxBufferedItemCount .
Performans Testi Geri Çekilmeleri Uygulamanızda test gerçekleştirirken, aralıklarla geri almalar RetryAfter uygulamanız gerekir. Geri çekilmeye saygı duymak, yeniden denemeler arasında beklemeye en az miktarda zaman ayırmanıza yardımcı olur.
Dizinleme Azure Cosmos DB dizin oluşturma ilkesi, dizin oluşturma yollarını (IndexingPolicy.IncludedPaths ve IndexingPolicy.ExcludedPaths) kullanarak dizin oluşturmanın hangi belge yollarının dahil edilmesini veya dışında tutulacağını belirtmenize de olanak tanır. Daha hızlı yazma işlemleri için kullanılmayan yolları dizin oluşturmanın dışında tutmadığınızdan emin olun. SDK kullanarak dizin oluşturma hakkında daha fazla bilgi için bkz. performans ipuçları .NET SDK v3.
Belge Boyutu Belirtilen işlemin istek ücreti doğrudan belgenin boyutuyla ilişkilidir. Büyük belgelerdeki işlemler küçük belgelerdeki işlemlerden daha pahalı olduğundan, belgelerinizin boyutunu azaltmanızı öneririz.
İş parçacığı/görev sayısını artırma Azure Cosmos DB'ye yapılan çağrılar ağ üzerinden yapıldığından, istemci uygulamasının istekler arasında beklemeye en az zaman ayırabilmesi için isteklerinizin eşzamanlılık derecesini değiştirmeniz gerekebilir. Örneğin, .NET Görev Paralel Kitaplığı'nı kullanıyorsanız, Azure Cosmos DB'den okunan veya Azure Cosmos DB'ye yazılan yüzlerce görev sırasına göre oluşturun.
Sorgu Ölçümlerini Etkinleştirme Arka uç sorgu yürütmelerinizin daha fazla günlüğe kaydedilmesi için .NET SDK'mızı kullanarak SQL Sorgu Ölçümlerini etkinleştirebilirsiniz. SQL Sorgu Ölçümlerini toplama hakkında daha fazla bilgi için bkz. sorgu ölçümleri ve performansı.
SDK Günlüğü Özel durumlar veya isteklerin beklenen gecikme süresinin ötesine geçtiği durumlar gibi bekleyen senaryolar için Günlük SDK tanılamaları .
DefaultTraceListener DefaultTraceListener, yüksek CPU ve G/Ç performans sorunlarına neden olan üretim ortamlarında performans sorunları oluşturur. En son SDK sürümlerini kullandığınızdan emin olun veya DefaultTraceListener'ı uygulamanızdan kaldırın
Tanımlayıcılarda özel karakterler kullanmaktan kaçının Bazı karakterler kısıtlanır ve bazı tanımlayıcılarda kullanılamaz: '/', '\', '?', '#'. Genel öneri, beklenmeyen davranışlardan kaçınmak için veritabanı adı, koleksiyon adı, öğe kimliği veya bölüm anahtarı gibi tanımlayıcılarda özel karakter kullanmamaktır.

Tanılamaları yakalama

dahil olmak üzere CosmosExceptionSDK'daki tüm yanıtların bir Diagnostics özelliği vardır. Bu özellik, yeniden denemeler veya geçici hatalar olup olmadığı dahil olmak üzere tek istekle ilgili tüm bilgileri kaydeder.

Tanılama bir dize olarak döndürülür. Dize, farklı senaryolarda sorun gidermeye yönelik geliştirilmiş olduğundan her sürümle birlikte değişir. SDK'nın her sürümünde, dizede biçimlendirmede hataya neden olan değişiklikler olur. Hataya neden olan değişiklikleri önlemek için dizeyi ayrıştırmayın. Aşağıdaki kod örneğinde .NET SDK'sını kullanarak tanılama günlüklerinin nasıl okunduğu gösterilmektedir:

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 bağlantıları için en iyi yöntemler

.NET SDK'sı, yapılandırılan bağlantı modundan bağımsız olarak HTTP istekleri gerçekleştirmek için kullanır HttpClient . Doğrudan modda HTTP, meta veri işlemleri için kullanılır ve Ağ Geçidi modunda hem veri düzlemi hem de meta veri işlemleri için kullanılır. HttpClient'ın temellerinden biri, havuza alınan bağlantı ömrünü özelleştirerek hesabınızdaki HttpClient DNS değişikliklerine tepki veremediğinden emin olmaktır. Havuza alınan bağlantılar açık tutulduğu sürece DNS değişikliklerine tepki vermez. Bu ayar havuza alınan bağlantıların düzenli aralıklarla kapatılmasını zorlayarak uygulamanızın DNS değişikliklerine tepki vermesini sağlar. Önerimiz, sık sık yeni bağlantılar oluşturmanın performans etkisini dengelemek ve DNS değişikliklerine (kullanılabilirlik) tepki vermek için bu değeri bağlantı modunuza ve iş yükünüze göre özelleştirmenizdir. 5 dakikalık bir değer, özellikle Ağ Geçidi modu için performansı etkiliyorsa artırılabilir iyi bir başlangıç olabilir.

Özel HttpClient'ınızı aracılığıyla CosmosClientOptions.HttpClientFactoryekleyebilirsiniz, örneğin:

// 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 bağımlılık ekleme özelliğini kullanıyorsanız Tekil işlemi basitleştirebilirsiniz:

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);
});

Ağ Geçidi modunu kullanırken en iyi yöntemler

Ağ geçidi modunu kullandığınızda konak başına artış System.Net MaxConnections . Azure Cosmos DB istekleri, Ağ Geçidi modunu kullandığınızda HTTPS/REST üzerinden yapılır. Bunlar ana bilgisayar adı veya IP adresi başına varsayılan bağlantı sınırına tabidir. İstemci kitaplığının Azure Cosmos DB'ye birden çok eşzamanlı bağlantı kullanabilmesi için daha yüksek bir değere (100 ile 1.000 arasında) ayarlamanız MaxConnections gerekebilir. .NET SDK 1.8.0 ve sonraki sürümlerde için ServicePointManager.DefaultConnectionLimit varsayılan değer 50'dir. Değeri değiştirmek için daha yüksek bir değere ayarlayabilirsiniz CosmosClientOptions.GatewayModeMaxConnectionLimit .

Yoğun yazma içeren iş yükleri için en iyi yöntemler

Yükü yoğun olan iş yükleri için istek seçeneğini olarak falseayarlayınEnableContentResponseOnWrite. Hizmet artık oluşturulan veya güncelleştirilmiş kaynağı SDK'ya döndürmez. Normalde, uygulamada oluşturulmakta olan nesne bulunduğundan, hizmeti döndürmesi gerekmez. Üst bilgi değerlerine istek ücreti gibi yine erişilebilir. SDK'nın artık bellek ayırması veya yanıtın gövdesini seri hale getirmesi gerekmeyen içerik yanıtını devre dışı bırakmak performansı artırmaya yardımcı olabilir. Ayrıca performansa daha fazla yardımcı olmak için ağ bant genişliği kullanımını azaltır.

Önemli

ayarı EnableContentResponseOnWritefalse , tetikleyici işleminden gelen yanıtı da devre dışı bırakır.

Çok kiracılı uygulamalar için en iyi yöntemler

Kullanımı, her kiracının aynı Azure Cosmos DB hesabı içindeki farklı bir veritabanı, kapsayıcı veya bölüm anahtarıyla temsil edildiği birden çok kiracıya dağıtan uygulamalar tek bir istemci örneği kullanmalıdır. Tek bir istemci örneği bir hesaptaki tüm veritabanları, kapsayıcılar ve bölüm anahtarlarıyla etkileşimde bulunabilir ve tekil düzeni kullanmak en iyi yöntemdir.

Ancak, her kiracı farklı bir Azure Cosmos DB hesabıyla temsil edildiğinde, hesap başına ayrı bir istemci örneği oluşturmak gerekir. Tekil desen her istemci (uygulamanın kullanım ömrü boyunca her hesap için bir istemci) için geçerli olmaya devam eder, ancak kiracıların hacmi yüksekse, istemcilerin sayısını yönetmek zor olabilir. Bağlantılar işlem ortamının sınırlarını aşabilir ve bağlantı sorunlarına neden olabilir.

Bu durumlarda şunların kullanılması önerilir:

  • İşlem ortamının (CPU ve bağlantı kaynakları) sınırlamalarını anlayın. Mümkün olduğunda en az 4 çekirdekli ve 8 GB belleğe sahip VM'ler kullanmanızı öneririz.
  • İşlem ortamının sınırlamalarına bağlı olarak, tek bir işlem örneğinin işleyebileceği istemci örneği sayısını (ve dolayısıyla kiracı sayısını) belirleyin. Seçilen bağlantı moduna bağlı olarak istemci başına açılacak bağlantı sayısını tahmin edebilirsiniz.
  • Örnekler arasında kiracı dağıtımlarını değerlendirme. Her işlem örneği belirli bir sınırlı miktarda kiracıyı başarıyla işleyebilirse, yük dengeleme ve kiracıların farklı işlem örneklerine yönlendirilmesi, kiracı sayısı arttıkça ölçeklendirmeye olanak tanır.
  • Seyrek iş yükleri için, istemci örneklerini tutmak ve bir zaman penceresi içinde erişilmemiş kiracılar için istemcileri atmak için yapı olarak En Az Sık Kullanılan önbelleği kullanmayı göz önünde bulundurun. .NET'teki seçeneklerden biri, etkin olmayan istemcileri atmak için RegisterPostEvictionCallback'in ve etkin olmayan bağlantıların tutulacağı en uzun süreyi tanımlamak için SetSlidingExpiration'ın kullanılabildiği MemoryCacheEntryOptions seçeneğidir.
  • Ağ bağlantısı sayısını azaltmak için Ağ Geçidi modunu kullanarak değerlendirme.
  • Doğrudan modu kullanırken kullanılmayan bağlantıları kapatmak ve bağlantı hacmini denetim altında tutmak için doğrudan mod yapılandırmasındaCosmosClientOptions.IdleTcpConnectionTimeout ve CosmosClientOptions.PortReuseMode ayarlarını yapmayı göz önünde bulundurun.

Sonraki adımlar

Azure Cosmos DB'yi birkaç istemci makinesinde yüksek performanslı senaryolar için değerlendirmek için kullanılan örnek bir uygulama için bkz. Azure Cosmos DB ile performans ve ölçek testi.

Uygulamanızı ölçek ve yüksek performans için tasarlama hakkında daha fazla bilgi edinmek için bkz. Azure Cosmos DB'de bölümleme ve ölçeklendirme.

Azure Cosmos DB'ye geçiş için kapasite planlaması yapmaya mı çalışıyorsunuz? Kapasite planlaması için mevcut veritabanı kümeniz hakkındaki bilgileri kullanabilirsiniz.