Azure Cosmos DB .NET SDK v3 für die API für NoSQL: Download und Anmerkungen zum Release

Versionsverlauf

Der Releaseverlauf wird im Azure Cosmos DB .NET SDK-Quellrepository verwaltet. Eine detaillierte Liste der Featurereleases und behobenen Fehler in jedem Release finden Sie in der Dokumentation zum SDK-Änderungsprotokoll

Empfohlene Version

Die Version 3.x.x umfasst verschiedene Nebenversionen des .NET SDK. Die empfohlene Mindestversion ist 3.47.0.

Bekannte Probleme

Eine Liste bekannter Probleme mit der empfohlenen Mindestversion des SDK finden Sie im Abschnitt zu bekannten Problemen.

Verwaltung von Newtonsoft.Json-Abhängigkeiten

Overview

Das Azure Cosmos DB .NET SDK hat eine Abhängigkeit von Newtonsoft.Json für JSON-Serialisierungsvorgänge. Diese Abhängigkeit wird nicht automatisch verwaltet – Sie müssen explizit eine direkte Abhängigkeit in Ihrem Projekt hinzufügen Newtonsoft.Json .

Das SDK kompiliert intern mit Newtonsoft.Json 10.x, das über eine bekannte Sicherheitslücke verfügt. Obwohl das SDK technisch mit 10.x kompatibel ist und die Verwendung von Newtonsoft.Json nicht anfällig für das gemeldete Sicherheitsproblem ist, empfehlen wir weiterhin die Verwendung von Version 13.0.3 oder höher , um potenzielle Sicherheitsprobleme oder Konflikte zu vermeiden. Die 13.x-Versionen enthalten Änderungen, die Inkompatibilitäten verursachen könnten, aber die Nutzungsmuster des SDK sind mit diesen Änderungen kompatibel.

Empfohlene Konfiguration

Fügen Sie Newtonsoft.Json immer explizit Version 13.0.3 oder höher als direkte Abhängigkeit hinzu, wenn Sie das Azure Cosmos DB .NET SDK v3 verwenden. Verwenden Sie Version 10.x aufgrund bekannter Sicherheitsrisiken nicht.

Für Standard .csproj-Projekte

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

Für Projekte mit zentraler Paketverwaltung

Wenn Ihr Projekt Folgendes verwendet Directory.Packages.props:

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

Problembehandlung bei Versionskonflikten

Fehlende Newtonsoft.Json-Referenz

Wenn ein Buildfehler auftritt, z. B.:

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.

Dieser Fehler wird absichtlich in den Buildzielen des Cosmos DB SDK erzeugt, um sicherzustellen, dass die Abhängigkeit richtig konfiguriert ist.

Lösung für Anwendungen:

Fügen Sie einen expliziten Verweis auf Newtonsoft.Json hinzu, wie im Abschnitt "Empfohlene Konfiguration " weiter oben gezeigt.

Lösung für Bibliotheken:

Wenn Sie eine Bibliothek (keine Anwendung) erstellen und die Newtonsoft.Json-Abhängigkeit auf die Verbraucher Ihrer Bibliothek übertragen möchten, können Sie diese Überprüfung umgehen, indem Sie die MSBuild-Eigenschaft in Ihrem .csproj setzen:

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

Paketversionskonflikte

Wenn Buildfehler auftreten, z. B.:

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

Solution:

1. Identifizieren Sie die erforderliche Version , indem Sie überprüfen, welche Pakete neuere Versionen benötigen:

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

2. Aktualisieren Sie Die zentrale Paketversion so, dass sie mit der höchsten erforderlichen Version übereinstimmt oder überschreitet:

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

3. Bereinigen und Neuaufbau:

   dotnet clean
   dotnet restore
   dotnet build
   

Versionskompatibilität

Die folgende Tabelle zeigt die mindestens empfohlenen sicheren Versionen von Newtonsoft.Json für jede Cosmos DB SDK-Version. Während das SDK technisch mit 10.x arbeiten kann, sollten diese Versionen aufgrund von Sicherheitsrisiken niemals verwendet werden.

Bewährte Methoden

