Azure Cosmos DB .NET SDK v3 per API per NoSQL: download e note sulla versione

• .NET SDK v3
• .NET SDK V2
• .NET Core SDK v2
• .NET Change Feed SDK v2
• Node.js
• Java SDK v4
• Sincronizzare Java SDK v2
• Async Java SDK v2
• Spring Data v2
• Spring Data v3
• Spring Data v5
• Python
• Go
• REST
• Provider di risorse REST
• SQL
• executor Bulk - .NET v2
• executor Bulk - Java

	Links
Note di rilascio	Note di rilascio
Download dell'SDK	NuGet
Documentazione sull'API	Documentazione di riferimento API .NET
esempi di	Esempi di codice .NET
Operazioni preliminari	Introduzione ad Azure Cosmos DB .NET SDK
Procedure consigliate	Procedure consigliate per Azure Cosmos DB .NET SDK
Esercitazione su Entity Framework Core	Entity Framework Core con il provider Azure Cosmos DB
Framework attualmente supportato	Microsoft .NET Standard 2.0

Cronologia delle versioni

La cronologia delle versioni viene mantenuta nel repository di origine .NET SDK di Azure Cosmos DB. Per un elenco dettagliato delle versioni delle funzionalità e dei bug risolti in ogni versione, vedere la documentazione relativa al log delle modifiche dell'SDK

Versione consigliata

Le diverse versioni secondarie degli SDK .NET sono disponibili nella versione 3.x.x. La versione minima consigliata è 3.47.0.

Problemi noti

Per un elenco dei problemi noti relativi alla versione minima consigliata dell'SDK, vedere la sezione problemi noti.

Gestione delle dipendenze di Newtonsoft.Json

Overview

Azure Cosmos DB .NET SDK ha una dipendenza da Newtonsoft.Json per le operazioni di serializzazione JSON. Questa dipendenza non viene gestita automaticamente . È necessario aggiungere Newtonsoft.Json in modo esplicito come dipendenza diretta nel progetto.

L'SDK viene compilato internamente in Newtonsoft.Json 10.x, che presenta una vulnerabilità di sicurezza nota. Anche se l'SDK è tecnicamente compatibile con la versione 10.x e l'uso dell'SDK di Newtonsoft.Json non è soggetto al problema di sicurezza segnalato, è comunque consigliabile usare la versione 13.0.3 o successiva per evitare potenziali problemi di sicurezza o conflitti. Le versioni 13.x includono modifiche di rilievo, ma i modelli di utilizzo dell'SDK sono compatibili con queste modifiche.

Importante

Questa dipendenza è necessaria anche quando si usa System.Text.Json per i tipi definiti dall'utente tramite CosmosClientOptions.UseSystemTextJsonSerializerWithOptions, perché le operazioni interne dell'SDK usano ancora Newtonsoft.Json per i tipi di sistema.

Configurazione consigliata

Aggiungere Newtonsoft.Json sempre in modo esplicito la versione 13.0.3 o successiva come dipendenza diretta quando si usa Azure Cosmos DB .NET SDK v3. Non usare la versione 10.x a causa di vulnerabilità di sicurezza note.

Per progetti Standard .csproj

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

Per i progetti che usano la gestione pacchetti centrale

Se il progetto usa Directory.Packages.props:

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

Risoluzione dei conflitti di versione

Informazioni di riferimento su Newtonsoft.Json mancanti

Se si verifica un errore di compilazione simile al seguente:

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.

Questo errore viene generato intenzionalmente dalle destinazioni di compilazione di Cosmos DB SDK per assicurarsi che la dipendenza sia configurata correttamente.

Soluzione per le applicazioni:

Aggiungere un riferimento esplicito a Newtonsoft.Json, come illustrato nella sezione Configurazione consigliata precedente.

Soluzione per le librerie:

