Condividi tramite

Eseguire la migrazione dell'applicazione per usare Azure Cosmos DB .NET SDK v2

  • Articolo

SI APPLICA A: NoSQL

Importante

È importante notare che la versione 3 di .NET SDK è attualmente disponibile, mentre un piano di migrazione dalla versione 2 alla versione 3 è disponibile qui. Per informazioni su Azure Cosmos DB .NET SDK v2, vedere le note sulla versione, il repository GitHub .NET, i suggerimenti sulle prestazioni per .NET SDK v2 e la guida alla risoluzione dei problemi.

Questo articolo illustra alcune considerazioni per aggiornare l'applicazione .NET v1 esistente ad Azure Cosmos DB .NET SDK v2 per API per NoSQL. Azure Cosmos DB .NET SDK v2 corrisponde allo spazio dei nomi Microsoft.Azure.DocumentDB. È possibile usare le informazioni fornite in questo documento se si esegue la migrazione dell'applicazione da una delle piattaforme .NET di Azure Cosmos DB seguenti per usare l'SDK v2 Microsoft.Azure.Cosmos:

  • Azure Cosmos DB .NET Framework v1 SDK per API per NoSQL
  • Azure Cosmos DB .NET Core SDK v1 per API per NoSQL

Elementi disponibili in .NET v2 SDK

L'SDK v2 contiene numerosi miglioramenti dell'usabilità e delle prestazioni, tra cui:

  • Supporto per la modalità diretta TCP per i client non Windows
  • Supporto per la scrittura in più aree
  • Miglioramenti delle prestazioni delle query
  • Supporto per raccolte geospaziali/geometriche e indicizzazione
  • Ulteriori miglioramenti per la diagnostica del trasporto diretto/TCP
  • Aggiornato lo stack di trasporto TCP diretto per ridurre il numero di connessioni stabilite
  • Miglioramenti della riduzione della latenza in RequestTimeout

La maggior parte della logica di retry e dei livelli inferiori dell'SDK rimane in gran parte invariata.

Perché eseguire la migrazione a SDK .NET v2

Oltre ai numerosi miglioramenti delle prestazioni, i nuovi investimenti di funzionalità effettuati nell'SDK più recente non verranno trasferiti alle versioni precedenti.

Inoltre, gli SDK precedenti verranno sostituiti da versioni più recenti e l'SDK v1 passerà alla modalità di manutenzione. Per un'esperienza di sviluppo ottimale, è consigliabile eseguire la migrazione dell'applicazione a una versione successiva dell'SDK.

Modifiche principali da SDK v1 a SDK v2

Modalità diretta + TCP

SDK .NET v2 supporta ora sia la modalità diretta che quella gateway. La modalità diretta supporta la connettività tramite protocollo TCP e offre prestazioni migliori perché si connette direttamente alle repliche back-end con un minor numero di hop di rete.

Per altre informazioni, vedere la guida alle modalità di connettività dell'SDK SQL di Azure Cosmos DB.

Formattazione del token di sessione

L'SDK v2 non usa più il formato semplice del token di sessione usato nella versione 1, ma usa la formattazione vettoriale. Il formato deve essere convertito quando si passa all'applicazione client con versioni diverse, poiché i formati non sono intercambiabili.

Per altre informazioni, vedere l'argomento relativo alla conversione dei formati di token di sessione in .NET SDK.

Uso dell'SDK del processore dei feed di modifiche .NET

La libreria del processore dei feed di modifiche .NET 2.1.x richiede Microsoft.Azure.DocumentDB 2.0 o versione successiva.

La libreria 2.1.x presenta le modifiche chiave seguenti:

  • Miglioramenti apportati alla stabilità e alla diagnostica
  • Gestione di errori ed eccezioni migliorata
  • Supporto aggiuntivo per le raccolte di lease partizionate
  • Estensioni avanzate per implementare l'interfaccia e la classe ChangeFeedDocument per ulteriori operazioni di gestione e traccia degli errori
  • Aggiunto il supporto per l'uso dell’archivio personalizzato per rendere persistenti i token di continuazione per ogni partizione

Per altre informazioni, vedere le note sulla versione della libreria del processore dei feed di modifiche.

Uso della libreria di esecuzione bulk

La libreria di esecuzione bulk v2 ha attualmente una dipendenza da Azure Cosmos DB .NET SDK 2.5.1 o versione successiva.

Per altre informazioni, vedere la panoramica della libreria di esecuzione bulk di Azure Cosmos DB e le note sulla versione della libreria di esecuzione bulk .NET.

Passaggi successivi