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

  • Şunlara uygulanır: ✅ 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 artırmanıza ve genel performansı artırmanıza yardımcı olabilirsiniz.

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

Checklist

Onay kutusu Konu Description
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 istemcisi Daha iyi performans için uygulamanızın ömrü boyunca tek bir CosmosClient kullanın.
Bölgeler Gecikme süresini azaltmak için mümkün olduğunca 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ğaltın. Üretim iş yükleri için hizmet tarafından yönetilen yük devretmeyi etkinleştirin. Bu yapılandırma olmadığında, bölge bağlantısının eksikliği nedeniyle el ile yük devretme başarılı olmaz; bu durum, yazma bölgesi kesintisinin tüm süresi boyunca hesapta yazma erişilebilirliği kaybına neden olur. .NET SDK'sını kullanarak birden çok bölge eklemeyi öğrenmek için bu öğreticiye bakın.
Kullanılabilirlik ve yük devretmeler Tercih edilen bölgeler listesini kullanarak v3 SDK'sında ApplicationPreferredRegions veya ApplicationRegion ve v2 SDK'sında PreferredLocations değerlerini 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.
İşlemci (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 oranını izleyin, ve eğer kullanım yüksekse, ölçeği artırın veya genişletin.
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ğunca en az 4 çekirdekli ve 8 GB bellekli VM'ler kullanmanızı kesinlikle öneririz.
Bağlantı modları En iyi performans için doğrudan modu kullanın. Yönergeler için V3 SDK belgelerine veya V2 SDK belgelerine bakın.
Networking 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şimlerini azaltmak için VM'nizde Hızlandırılmış Ağ'ı etkinleştirin. Ayrıca maksimum CPU kullanımının 70%altında olduğu üst düzey bir sanal makine kullanmayı da düşünebilirsiniz.
Geçici bağlantı noktası tükenmesi Seyrek veya düzensiz bağlantılar için, IdleConnectionTimeout ve PortReuseMode, PrivatePortPool olarak ayarlarız. 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ının küçük bir havuzunu kullanmasına olanak tanır.
Async/await kullan Çağrıları engellemekten kaçının: Task.Result, Task.Wait, ve Task.GetAwaiter().GetResult(). Tüm çağrı yığını async/await desenlerinden yararlanmak için eşzamanlı çalışır. Birçok senkronize engelleme çağrısı iş parçacığı havuzu tükenmesine ve yanıt sürelerinin düşmesine yol açar.
Uçtan uca zaman aşımları Uçtan uca zaman aşımlarını almak için hem RequestTimeout hem de CancellationToken parametrelerini kullanmanız gerekir. Daha fazla bilgi için zaman aşımı sorun giderme kılavuzumuza bakın.
Mantığı yeniden deneme Hangi hataların yeniden denendiği ve SDK'lar tarafından hangilerinin yeniden denendiği 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 deneme yaptığı bazı senaryolar vardır. İçin. NET'e özgü uygulama ayrıntıları, bkz. SDK kaynak deposu.
Veritabanı/koleksiyon adlarını önbelleğe alma Veritabanlarınızın ve kapsayıcılarınızın adlarını yapılandırmadan alın veya başlangıçta önbelleğe alın. ReadDatabaseAsync veya ReadDocumentCollectionAsync ve CreateDatabaseQuery veya CreateDocumentCollectionQuery gibi çağrılar, sistem tarafından ayrılmış olan RU sınırından tüketim yapan hizmete meta veri çağrıları ile sonuçlanır. 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üresi için iyileştirme yapmanız 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ı paralel çalıştırmayı destekler. MaxConcurrency içindeki QueryRequestsOptions özelliğini, sahip olduğunuz bölüm sayısına ayarlamanızı öneririz. Bölüm sayısını bilmiyorsanız, en iyi gecikme süresini sağlayan 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, MaxBufferedItemCount değerini önceden getirilen sonuçların sayısını sınırlamak için beklenen döndürülecek sonuç sayısına ayarlayın.
Performans testi düşüşleri Uygulamanızda test yaparken, RetryAfter aralıklarla geri çekilme stratejilerini uygulamanız gerekir. Geri çekilme stratejisine uymak, yeniden denemeler arasında bekleme sürenizi en aza indirmenize yardımcı olur.
Dizinleme Azure Cosmos DB dizin oluşturma ilkesi, dizin oluşturma yollarını (IndexingPolicy.IncludedPaths ve IndexingPolicy.ExcludedPaths) kullanarak hangi belge yollarının dizine ekleneceğini veya dizin oluşturmanın dışında tutulacağını belirtmenize de olanak tanır. Daha hızlı yazma işlemleri için kullanılmayan yolları dizinlemenin dışında tuttuğunuzdan emin olun. SDK kullanarak dizin oluşturma hakkında daha fazla bilgi için bkz. Dizin oluşturma ilkesi.
Belge boyutu Belirtilen işlemin istek ücreti doğrudan belgenin boyutuyla ilişkilidir. Büyük belgelerdeki işlemler daha küçük belgelerdeki işlemlerden daha pahalı olduğundan, belgelerinizin boyutunu azaltmanızı öneririz.
İş parçacığı/görev sayısını artırın 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 harcaması için isteklerinizin eşzamanlılık derecesini değiştirmeniz gerekebilir. Örneğin, .NET Görev Paralel Kitaplığı kullanıyorsanız, Azure Cosmos DB'den okuma yapan veya Azure Cosmos DB'ye yazma yapan yüzlerce görev oluşturun.
Sorgu ölçümlerini etkinleştirme Arka uç sorgularınızın yürütmelerini daha detaylı kaydetmek için, .NET SDK'mızı kullanarak SQL Sorgu Metriklerini etkinleştirebilirsiniz. SQL Sorgu Ölçümlerini toplama hakkında daha fazla bilgi için bkz . sorgu ölçümleri ve performansı.
SDK kaydı Belirgin senaryolar için, örneğin istisnalar veya isteklerin beklenen gecikme süresinin ötesine geçtiği durumlar, SDK tanılama bilgilerini günlük olarak kaydedin.
DefaultTraceListener DefaultTraceListener üretim ortamlarında yüksek CPU kullanımı ve G/Ç darboğazlarına neden olarak 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ıtlanmıştır ve bazı tanımlayıcılarda kullanılamaz: /, \, ?, #. Genel öneri, beklenmeyen davranışlardan kaçınmak için tanımlayıcılarda veritabanı adı, koleksiyon adı, öğe kimliği veya bölüm anahtarı gibi özel karakterler kullanılmamasıdır.

Newtonsoft.Json Bağımlılıklarını Yönetme

Overview

Azure Cosmos DB .NET SDK'sının JSON serileştirme işlemlerine bağımlılığı Newtonsoft.Json vardır. Bu bağımlılık otomatik olarak yönetilmiyor ; projenize doğrudan bağımlılık olarak açıkça eklemeniz Newtonsoft.Json gerekir.

SDK, bilinen bir güvenlik açığı olan Newtonsoft.Json 10.x'e karşı dahili olarak derler. SDK teknik olarak 10.x ile uyumludur ve SDK'nın Newtonsoft.Json kullanımı bildirilen güvenlik sorununa açık olmasa da, olası güvenlik sorunlarını veya çakışmalarını önlemek için 13.0.3 veya üzeri bir sürümü kullanmanızı öneririz . 13.x sürümleri hataya neden olan değişiklikleri içerir, ancak SDK'nın kullanım desenleri bu değişikliklerle uyumludur.

Important

Bu bağımlılıkSystem.Text.Json aracılığıyla kullanıcı tanımlı türler için kullanılırken bile gereklidir çünkü SDK'nın iç işlemleri sistem türleri için hala Newtonsoft.Json kullanır.

Azure Cosmos DB .NET SDK v3 kullanırken her zaman doğrudan bağımlılık olarak 13.0.3 veya üzeri bir sürümü açıkça ekleyinNewtonsoft.Json. Bilinen güvenlik açıklarından dolayı 10.x sürümünü kullanmayın.

Standart .csproj Projeleri için

<ItemGroup>
  <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
  <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
</ItemGroup>

Merkezi Paket Yönetimi Kullanan Projeler için

Projeniz kullanıyorsa Directory.Packages.props:

<Project>
  <ItemGroup>
    <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
  </ItemGroup>
</Project>

Sürüm Çakışmaları Sorunlarını Giderme

Eksik Newtonsoft.Json Referansı

Şöyle bir derleme hatasıyla karşılaşırsanız:

The Newtonsoft.Json package must be explicitly referenced with version >= 10.0.2. Please add a reference to Newtonsoft.Json or set the 'AzureCosmosDisableNewtonsoftJsonCheck' property to 'true' to bypass this check.

Bu hata, bağımlılığın düzgün yapılandırıldığından emin olmak için Cosmos DB SDK'sının derleme hedefleri tarafından kasıtlı olarak oluşturulur.

Uygulamalar için Çözüm:

Yukarıdaki Önerilen Yapılandırma bölümünde gösterildiği gibi Newtonsoft.Json dosyasına açık bir başvuru ekleyin.

Kitaplıklar için çözüm:

Bir kitaplık oluşturuyorsanız (uygulama değil) ve Newtonsoft.Json bağımlılığını kitaplığınızın tüketicilerine ertelemek istiyorsanız, içinde MSBuild özelliğini ayarlayarak bu denetimi atlayabilirsiniz .csproj:

<PropertyGroup>
  <AzureCosmosDisableNewtonsoftJsonCheck>true</AzureCosmosDisableNewtonsoftJsonCheck>
</PropertyGroup>

Warning

Bu atlama yalnızca son kullanıcıların Newtonsoft.Json bağımlılığını sağlayacağı kitaplıklar oluştururken kullanın. Uygulamalar için her zaman belirgin referansı ekleyin.

Paket Sürümü Çakışmaları

Şu gibi derleme hatalarıyla karşılaşırsanız:

error NU1109: Detected package downgrade: Newtonsoft.Json from 13.0.4 to centrally defined 13.0.3

Çözüm:

  1. Hangi paketlerin daha yeni sürümlere ihtiyacı olduğunu denetleyerek gerekli sürümü belirleyin:

    dotnet list package --include-transitive | Select-String "Newtonsoft.Json"

  2. Merkezi paket sürümünüzü gerekli en yüksek sürümle eşleşecek veya bu sürümü aşacak şekilde güncelleştirin:

    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />

  3. Temizleme ve yeniden oluşturma:

    dotnet clean
dotnet restore
dotnet build

Sürüm Uyumluluğu

Aşağıdaki tabloda, her Cosmos DB SDK sürümü için önerilen en düşük güvenli Newtonsoft.Json sürümleri gösterilmektedir. SDK teknik olarak 10.x ile çalışasa da, bu sürümler güvenlik açıkları nedeniyle hiçbir zaman kullanılmamalıdır.

Cosmos DB SDK Sürümü En Düşük Güvenli Sürüm Recommended
3.47.0+ 13.0.3 13.0.4
3.54.0+ 13.0.4 13.0.4

Tip

.NET Aspire 13.0.0 veya üzerini kullanırken Aspire'in Azure bileşenleriyle çakışmaları önlemek için sürüm 13.0.4'te olduğundan emin olun Newtonsoft.Json .

En İyi Uygulamalar

  • Her zaman doğrudan bağımlılık olarak ekle - SDK bu bağımlılığı sizin için otomatik olarak yönetmez
  • Sürüm 13.0.3 veya üzerini kullanma - Bilinen güvenlik açıkları nedeniyle teknik uyumluluğa rağmen asla 10.x kullanmayın
  • System.Text.Json ile bile gereklidir - SDK sistem türleri için dahili olarak kullandığından, kullanırken bile UseSystemTextJsonSerializerWithOptionsNewtonsoft.Json eklemeniz gerekir.
  • Sürümü açıkça sabitleyin - Geçişli bağımlılık çözümlemesine güvenmeyin
  • Uyarıları izleme - NuGet paketi sürüm düşürme uyarılarını (NU1109) CI/CD işlem hatlarında hata olarak değerlendirin

Tanı bilgilerini kaydet

SDK'daki tüm yanıtlar, CosmosException dahil olmak üzere, bir Diagnostics özelliğine sahiptir. 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. Farklı senaryolarda sorun gidermeye yönelik geliştirilmiş olduğundan, dize her sürümde değişir. SDK'nin her sürümünde, dize formatında köklü değişiklikler olacaktır. Geri dönülemez değişikliklere yol açmamak 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
  • Ağ geçidi modunda HTTP hem veri düzlemi hem de meta veri işlemleri için kullanılır

HttpClient'ın temellerinden biri, havuzdaki bağlantı ömrünü HttpClient hesabınızdaki DNS değişikliklerine tepki verebildiğinden emin olmaktır. Havuza alınan bağlantılar açık tutuldukları sürece, DNS değişikliklerine tepki vermezler. 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ı etkilerse artırılabilecek 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 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 kullanırken konak başına artış System.Net MaxConnections . Azure Cosmos DB istekleri, Ağ Geçidi modunu kullandığınızda HTTPS/REST üzerinden yapılır. 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ümlerinde 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ş yükleri için en iyi yöntemler

Oluşturma yükleri fazla olan iş yükleri için EnableContentResponseOnWrite istek seçeneğini false olarak ayarlayın. Hizmet artık oluşturulan veya güncelleştirilmiş kaynağı SDK'ya döndürmez. Normalde, uygulama oluşturulan nesneye sahip olduğundan, hizmetin nesneyi geri döndürmesine gerek yoktur. Başlık değerleri, istek ücreti gibi bilgilere hâlâ erişilebilir. İçerik yanıtını devre dışı bırakmak, SDK'nın artık bellek ayırmak veya yanıtın gövdesini seri hale getirmek zorunda kalmaması anlamına geleceği için performansın geliştirilmesine yardımcı olabilir. Ayrıca performansa daha fazla yardımcı olmak için ağ bant genişliği kullanımını azaltır.

Important

EnableContentResponseOnWrite ayarını false olarak değiştirmek, 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 desen kullanmak en iyi uygulamadır.

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 ömrü boyunca her hesap için bir istemci) için geçerli olmaya devam eder, ancak kiracıların hacmi yüksekse, istemci 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 önerilir:

Sonraki Adımlar

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.

  • Geçerli veritabanı iş yükünüz için tipik istek oranlarını biliyorsanız, Azure Cosmos DB kapasite planlayıcısını kullanarak RU/sn değerlerini tahmin etme konusuna bakın.
  • Last updated on