Partager via

SDK .NET v3 Azure Cosmos DB pour l’API pour NoSQL : Téléchargement et notes de publication

S’APPLIQUE À : NoSQL

Liens
Notes de publication Notes de publication
Téléchargement du Kit de développement logiciel (SDK) NuGet
Documentation de l’API Documentation de référence sur l’API .NET
Exemples Exemples de code .NET
Prise en main Prise en main du Kit de développement logiciel (SDK) .NET Azure Cosmos DB
Bonnes pratiques Bonnes pratiques pour le SDK .NET Azure Cosmos DB
Tutoriel Entity Framework Core Entity Framework Core avec le fournisseur Azure Cosmos DB
Infrastructure actuellement prise en charge Microsoft .NET Standard 2.0

Historique des mises en production

L’historique des versions est conservé dans le référentiel source du kit de développement logiciel (SDK) .NET Azure Cosmos DB. Pour obtenir une liste détaillée des mises en production de fonctionnalités et des bogues résolus dans chaque version, consultez la Documentation du journal des modifications du SDK

Différentes sous-versions des Kits de développement logiciel (SDK) .NET sont disponibles sous la version 3.x.x. La version minimale recommandée est 3.47.0.

Problèmes connus

Pour obtenir la liste des problèmes connus avec la version minimale recommandée du Kit de développement logiciel (SDK), consultez la section des problèmes connus.

Gestion des dépendances Newtonsoft.Json

Aperçu

Le Kit de développement logiciel (SDK) .NET Azure Cosmos DB dépend des Newtonsoft.Json opérations de sérialisation JSON. Cette dépendance n’est pas gérée automatiquement : vous devez ajouter Newtonsoft.Json explicitement en tant que dépendance directe dans votre projet.

Le SDK se compile sur Newtonsoft.Json 10.x en interne, qui a une vulnérabilité de sécurité connue. Bien que le Kit de développement logiciel (SDK) soit techniquement compatible avec la version 10.x et que l’utilisation du SDK de Newtonsoft.Json n’est pas sensible au problème de sécurité signalé, nous vous recommandons toujours d’utiliser la version 13.0.3 ou ultérieure pour éviter les éventuels problèmes de sécurité ou conflits. Les versions 13.x incluent des changements cassants, mais les modèles d’utilisation du Kit de développement logiciel (SDK) sont compatibles avec ces modifications.

Important

Cette dépendance est requise même lorsque vous utilisez System.Text.Json des types définis par l’utilisateur via CosmosClientOptions.UseSystemTextJsonSerializerWithOptions, car les opérations internes du SDK utilisent toujours Newtonsoft.Json pour les types système.

Ajoutez toujours Newtonsoft.Json explicitement la version 13.0.3 ou ultérieure en tant que dépendance directe lors de l’utilisation du Kit de développement logiciel (SDK) .NET Azure Cosmos DB v3. N’utilisez pas la version 10.x en raison de vulnérabilités de sécurité connues.

Pour les projets .csproj standard

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

Pour les projets utilisant la gestion centralisée des packages

Si votre projet utilise Directory.Packages.props:

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

Résolution des problèmes de conflits de version

Référence Newtonsoft.Json manquante

Si vous rencontrez une erreur de build telle que :

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.

Cette erreur est générée intentionnellement par les cibles de build du Kit de développement logiciel (SDK) Cosmos DB pour vous assurer que la dépendance est correctement configurée.

Solution pour les applications :

Ajoutez une référence explicite à Newtonsoft.Json, comme indiqué dans la section Configuration recommandée ci-dessus.

Solution pour les bibliothèques :

Si vous créez une bibliothèque (et non une application) et souhaitez différer la dépendance Newtonsoft.Json aux consommateurs de votre bibliothèque, vous pouvez contourner cette vérification en définissant la propriété MSBuild dans votre .csproj:

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

Avertissement

Utilisez ce contournement uniquement lors de la création de bibliothèques où les utilisateurs finaux fournissent la dépendance Newtonsoft.Json. Pour les applications, ajoutez toujours la référence explicite.

Conflits de version de package

Si vous rencontrez des erreurs de génération telles que :

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

Solution:

  1. Identifiez la version requise en vérifiant quels packages ont besoin de versions plus récentes :

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

  2. Mettez à jour votre version de package centralisée pour qu’elle corresponde ou dépasse la version la plus élevée requise :

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

  3. Nettoyer et reconstruire :

    dotnet clean
dotnet restore
dotnet build

Compatibilité des versions

Le tableau suivant présente les versions minimales recommandées de Newtonsoft.Json pour chaque version du Kit de développement logiciel (SDK) Cosmos DB. Bien que le Kit de développement logiciel (SDK) puisse fonctionner techniquement avec la version 10.x, ces versions ne doivent jamais être utilisées en raison de vulnérabilités de sécurité.