• Immer als direkte Abhängigkeit hinzufügen – Das SDK verwaltet diese Abhängigkeit nicht automatisch für Sie.
• Verwenden Sie Version 13.0.3 oder höher – Verwenden Sie niemals 10.x trotz technischer Kompatibilität, aufgrund bekannter Sicherheitsrisiken
• Erforderlich auch bei System.Text.Json – Sie müssen Newtonsoft.Json auch bei Verwendung UseSystemTextJsonSerializerWithOptionseinschließen, da das SDK es intern für Systemtypen verwendet.
• Version explizit festlegen – Verlassen Sie sich nicht auf die transitive Auflösung von Abhängigkeiten
• Überwachen von Warnungen – Behandeln von NuGet-Paket-Downgradewarnungen (NU1109) als Fehler in CI/CD-Pipelines

Häufig gestellte Fragen

Wie werde ich über die Einstellung eines SDK benachrichtigt?

Microsoft wird vor Ablauf des Supports des reaktivierten SDK 12 Monate im Voraus informieren, um einen reibungslosen Übergang zu einem unterstützten SDK zu erleichtern. Wir benachrichtigen Sie über verschiedene Kommunikationskanäle: das Azure-Portal, Azure Updates und die direkte Kommunikation mit zugewiesenen Dienstadministratoren.

Kann ich Anwendungen mithilfe eines to-be-eingestellten Azure Cosmos DB SDK während des Zeitraums von 12 Monaten erstellen?

Ja, Sie können Anwendungen mithilfe des to-be-eingestellten Azure Cosmos DB SDK während des 12-Monat-Benachrichtigungszeitraums erstellen, bereitstellen und ändern. Es wird empfohlen, während des 12-monatigen Kündigungszeitraums zu einer neueren unterstützten Version des Azure Cosmos DB SDK zu migrieren.

Nach dem Deaktivierungsdatum geschieht folgendes mit Anwendungen, die das nicht unterstützte Azure Cosmos DB SDK verwenden?

Nach dem Deaktivierungsdatum werden Azure Cosmos DB keine Fehlerbehebungen mehr vornehmen, neue Features hinzufügen oder Unterstützung für die eingestellten SDK-Versionen bereitstellen. Wenn Sie kein Upgrade durchführen möchten, werden anforderungen, die von den eingestellten Versionen des SDK gesendet werden, weiterhin vom Azure Cosmos DB-Dienst bereitgestellt.

Welche SDK-Versionen werden über die neuesten Funktionen und Updates verfügen?

Neue Funktionen und Updates werden nur der aktuellen Nebenversion der neuesten unterstützten SDK-Hauptversion hinzugefügt. Es wird empfohlen, immer die aktuelle Version zu verwenden, um von neuen Funktionen, Leistungsverbesserungen und Fehlerbehebungen zu profitieren. Wenn Sie eine alte, nicht eingestellte Version des SDK verwenden, funktionieren Ihre Anforderungen an Azure Cosmos DB weiterhin, aber Sie haben keinen Zugriff auf neue Funktionen.

Was muss ich tun, wenn ich meine Anwendung nicht vor einem Stichtag aktualisieren kann?

Es wird empfohlen, so früh wie möglich auf das neueste SDK zu aktualisieren. Nachdem ein SDK für die Einstellung markiert wurde, bleiben Ihnen 12 Monate zur Aktualisierung Ihrer Anwendung. Wenn Sie nicht nach dem Einstellungsdatum aktualisieren können, werden anforderungen, die von den eingestellten Versionen des SDK gesendet werden, weiterhin von Azure Cosmos DB bereitgestellt, sodass Ihre ausgeführten Anwendungen weiterhin funktionieren. Aber Azure Cosmos DB werden keine Fehlerbehebungen mehr vornehmen, neue Features hinzufügen oder Unterstützung für die eingestellten SDK-Versionen bereitstellen.

Wenn Sie über einen Supportplan verfügen und technischen Support benötigen, kontaktieren Sie uns, indem Sie ein Supportticket erstellen.

Wie kann ich anfordern, dass Features zu einem SDK oder Connector hinzugefügt werden?

Neue Features werden nicht immer jedem SDK oder Connector sofort hinzugefügt. Wenn eine Funktion, die Ihrer Meinung hinzugefügt werden sollte, nicht unterstützt wird, fügen Sie bitte unserem Communityforum ein Feedback hinzu.

Siehe auch

Weitere Informationen zu Azure Cosmos DB finden Sie auf Microsoft Azure Cosmos DB Service page.