NoSQL için API için Azure Cosmos DB .NET SDK v3: İndirme ve sürüm notları

  • Şunlara uygulanır: ✅ NoSQL
Links
Sürüm notları Sürüm notları
SDK indirmesi NuGet
API belgeleri .NET API başvuru belgeleri
Örnekleri .NET kod örnekleri
Başlayın Azure Cosmos DB .NET SDK'sını kullanmaya başlama
En İyi Yöntemler Azure Cosmos DB .NET SDK'sı için En İyi Yöntemler
Entity Framework Core öğreticisi Azure Cosmos DB Sağlayıcısı ile Entity Framework Core
Şu anda desteklenen çerçeve Microsoft .NET Standard 2.0

Sürüm geçmişi

Sürüm geçmişi, Azure Cosmos DB .NET SDK kaynak deposunda tutulur. Her sürümde düzeltilen özellik sürümlerinin ve hataların ayrıntılı listesi için SDK değişiklik günlüğü belgelerine bakın

.NET SDK'larının farklı alt sürümleri 3.x.x sürümünde kullanılabilir. Önerilen en düşük sürüm 3.47.0'dır.

Bilinen sorunlar

SDK'nın önerilen en düşük sürümüyle ilgili bilinen sorunların listesi için bilinen sorunlar bölümüne bakın.

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

FAQ

SDK'nın kullanımdan kaldırıldığı bana nasıl bildirilir?

Microsoft, desteklenen bir SDK'ya sorunsuz bir geçişi kolaylaştırmak için kullanımdan kaldırılacak SDK desteği sona ermeden önce 12 ay önceden bildirimde bulunacaktır. Sizi çeşitli iletişim kanalları aracılığıyla bilgilendireceğiz: Azure portalı, Azure güncelleştirmeleri ve atanan hizmet yöneticileriyle doğrudan iletişim.

12 aylık süre boyunca to-bekullanımdan kaldırılan bir Azure Cosmos DB SDK kullanarak uygulama yazamaz

Evet, 12 aylık bildirim süresi boyunca to-bekullanımdan kaldırılan Azure Cosmos DB SDK'sını kullanarak uygulamaları yazabilir, dağıtabilir ve değiştirebilirsiniz. 12 aylık bildirim döneminde uygun şekilde Azure Cosmos DB SDK'sının desteklenen daha yeni bir sürümüne geçmenizi öneririz.

Kullanımdan kaldırma tarihinden sonra desteklenmeyen Azure Cosmos DB SDK'sını kullanan uygulamalara ne olur?

Kullanımdan kaldırma tarihinden sonra Azure Cosmos DB artık hata düzeltmeleri yapmaz, yeni özellikler eklemez veya kullanımdan kaldırılan SDK sürümlerine destek sağlamaz. Yükseltmeyi tercih ederseniz, SDK'nın kullanımdan kaldırılan sürümlerinden gönderilen istekler Azure Cosmos DB hizmeti tarafından sunulmaya devam eder.

Hangi SDK sürümleri en son özellikleri ve güncelleştirmeleri içerecek?

Yeni özellikler ve güncelleştirmeler yalnızca desteklenen en son ana SDK sürümünün en son alt sürümüne eklenecek. Yeni özelliklerden, performans geliştirmelerinden ve hata düzeltmelerinden yararlanmak için her zaman en son sürümü kullanmanızı öneririz. SDK'nın eski, kullanımdan kaldırılmamış bir sürümünü kullanıyorsanız, Azure Cosmos DB istekleriniz çalışmaya devam eder, ancak yeni özelliklere erişiminiz olmaz.

Uygulamamı belirli bir kesme tarihinden önce güncelleştiremezsem ne yapmalıyım?

Mümkün olan en kısa zamanda en son SDK'ya yükseltmenizi öneririz. SDK kullanımdan kaldırılmak üzere etiketlendikten sonra, uygulamanızı güncelleştirmek için 12 ayınız olacak. Kullanımdan kaldırma tarihine kadar güncelleştiremiyorsanız SDK'nın kullanımdan kaldırılan sürümlerinden gönderilen istekler Azure Cosmos DB tarafından sunulmaya devam eder, dolayısıyla çalışan uygulamalarınız çalışmaya devam eder. Ancak Azure Cosmos DB artık hata düzeltmeleri yapmaz, yeni özellikler eklemez veya kullanımdan kaldırılacak SDK sürümleri için destek sağlamaz.

Destek planınız varsa ve teknik desteğe gerek duyuyorsanız, bir destek bileti doldurarak bizimle iletişime geçin.

Sdk veya bağlayıcıya özelliklerin eklenmesini nasıl isteyebilirim?

Yeni özellikler her zaman her SDK'ya veya bağlayıcıya hemen eklenmez. Eklenmesini istediğiniz desteklenmeyen bir özellik varsa lütfen topluluk forumumuza geri bildirim ekleyin.

Ayrıca bakınız

Azure Cosmos DB hakkında daha fazla bilgi edinmek için bkz. Microsoft Azure Cosmos DB hizmet sayfası.

  • Last updated on