Azure Cosmos DB .NET SDK v3 pro rozhraní API for NoSQL: Stažení a poznámky k verzi

  • Platí pro: ✅ NoSQL
Links
Poznámky k vydání Poznámky k vydání
Stažení sady SDK NuGet
Dokumentace k rozhraní API Referenční dokumentace k rozhraní .NET API
Ukázky Ukázky kódu .NET
Začínáme Začínáme se sadou .NET SDK služby Azure Cosmos DB
Osvědčené postupy Osvědčené postupy pro sadu .NET SDK služby Azure Cosmos DB
Kurz entity Framework Core Entity Framework Core se zprostředkovatelem služby Azure Cosmos DB
Aktuální podporovaná architektura Microsoft .NET Standard 2.0

Historie vydaných verzí

Historie verzí se udržuje ve zdrojovém úložišti sady .NET SDK služby Azure Cosmos DB. Podrobný seznam vydaných verzí funkcí a chyb opravených v jednotlivých verzích najdete v dokumentaci k protokolu změn sady SDK.

Různé dílčí verze sad .NET SDK jsou k dispozici ve verzi 3.x.x. Minimální doporučená verze je 3.47.0.

Známé problémy

Seznam známých problémů s doporučenou minimální verzí sady SDK najdete v části známé problémy.

Správa závislostí Newtonsoft.Json

Overview

Sada .NET SDK služby Azure Cosmos DB má závislost na Newtonsoft.Json pro operace serializace JSON. Tato závislost se nespravuje automaticky – v projektu musíte explicitně přidat Newtonsoft.Json přímou závislost.

Sada SDK se interně zkompiluje proti Newtonsoft.Json 10.x, která má známé ohrožení zabezpečení. I když je sada SDK technicky kompatibilní s verzí 10.x a použití Newtonsoft.Json sady SDK není náchylné k nahlášenému problému se zabezpečením, přesto doporučujeme použít verzi 13.0.3 nebo vyšší , abyste se vyhnuli potenciálním problémům nebo konfliktům zabezpečení. Verze 13.x zahrnují zásadní změny, ale vzory použití sady SDK jsou s těmito změnami kompatibilní.

Important

Tato závislost se vyžaduje i při použití System.Text.Json pro uživatelem definované typy prostřednictvím CosmosClientOptions.UseSystemTextJsonSerializerWithOptions, protože interní operace sady SDK stále používají Newtonsoft.Json pro systémové typy.

Při použití sady .NET SDK služby Azure Cosmos DB v3 vždy explicitně přidejte Newtonsoft.Json jako přímou závislost verzi 13.0.3 nebo vyšší. Nepoužívejte verzi 10.x kvůli známým ohrožením zabezpečení.

Pro projekty typu Standard .csproj

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

Pro projekty využívající správu centrálních balíčků

Pokud váš projekt používá Directory.Packages.props:

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

Řešení potíží s konflikty verzí

Chybějící referenční položka Newtonsoft.Json

Pokud dojde k chybě sestavení, například:

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.

Tato chyba je záměrně generována cíli sestavení sady Cosmos DB SDK, aby se zajistilo, že závislost je správně nakonfigurovaná.

Řešení pro aplikace:

Přidejte explicitní odkaz na Newtonsoft.Json, jak je znázorněno v části Doporučená konfigurace výše.

Řešení pro knihovny:

Pokud vytváříte knihovnu (ne aplikaci) a chcete odložit závislost Newtonsoft.Json na uživatele vaší knihovny, můžete tuto kontrolu obejít nastavením vlastnosti MSBuild v .csproj:

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

Warning

Tento obchvat použijte pouze při vytváření knihoven, kde koncoví uživatelé poskytnou závislost Newtonsoft.Json. Pro aplikace vždy přidejte explicitní odkaz.

Konflikty verzí balíčku

Pokud dojde k chybám sestavení, například:

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

Solution:

  1. Určete požadovanou verzi kontrolou, které balíčky potřebují novější verze:

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

  2. Aktualizujte centralizovanou verzi balíčku tak, aby odpovídala nebo překročila nejvyšší požadovanou verzi:

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

  3. Vyčištění a opětovné sestavení:

    dotnet clean
dotnet restore
dotnet build

Kompatibilita verzí

