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

SI APPLICA A: NoSQL

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

Informazioni generali

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.

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 con estensione csproj standard

<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 vuole rinviare la dipendenza Newtonsoft.Json ai consumer della libreria, è possibile ignorare questa verifica impostando la proprietà MSBuild in .csproj:

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

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.

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
• Monitorare gli avvisi - Considerare 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 invierà un preavviso di 12 mesi prima fine del supporto dell'SDK in fase di ritiro per agevolare la transizione a un SDK supportato. Verrà inviata una notifica tramite diversi canali di comunicazione, ossia il portale di Azure, gli aggiornamenti di Azure e la comunicazione diretta con gli amministratori del servizio assegnati.

È possibile creare applicazioni usando una versione di Azure Cosmos DB SDK che sta per essere ritirata durante il periodo di 12 mesi?

Sì, durante il periodo di preavviso di 12 mesi sarà possibile creare, distribuire e modificare applicazioni usando la versione di Azure Cosmos DB SDK che sta per essere ritirata. Durante il periodo di preavviso di 12 mesi, è consigliabile eseguire la migrazione a una versione più recente supportata di Azure Cosmos DB SDK.

Dopo la data di ritiro, che cosa succede alle applicazioni che usano una versione di Azure Cosmos DB SDK non supportata?

Dopo la data di ritiro, Azure Cosmos DB non eseguirà più correzioni dei bug, non aggiungerà nuove funzionalità, né fornirà supporto per le versioni ritirate dell'SDK. Se si preferisce non eseguire l'aggiornamento, le richieste inviate dalle versioni ritirate 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 di SDK precedente, non ritirata, le richieste inviate ad Azure Cosmos DB continueranno a funzionare, ma non sarà possibile accedere alle 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 si è in grado di eseguire l'aggiornamento entro la data di ritiro, le richieste inviate dalle versioni ritirate dell'SDK continueranno a essere gestite da Azure Cosmos DB, quindi le applicazioni in esecuzione continueranno a funzionare. Tuttavia, Azure Cosmos DB non eseguirà più correzioni dei bug, non aggiungerà nuove funzionalità, né non fornirà supporto per le versioni ritirate dell'SDK.

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.

Vedi anche

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