Version du Kit de développement logiciel (SDK) Cosmos DB Version minimale sécurisée Recommended
3.47.0+ 13.0.3 13.0.4
3.54.0+ 13.0.4 13.0.4

Conseil / Astuce

Lorsque vous utilisez .NET Aspire 13.0.0 ou version ultérieure, vérifiez qu’il Newtonsoft.Json se trouve à la version 13.0.4 pour éviter les conflits avec les composants Azure d’Aspire.

Meilleures pratiques

  • Toujours ajouter en tant que dépendance directe : le Kit de développement logiciel (SDK) ne gère pas automatiquement cette dépendance pour vous
  • Utiliser la version 13.0.3 ou ultérieure : n’utilisez jamais 10.x malgré la compatibilité technique, en raison des vulnérabilités de sécurité connues
  • Obligatoire même avec System.Text.Json : vous devez inclure Newtonsoft.Json même lors de l’utilisation UseSystemTextJsonSerializerWithOptions, car le SDK l’utilise en interne pour les types système
  • Épingler la version explicitement - Ne vous fiez pas à la résolution des dépendances transitives
  • Surveiller les avertissements - Traiter les avertissements de rétrogradation du package NuGet (NU1109) comme des erreurs dans les pipelines CI/CD

Questions fréquentes (FAQ)

Comment serai-je informé du retrait du kit SDK ?

Microsoft vous avertit 12 mois à l’avance de la fin de la prise en charge d’un kit SDK mis hors service afin de favoriser une transition en douceur vers un kit SDK pris en charge. Nous vous informons via différents canaux de communication : le portail Azure, les mises à jour Azure et une communication directe avec les administrateurs de service affectés.

Pendant cette période de 12 mois, puis-je créer des applications à l’aide d’un kit SDK Azure Cosmos DB destiné à être mis hors service ?

Oui, au cours de la période de préavis de 12 mois, vous pouvez créer, déployer et modifier des applications à l’aide du kit SDK Azure Cosmos DB destiné à être mis hors service. Nous vous conseillons de migrer vers une version prise en charge plus récente du kit SDK Azure Cosmos DB pendant cette période de 12 mois, le cas échéant.

Après la date de mise hors service, qu’advient-il des applications qui utilisent le kit SDK Azure Cosmos DB non pris en charge ?

Après la date de mise hors service, Azure Cosmos DB n’apporte plus de correctifs de bogues, n’ajoute plus de nouvelles fonctionnalités et ne fournit plus de support aux versions mises hors service du kit SDK. Si vous préférez ne pas effectuer la mise à niveau, les requêtes envoyées depuis les versions mises hors service du Kit de développement logiciel (SDK) continueront d’être traitées par le service Azure Cosmos DB.

Quelles versions du kit SDK disposent des dernières fonctionnalités et mises à jour ?

Les nouvelles fonctionnalités et mises à jour ne sont ajoutées qu’à la dernière version mineure de la dernière version majeure prise en charge du kit SDK. Nous vous recommandons de toujours utiliser la dernière version pour tirer parti des nouvelles fonctionnalités, des améliorations des performances et des correctifs de bogues. Si vous utilisez une ancienne version du kit SDK encore en service, vos requêtes vers Azure Cosmos DB continuent de fonctionner, mais vous n’avez accès à aucune des nouvelles fonctionnalités.

Que faire si je ne parviens pas à mettre à jour mon application avant la date limite ?

Nous vous recommandons de mettre à niveau vers la dernière version du kit de développement logiciel dès que possible. Une fois qu’un kit SDK est marqué pour la mise hors service, vous avez 12 mois pour mettre à jour votre application. Si vous n’êtes pas en mesure de procéder à une mise à jour avant la date de mise hors service, les requêtes envoyées à partir des versions mises hors service du kit SDK continuent d’être traitées par Azure Cosmos DB. Vos applications continuent donc de fonctionner. Toutefois, Azure Cosmos DB n’apporte plus de correctifs de bogues, n’ajoute plus de nouvelles fonctionnalités et ne fournit plus de support aux versions mises hors service du kit SDK.

Si vous disposez d’un plan de support et avez besoin d’assistance technique, veuillez nous contacter en remplissant un ticket de support.

Comment puis-je demander l’ajout de fonctionnalités à un SDK ou un connecteur ?

Les nouvelles fonctionnalités ne sont pas toujours ajoutées à chaque SDK ou connecteur immédiatement. S’il existe une fonctionnalité non prise en charge que vous souhaitez ajouter, ajoutez des commentaires à notre forum communautaire.

Voir aussi

Pour en savoir plus sur Azure Cosmos DB, consultez la page du service Microsoft Azure Cosmos DB.

  • Last updated on