Následující tabulka uvádí minimální doporučené zabezpečené verze Newtonsoft.Json pro každou verzi sady SDK služby Cosmos DB. I když sada SDK může technicky pracovat s verzí 10.x, tyto verze by se nikdy neměly používat kvůli ohrožením zabezpečení.

Verze sady SDK služby Cosmos DB Minimální zabezpečená verze Doporučeno
3.47.0+ 13.0.3 13.0.4
3.54.0+ 13.0.4 13.0.4

Tip

Pokud používáte .NET Aspire 13.0.0 nebo novější, ujistěte se, že Newtonsoft.Json je ve verzi 13.0.4, abyste se vyhnuli konfliktům s komponentami Azure od Aspire.

Osvědčené postupy

  • Vždy přidat jako přímou závislost – sada SDK tuto závislost automaticky nespravuje za vás.
  • Použití verze 13.0.3 nebo vyšší – nikdy nepoužívejte 10.x bez ohledu na technickou kompatibilitu kvůli známým ohrožením zabezpečení
  • Vyžadováno i v případě System.Text.Json – Musíte zahrnout Newtonsoft.Json i při použití UseSystemTextJsonSerializerWithOptions, protože sada SDK ho interně používá pro systémové typy.
  • Explicitně připnout verzi – Nespoléhejte na přechodné řešení závislostí.
  • Upozornění monitorování – Zacházení s upozorněními downgradu balíčku NuGet (NU1109) jako s chybami v kanálech CI/CD

časté otázky

Jak se dozvím o vyřazení sady SDK?

Microsoft poskytne 12měsíční předstih před ukončením podpory sady SDK pro vyřazení, aby se usnadnil hladký přechod na podporovanou sadu SDK. Budeme vás informovat prostřednictvím různých komunikačních kanálů: portálu Azure, Azure aktualizací a přímé komunikace s přiřazenými správci služeb.

Vytáčuji aplikace pomocí sady to-be–vyřazené Azure Cosmos DB SDK během 12měsíčního období?

Ano, během 12měsíčního období oznámení budete moct vytvářet, nasazovat a upravovat aplikace pomocí to-bevyřazené sady AZURE COSMOS DB SDK. Doporučujeme migrovat na novější podporovanou verzi sady Azure Cosmos DB SDK během 12měsíčního období oznámení.

Po datu vyřazení aplikace, které používají nepodporovanou sadu SDK Azure Cosmos DB?

Po datu vyřazení už Azure Cosmos DB nebudou provádět opravy chyb, přidávat nové funkce nebo poskytovat podporu pro vyřazené verze sady SDK. Pokud nechcete upgradovat, žádosti odeslané z vyřazených verzí sady SDK budou dál obsluhovány službou Azure Cosmos DB.

Které verze sady SDK budou mít nejnovější funkce a aktualizace?

Nové funkce a aktualizace se budou přidávat jenom do nejnovější podverze nejnovější podporované hlavní verze sady SDK. Doporučujeme vám vždy používat nejnovější verzi, abyste mohli využívat nové funkce, vylepšení výkonu a opravy chyb. Pokud používáte starou, neřaděnou verzi sady SDK, budou vaše požadavky na Azure Cosmos DB fungovat, ale nebudete mít přístup k žádným novým funkcím.

Co mám dělat, když nemůžu aktualizovat aplikaci před datem přerušení?

Doporučujeme vám co nejdřív provést upgrade na nejnovější sadu SDK. Jakmile označíme některou sadu SDK k vyřazení, máte na aktualizaci své aplikace ještě 12 měsíců. Pokud se vám datum vyřazení nedaří aktualizovat, budou žádosti odeslané z vyřazených verzí sady SDK dál obsluhovat Azure Cosmos DB, takže spuštěné aplikace budou dál fungovat. Azure Cosmos DB už ale nebudou provádět opravy chyb, přidávat nové funkce ani poskytovat podporu pro vyřazené verze sady SDK.

Pokud máte plán podpory a potřebujete technickou podporu, kontaktujte nás vytvořením lístku podpory.

Jak můžu požádat o přidání funkcí do sady SDK nebo konektoru?

Nové funkce se vždy nepřidávají do každé sady SDK nebo konektoru okamžitě. Pokud není podporovaná funkce, kterou byste chtěli přidat, přidejte nám prosím svůj názor na fóru komunity.

Viz také

Další informace o Azure Cosmos DB najdete na stránce služby Microsoft Azure Cosmos DB.

  • Poslední aktualizace v