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

  • Si applica a: ✅ NoSQL

Importante

È importante notare che la versione 3 di .NET SDK è attualmente disponibile e 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 di .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 Microsoft.Azure.Cosmosv2:

  • Azure Cosmos DB .NET Framework v1 SDK per l'API NoSQL
  • Azure Cosmos DB .NET Core SDK v1 per l'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
  • Miglioramenti maggiori per la diagnostica del trasporto diretto/TCP
  • Aggiornamenti sullo 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 ripetizione dei tentativi e dei livelli inferiori dell'SDK rimane in gran parte invariata.

Perché eseguire la migrazione a .NET v2 SDK

Oltre ai numerosi miglioramenti delle prestazioni, le nuove funzionalità effettuate nell'SDK più recente non verranno convertite nelle versioni precedenti.

Inoltre, gli SDK meno recenti 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 v1 SDK a v2 SDK

Modalità diretta + TCP

.NET v2 SDK 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à di SQL SDK di Azure Cosmos DB.

Formattazione del token di sessione

L'SDK v2 non usa più il formato di token di sessione semplice 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 Conversione dei formati di token di sessione in .NET SDK.

Utilizzo del Change Feed Processor SDK di .NET

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

La libreria 2.1.x presenta le modifiche chiave seguenti:

  • Miglioramenti della stabilità e della diagnobilità
  • Miglioramento della gestione degli errori e delle eccezioni
  • Supporto aggiuntivo per le raccolte di lease partizionate
  • Estensioni avanzate per implementare l'interfaccia e la ChangeFeedDocument classe per ulteriori operazioni di gestione e traccia degli errori
  • Aggiunta del supporto per l'uso di un archivio personalizzato per rendere persistenti i token di continuazione per partizione

Per ulteriori informazioni, vedere le note sulla versione della libreria dell'elaboratore di change feed.

Uso della libreria bulk executor

La libreria dell'executor in blocco v2 ha attualmente una dipendenza da Azure Cosmos DB .NET SDK 2.5.1 o versione successiva.

Per ulteriori informazioni, consultare la panoramica della libreria dell’esecutore bulk di Azure Cosmos DB e le note di rilascio della libreria dell’esecutore bulk .NET.

Passaggi successivi

  • Last updated on