Zestaw .NET SDK platformy .NET usługi Azure Cosmos DB w wersji 3 dla interfejsu API dla noSQL: pobieranie i informacje o wersji

Historia wydania

Historia wersji jest przechowywana w repozytorium źródłowym zestawu .NET SDK usługi Azure Cosmos DB. Aby uzyskać szczegółową listę wersji funkcji i usterek rozwiązanych w każdej wersji, zobacz dokumentację dziennika zmian zestawu SDK

Zalecana wersja

Różne wersje podrzędne zestawów SDK platformy .NET są dostępne w wersji 3.x.x. Minimalna zalecana wersja to 3.47.0.

Znane problemy

Aby uzyskać listę znanych problemów z zalecaną minimalną wersją zestawu SDK, zobacz sekcję znane problemy.

Zarządzanie zależnościami newtonsoft.Json

Overview

Zestaw SDK dla platformy .NET w usłudze Azure Cosmos DB ma zależność od Newtonsoft.Json do operacji serializacji JSON. Ta zależność nie jest zarządzana automatycznie — musisz jawnie dodać Newtonsoft.Json jako bezpośrednią zależność w projekcie.

Zestaw SDK kompiluje się wewnętrznie z oprogramowaniem Newtonsoft.Json 10.x, który ma znaną lukę w zabezpieczeniach. Chociaż zestaw SDK jest technicznie zgodny z wersją 10.x, a użycie zestawu SDK newtonsoft.Json nie jest podatne na zgłoszony problem z zabezpieczeniami, nadal zalecamy użycie wersji 13.0.3 lub nowszej , aby uniknąć potencjalnych problemów z zabezpieczeniami lub konfliktów. Wersje 13.x obejmują zmiany wymagające dostosowania, ale wzorce użycia SDK są nadal kompatybilne z tymi zmianami.

Zalecana konfiguracja

Zawsze jawnie dodaj Newtonsoft.Json wersję 13.0.3 lub nowszą jako bezpośrednią zależność podczas korzystania z zestawu SDK .NET usługi Azure Cosmos DB w wersji 3. Nie używaj wersji 10.x ze względu na znane luki w zabezpieczeniach.

Dla projektów .csproj typu standardowego

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

W przypadku projektów korzystających z centralnego zarządzania pakietami

Jeśli projekt używa elementu Directory.Packages.props:

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

Rozwiązywanie problemów z konfliktami wersji

Brak referencji do Newtonsoft.Json

Jeśli wystąpi błąd kompilacji, taki jak:

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.

Ten błąd jest celowo generowany przez cele kompilacji SDK Cosmos DB, aby upewnić się, że konfiguracja zależności jest prawidłowa.

Rozwiązanie dla aplikacji:

Dodaj jawne odwołanie do pliku Newtonsoft.Json, jak pokazano w powyższej sekcji Zalecana konfiguracja .

Rozwiązanie dla bibliotek:

Jeśli tworzysz bibliotekę (a nie aplikację) i chcesz przekazać zależność Newtonsoft.Json użytkownikom swojej biblioteki, możesz pominąć tę kontrolę, ustawiając właściwość MSBuild w pliku .csproj:

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

Konflikty wersji pakietu

Jeśli wystąpią błędy kompilacji, takie jak:

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

Rozwiązanie:

1. Zidentyfikuj wymaganą wersję , sprawdzając, które pakiety wymagają nowszych wersji:

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

2. Zaktualizuj scentralizowaną wersję pakietu tak, aby odpowiadała lub przekroczyła najwyższą wymaganą wersję:

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

3. Czyszczenie i ponowne kompilowanie:

   dotnet clean
   dotnet restore
   dotnet build
   

Zgodność wersji

W poniższej tabeli przedstawiono minimalne zalecane bezpieczne wersje pliku Newtonsoft.Json dla każdej wersji zestawu SDK usługi Cosmos DB. Chociaż zestaw SDK może technicznie współpracować z wersją 10.x, te wersje nigdy nie powinny być używane z powodu luk w zabezpieczeniach.

Najlepsze praktyki