Se si sta creando una libreria (non un'applicazione) e si intende rinviare la dipendenza Newtonsoft.Json ai consumatori della libreria, è possibile ignorare questa verifica impostando la proprietà MSBuild in .csproj:

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

Avvertimento

Usare questo bypass solo quando si compilano librerie in cui gli utenti finali forniranno la dipendenza Newtonsoft.Json. Per le applicazioni, aggiungere sempre il riferimento esplicito.

Conflitti di versione del pacchetto

Se si verificano errori di compilazione come:

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

Soluzione:

1. Identificare la versione richiesta controllando quali pacchetti necessitano di versioni più recenti:

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

2. Aggiornare la versione centralizzata del pacchetto in modo che corrisponda o superi la versione più recente richiesta:

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

3. Pulizia e ricompilazione:

   dotnet clean
   dotnet restore
   dotnet build
   

Compatibilità delle versioni

La tabella seguente illustra le versioni sicure minime consigliate di Newtonsoft.Json per ogni versione di Cosmos DB SDK. Anche se l'SDK può funzionare tecnicamente con 10.x, queste versioni non devono mai essere usate a causa di vulnerabilità di sicurezza.

Versione di Cosmos DB SDK	Versione minima sicura	Recommended
3.47.0+	13.0.3	13.0.4
3.54.0+	13.0.4	13.0.4

Suggerimento

Quando si usa .NET Aspire 13.0.0 o versione successiva, assicurarsi che Newtonsoft.Json sia alla versione 13.0.4 per evitare conflitti con i componenti di Azure di Aspire.

Migliori pratiche

• Aggiungere sempre come dipendenza diretta : l'SDK non gestisce automaticamente questa dipendenza
• Usare la versione 13.0.3 o successiva : non usare mai la versione 10.x nonostante la compatibilità tecnica, a causa di vulnerabilità di sicurezza note
• Obbligatorio anche con System.Text.Json : è necessario includere Newtonsoft.Json anche quando si usa UseSystemTextJsonSerializerWithOptions, perché l'SDK lo usa internamente per i tipi di sistema
• Aggiungere la versione in modo esplicito : non fare affidamento sulla risoluzione delle dipendenze transitive
• Avvisi di monitoraggio - Trattare gli avvisi di downgrade del pacchetto NuGet (NU1109) come errori nelle pipeline CI/CD

---

Domande frequenti

In che modo si viene avvisati del ritiro degli SDK?

Microsoft fornirà un preavviso di 12 mesi prima della fine del supporto dell'SDK di ritiro per facilitare una transizione senza problemi a un SDK supportato. Verrà visualizzata una notifica tramite vari canali di comunicazione: il portale di Azure, gli aggiornamenti Azure e la comunicazione diretta agli amministratori del servizio assegnati.

Can I author applications by using a to-be-retired Azure Cosmos DB SDK during the 12-month period?

Sì, sarà possibile creare, distribuire e modificare le applicazioni usando il to-be-ritirato Azure Cosmos DB SDK durante il periodo di preavviso di 12 mesi. È consigliabile eseguire la migrazione a una versione più recente supportata di Azure Cosmos DB SDK durante il periodo di preavviso di 12 mesi, in base alle esigenze.

Dopo la data di ritiro, cosa accade alle applicazioni che usano l'SDK di Azure Cosmos DB non supportato?

Dopo la data di ritiro, Azure Cosmos DB non eseguirà più correzioni di bug, aggiungerà nuove funzionalità o fornirà supporto alle versioni dell'SDK ritirato. Se si preferisce non eseguire l'aggiornamento, le richieste inviate dalle versioni ritirata dell'SDK continueranno a essere gestite dal servizio Azure Cosmos DB.

Quali versioni dell'SDK avranno le funzionalità e gli aggiornamenti più recenti?

Le nuove funzionalità e gli aggiornamenti verranno aggiunti solo alla versione secondaria più recente della versione principale più recente supportata dell'SDK. È consigliabile usare sempre la versione più recente per sfruttare le nuove funzionalità, i miglioramenti delle prestazioni e le correzioni dei bug. Se si usa una versione precedente e non ritirata dell'SDK, le richieste di Azure Cosmos DB funzioneranno ancora, ma non si avrà accesso a nuove funzionalità.

Come si deve procedere se non è possibile aggiornare l'applicazione prima della data del ritiro?

Si consiglia di effettuare l'aggiornamento alla versione di SDK più recente quanto prima. Una volta che un SDK è stato contrassegnato per il ritiro, si avranno a disposizione 12 mesi per aggiornare l'applicazione. Se non è possibile eseguire l'aggiornamento in base alla data di ritiro, le richieste inviate dalle versioni ritirata dell'SDK continueranno a essere gestite da Azure Cosmos DB, quindi le applicazioni in esecuzione continueranno a funzionare. Tuttavia, Azure Cosmos DB non effettuerà più correzioni di bug, aggiungerà nuove funzionalità o fornirà supporto alle versioni dell'SDK ritirato.

Se si ha un piano di supporto e si richiede supporto tecnico, contattare Microsoft inviando un ticket di supporto.

Come è possibile richiedere l'aggiunta di funzionalità a un SDK o a un connettore?

Le nuove funzionalità non vengono sempre aggiunte immediatamente a ogni SDK o connettore. Se non è supportata una funzionalità che si vuole aggiungere, aggiungere commenti e suggerimenti al forum della community.

Vedere anche

Per altre informazioni sulle Azure Cosmos DB, vedere Microsoft Azure Cosmos DB pagina del servizio.