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

• .NET SDK v3
• .NET SDK v2
• .NET Core SDK v2
• Sada .NET Change Feed SDK v2
• Node.js
• Java SDK v4
• Synchronizace sady Java SDK v2
• Async Java SDK v2
• Spring Data v2
• Spring Data v3
• Spring Data v5
• Python
• Pokračovat
• REST
• Poskytovatel prostředků REST
• SQL
• Bulk Executor – .NET v2
• Bulk Executor – Java

	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.

Doporučená verze

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

Přehled

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í.

Důležité

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.

Doporučená konfigurace

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>

Výstraha

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

Návod

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 oznámí ukončení podpory vyřazené sady SDK s 12měsíčním předstihem, aby mohlo dojít k bezproblémovému přechodu na podporovanou sadu SDK. Budeme vás informovat pomocí různých komunikačních kanálů: webu Azure Portal, aktualizací Azure a přímých zpráv určeným správcům služeb.

Můžu během těchto 12 měsíců vytvářet aplikace pomocí sady SDK Azure Cosmos DB určené k vyřazení z provozu?

Ano, během těchto 12 měsíců budete moct pomocí sady SDK Azure Cosmos DB určené k vyřazení z provozu vytvářet, nasazovat a upravovat aplikace. Doporučujeme vám během tohoto 12měsíčního období provést migraci na novější podporovanou verzi sady SDK Azure Cosmos DB.

Co se stane po datu vyřazení z provozu s aplikacemi, které používají nepodporovanou sadu SDK Azure Cosmos DB?

Po datu vyřazení už Azure Cosmos DB nebude u vyřazených verzí sady SDK provádět opravy chyb, přidávat nové funkce ani poskytovat podporu. Pokud nechcete provést upgrade, služba Azure Cosmos DB bude dál zpracovávat požadavky odeslané z vyřazených verzí sady SDK.

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 nevyřazenou verzi sady SDK, požadavky na Azure Cosmos DB budou pořád 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 nepodaří provést aktualizaci do data vyřazení, Azure Cosmos DB bude dál zpracovávat požadavky odeslané z vyřazených verzí sady SDK, takže vaše spuštěné aplikace budou dál fungovat. Azure Cosmos DB už ale nebude u vyřazených verzí sady SDK provádět opravy chyb, přidávat nové funkce ani poskytovat podporu.

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 službě Azure Cosmos DB najdete na stránce služby Microsoft Azure Cosmos DB .