• Zawsze dodaj jako zależność bezpośrednią — zestaw SDK nie automatycznie zarządza tą zależnością
• Użyj wersji 13.0.3 lub nowszej — nigdy nie używaj wersji 10.x pomimo zgodności technicznej ze względu na znane luki w zabezpieczeniach
• Wymagane nawet w przypadku pliku System.Text.Json — należy uwzględnić plik Newtonsoft.Json nawet w przypadku używania elementu UseSystemTextJsonSerializerWithOptions, ponieważ zestaw SDK używa go wewnętrznie dla typów systemów
• Ustal wersję jawnie — nie opieraj się na pośrednim rozwiązywaniu zależności
• Ostrzeżenia dotyczące monitorowania — traktuj ostrzeżenia o obniżeniu poziomu pakietu NuGet (NU1109) jako błędy w potokach ciągłej integracji/ciągłego wdrażania

Często zadawane pytania

W jaki sposób będę otrzymywać powiadomienia o wycofywanym zestawie SDK?

Microsoft powiadomi o 12-miesięcznym wyprzedzeniu przed zakończeniem wsparcia wycofanego zestawu SDK, aby ułatwić bezproblemowe przejście do obsługiwanego zestawu SDK. Powiadomimy Cię za pośrednictwem różnych kanałów komunikacyjnych: portalu Azure, aktualizacji Azure i bezpośredniej komunikacji z przypisanymi administratorami usługi.

Can I author applications using a to-be-retired Azure Cosmos DB SDK w ciągu 12 miesięcy?

Tak, będzie można tworzyć, wdrażać i modyfikować aplikacje przy użyciu zestawu SDK to-be— wycofany Azure Cosmos DB w okresie powiadomienia 12 miesięcy. Zalecamy przeprowadzenie migracji do nowszej obsługiwanej wersji zestawu AZURE COSMOS DB SDK w odpowiednim okresie powiadomienia o upływie 12 miesięcy.

Po dacie wycofania co się stanie z aplikacjami korzystającymi z nieobsługiwanego zestawu SDK Azure Cosmos DB?

Po dacie wycofania Azure Cosmos DB nie będą już wprowadzać poprawek usterek, dodawać nowych funkcji ani zapewniać pomocy technicznej dla wycofanych wersji zestawu SDK. Jeśli nie chcesz uaktualnić, żądania wysyłane z wycofanych wersji zestawu SDK będą nadal obsługiwane przez usługę Azure Cosmos DB.

Które wersje zestawu SDK będą mieć najnowsze funkcje i aktualizacje?

Nowe funkcje i aktualizacje będą dodawane tylko do najnowszej wersji pomocniczej najnowszej obsługiwanej wersji zestawu SDK. Zalecamy używanie najnowszej wersji, aby korzystać z nowych funkcji, ulepszeń wydajności i poprawek błędów. Jeśli używasz starej, nieucofej wersji zestawu SDK, żądania do Azure Cosmos DB nadal będą działać, ale nie będziesz mieć dostępu do żadnych nowych funkcji.

Co zrobić, jeśli nie mogę zaktualizować aplikacji przed datą progową?

Zalecamy przeprowadzenie uaktualnienia do najnowszej wersji zestawu SDK tak szybko, jak to możliwe. Gdy zestaw SDK zostanie oznaczony do wycofania, będziesz mieć 12 miesięcy na zaktualizowanie swojej aplikacji. Jeśli nie możesz zaktualizować daty wycofania, żądania wysyłane z wycofanych wersji zestawu SDK będą nadal obsługiwane przez Azure Cosmos DB, więc uruchomione aplikacje będą nadal działać. Jednak Azure Cosmos DB nie będą już wprowadzać poprawek błędów, dodawać nowych funkcji ani zapewniać pomocy technicznej dla wycofanych wersji zestawu SDK.

Jeśli masz plan pomocy technicznej i potrzebujesz pomocy technicznej, skontaktuj się z nami, tworząc bilet pomocy technicznej.

Jak mogę zażądać dodania funkcji do zestawu SDK lub łącznika?

Nowe funkcje nie zawsze są natychmiast dodawane do każdego zestawu SDK lub łącznika. Jeśli funkcja nie jest obsługiwana, którą chcesz dodać, dodaj opinię do naszego forum społeczności.

Zobacz także

Aby dowiedzieć się więcej na temat Azure Cosmos DB, zobacz stronę usługi Microsoft Azure Cosmos DB.