.NET Change Feed Processor SDK: download e note sulla versione (legacy)

Articolo
05/24/2023

SI APPLICA A: NoSQL

	Collegamenti
Download dell'SDK	NuGet
Documentazione sull'API	Documentazione di riferimento sull'API della libreria del processore dei feed delle modifiche
Introduzione	Introduzione all'SDK del processore dei feed delle modifiche .NET
Framework attualmente supportato	Microsoft .NET Framework 4.5 Microsoft .NET Core

Nota

Se si usa il processore dei feed di modifiche, vedere la versione 3. x più recente di .NET SDK, che include il feed di modifiche incorporato nell'SDK.

Note sulla versione

Build della seconda versione

2.5.0

Aggiunta del nuovo costruttore per la Microsoft.Azure.Documents.ChangeFeedProcessor.Logging.TraceLogProvider classe che accetta un'istanza System.Diagnostics.TraceSource di come argomento. In questo modo , TraceLogProviderusato per la traccia .net, può essere creato a livello di codice da un'istanza personalizzata TraceSource inizializzata nel codice sorgente. Prima di questa modifica era possibile configurare solo la traccia .net usando il file App.config.

2.4.0

Aggiunta del supporto per le raccolte di lease che possono essere partizionate con la chiave di partizione definita come /partitionKey. Prima di questa modifica, la chiave di partizione della raccolta di lease deve essere definita come /id.
Questa versione consente l'uso di raccolte di lease con API per Gremlin, perché le raccolte Gremlin non possono avere la chiave di partizione definita come /id.

2.3.2

Aggiunta la compatibilità dell'archivio di lease con [l'SDK v3 che consente percorsi di migrazione critici. È possibile eseguire la migrazione all'SDK v3 e ritrasferirla alla libreria del processore del feed di modifiche senza perdere alcuno stato.

2.3.1

Correzione di un caso per cui viene inviato il motivo di chiusura FeedProcessing.ChangeFeedObserverCloseReason.Unknown a FeedProcessing.IChangeFeedObserver.CloseAsync se non è possibile trovare la partizione o se la replica di destinazione non è aggiornata con la sessione di lettura. In questi casi vengono ora usati i motivi di chiusura FeedProcessing.ChangeFeedObserverCloseReason.ResourceGone e FeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable.
Aggiunto un nuovo motivo di chiusura FeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable inviato per chiudere l'osservatore del feed di modifiche quando la replica di destinazione non è aggiornata con la sessione di lettura.

2.3.0

Aggiunta di un nuovo metodo ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory e dell'interfaccia pubblica corrispondente ICheckpointPartitionProcessorFactory. In questo modo un'implementazione dell'interfaccia IPartitionProcessor può usare il meccanismo di checkpoint incorporato. La nuova factory è simile all'elemento IPartitionProcessorFactory esistente, con la differenza che il metodo Create accetta anche il parametro ILeaseCheckpointer.
Per la stessa istanza di ChangeFeedProcessorBuilder è possibile usare solo uno dei due metodi ChangeFeedProcessorBuilder.WithPartitionProcessorFactory e ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory.

2.2.8

Miglioramenti della stabilità e della diagnobilità:
- Aggiunta del supporto per rilevare operazioni di lettura del feed di modifiche che richiedono molto tempo. Quando il valore specificato dalla ChangeFeedProcessorOptions.ChangeFeedTimeout proprietà richiede più tempo, vengono eseguiti i passaggi seguenti:
  - L'operazione di lettura del feed di modifiche nella partizione problematica viene interrotta.
  - L'istanza del processore del feed di modifiche rilascia la proprietà del lease problematico. Il lease rilasciato verrà prelevato durante il passaggio di acquisizione del lease successivo che verrà eseguito dalla stessa istanza o da un'istanza diversa del processore del feed di modifiche. In questo modo, la lettura del feed delle modifiche potrà ricominciare.
  - Viene segnalato un problema al monitoraggio integrità. Il monitoraggio integrità predefinito invia tutti i problemi segnalati al log di traccia.
- Aggiunta di una nuova proprietà pubblica: ChangeFeedProcessorOptions.ChangeFeedTimeout. Il valore predefinito di questa proprietà è 10 minuti.
- Aggiunta di un nuovo valore di enumerazione pubblica: Monitoring.MonitoredOperation.ReadChangeFeed. Quando il valore di HealthMonitoringRecord.Operation è impostato su Monitoring.MonitoredOperation.ReadChangeFeed, il problema di integrità è correlato alla lettura del feed di modifiche.

2.2.7

Miglioramento della strategia di bilanciamento del carico per lo scenario quando il recupero di tutti i lease richiede più tempo rispetto all'intervallo di scadenza del lease, ad esempio a causa di problemi di rete:
- In questo scenario l'algoritmo di bilanciamento del carico considerava erroneamente i lease come scaduti causando il furto dei lease dai proprietari attivi. Questa situazione poteva attivare il ribilanciamento superfluo di un numero elevato di lease.
- Questo problema è stato risolto in questa versione, evitando nuovi tentativi in caso di conflitto durante l'acquisizione del lease scaduto che il proprietario non ha cambiato e posticipando l'acquisizione del lease scaduto alla successiva iterazione del bilanciamento del carico.

2.2.6

Gestione delle eccezioni di Observer migliorata.
Informazioni più dettagliate sugli errori observer:
- Quando un'istanza di Observer viene chiusa a causa di un'eccezione generata da ProcessChangesAsync di Observer, CloseAsync riceverà il parametro del motivo impostato su ChangeFeedObserverCloseReason.ObserverError.
- Sono state aggiunte funzionalità di analisi per identificare errori nel codice utente in un'istanza di Observer.

2.2.5

Aggiunta del supporto per la gestione della suddivisione nelle raccolte che usano la velocità effettiva per database condivisi.
- Questa versione corregge un problema che può verificarsi durante la divisione in raccolte che usano unità elaborate di database condivise, quando la divisione genera un ribilanciamento delle partizioni con la creazione di un solo intervallo di chiavi di partizione figlio, anziché di due. Quando ciò si verifica, il processore dei feed di modifiche può rimanere bloccato durante l'eliminazione del lease per l'intervallo di chiavi di partizione precedente e non creare nuovi lease. Il problema è stato corretto in questa versione.

2.2.4

Nuova proprietà aggiunta ChangeFeedProcessorOptions.StartContinuation per supportare l'avvio del feed di modifica dal token di continuazione della richiesta. Viene utilizzato solo quando la raccolta di lease è vuota o un lease non ha impostato ContinuationToken. Per i lease nella raccolta di lease con ContinuationToken impostato, viene usato ContinuationToken e viene ignorato ChangeFeedProcessorOptions.StartContinuation.

2.2.3

Aggiunto il supporto per l'uso dell’archivio personalizzato per rendere persistenti i token di continuazione per ogni partizione.
- Ad esempio, un archivio personalizzato lease può essere raccolta di lease Azure Cosmos DB partizionata in modo personalizzato.
- Gli archivi di lease personalizzati possono utilizzare il nuovo punto di estensibilità ChangeFeedProcessorBuilder.WithLeaseStoreManager (ILeaseStoreManager) e l’interfaccia pubblica ILeaseStoreManager.
- L'interfaccia di ILeaseManager è stata trasformata in interfacce di ruolo multiple.
Modifica di rilievo secondaria: rimosso il punto di estensibilità ChangeFeedProcessorBuilder.WithLeaseManager(ILeaseManager), viene utilizzato ChangeFeedProcessorBuilder.WithLeaseStoreManager(ILeaseStoreManager) al suo posto.

2.2.2

Questa versione corregge un problema che si verifica durante l'elaborazione di una divisione nella raccolta monitorata e l'utilizzo di una raccolta di lease partizionata. Durante l'elaborazione di un lease per partizione divisa, il lease corrispondente a quella partizione non può essere eliminato. Il problema è stato corretto in questa versione.

2.2.1

Correzione del calcolo di stima per gli account con più aree di scrittura e nuovo formato di token di sessione.

2.2.0

Aggiunta del supporto per le raccolte partizionate di lease. La chiave di partizione deve essere definita come /id.
Modifica che causa un'interruzione minore: i metodi dell'interfaccia IChangeFeedDocumentClient e la classe ChangeFeedDocumentClient sono stati modificati per includere i parametri RequestOptions e CancellationToken. IChangeFeedDocumentClient è un punto di estendibilità avanzato che consente di fornire un'implementazione personalizzata del client di documenti da usare con processore feed di modifiche, ad esempio decorare DocumentClient e intercettare tutte le chiamate a esso per eseguire tracce aggiuntive, gestione degli errori e così via. Con questo aggiornamento, il codice che implementa IChangeFeedDocumentClient dovrà essere modificato per includere nuovi parametri nell'implementazione.
Miglioramenti della diagnostica secondari.

2.1.0

È stata aggiunta una nuova API, Task<IReadOnlyList<RemainingPartitionWork>> IRemainingWorkEstimator.GetEstimatedRemainingWorkPerPartitionAsync(), utilizzabile per ottenere il lavoro stimato per ogni partizione.
Supporta Microsoft.Azure.DocumentDB SDK 2.0. Richiede Microsoft.Azure.DocumentDB 2.0 o versione successiva.

2.0.6

È stata aggiunta la proprietà pubblica ChangeFeedEventHost.HostName per la compatibilità con la versione 1.

2.0.5

È stata corretta una race condition che si verifica durante la suddivisione della partizione. Per effetto della race condition è possibile che il lease venga acquisito e immediatamente perso durante la suddivisione della partizione, provocando una contesa. Con questa versione il problema della race condition è stato risolto.

2.0.4

SDK con disponibilità generale

Versione provvisoria 2.0.3

Sono stati corretti i problemi seguenti:
- Quando si verifica la suddivisione della partizione, può verificarsi l'elaborazione duplicati dei documenti modificati prima della divisione.
- L'API GetEstimatedRemainingWork ha restituito 0 se non era presente alcun lease nella raccolta di lease.
Le eccezioni seguenti sono rese pubbliche. Le estensioni che implementano IPartitionProcessor possono generare queste eccezioni.
- Microsoft.Azure.Documents.ChangeFeedProcessor.Exceptions.LeaseLostException.
- Microsoft.Azure.Documents.ChangeFeedProcessor.Exceptions.PartitionException.
- Microsoft.Azure.Documents.ChangeFeedProcessor.Exceptions.PartitionNotFoundException.
- Microsoft.Azure.Documents.ChangeFeedProcessor.Exceptions.PartitionSplitException.

2.0.2-prerelease

Modifiche minime all'API:
- Rimozione di ChangeFeedProcessorOptions.IsAutoCheckpointEnabled, contrassegnato come obsoleto.

2.0.1-prerelease

Miglioramenti della stabilità:
- Gestione migliorata dell'inizializzazione dell'archivio dei lease. Quando l'archivio dei lease è vuoto, solo un'istanza del processore può inizializzarlo, mentre le altre rimarranno in attesa.
- Rilascio/rinnovo di un lease più stabile/efficiente. Il rinnovo e il rilascio di un lease con una partizione è indipendente dal rinnovo degli altri. Nella versione v1 questa operazione veniva eseguita in sequenza per tutte le partizioni.
Nuova API v2:
- Modello di generatore per la costruzione flessibile del processore: classe ChangeFeedProcessorBuilder.
  - Può accettare qualsiasi combinazione di parametri.
  - Può accettare l'istanza DocumentClient per il monitoraggio e/o la raccolta di lease (non disponibile in v1).
- IChangeFeedObserver.ProcessChangesAsync accetta ora CancellationToken.
- IRemainingWorkEstimator: la stima del lavoro rimanente può essere usata separatamente dal processore.
- Nuovi punti di estendibilità:
  - IPartitionLoadBalancingStrategy: per il bilanciamento del carico personalizzato di partizioni tra istanze del processore.
  - ILease, ILeaseManager: per la gestione personalizzata dei lease.
  - IPartitionProcessor: per modifiche di elaborazione personalizzate in una partizione.
Registrazione: usa la libreria LibLog.
100% compatibile con l'API v1.
Nuova codebase.
Compatibile con SQL .NET SDK 1.21.1 e versioni successive.

Build della prima versione

1.3.3

Aggiunta di maggiore registrazione.
Correzione di un problema DocumentClient quando si chiama più volte la stima del lavoro in sospeso.

1.3.2

Correzioni per la stima del lavoro in sospeso.

1.3.1

Miglioramenti alla stabilità.
- Correzione per la gestione del problema delle attività annullate che potrebbe comportare l'arresto degli osservatori in alcune partizioni.
Supporto per la creazione di checkpoint manuale.
Compatibile con SQL .NET SDK 1.21 e versioni successive.

1.2.0

Aggiunge il supporto per .NET Standard 2.0. Il pacchetto ora supporta i moniker framework netstandard2.0 e net451.
Compatibile con SQL .NET SDK 1.17.0 e versioni successive.
Compatibile con SQL .NET Core SDK 1.5.1 e versioni successive.

1.1.1

Correzione di un problema relativo al calcolo della stima del lavoro rimanente quando il feed di modifiche è vuoto o non ci sono lavori in sospeso.
Compatibile con SQL .NET SDK 1.13.2 e versioni successive.

1.1.0

Aggiungere un metodo per ottenere una stima di quanto resta da elaborare nel feed delle modifiche.
Compatibile con SQL .NET SDK 1.13.2 e versioni successive.

1.0.0

SDK con disponibilità generale
Compatibile con SQL .NET SDK 1.14.1 e versioni precedenti.

Date di rilascio e di ritiro

Microsoft invierà una notifica almeno 12 mesi prima del ritiro di un SDK per agevolare la transizione a una versione più recente o supportata. Le nuove caratteristiche e funzionalità e le ottimizzazioni vengono aggiunte solo all'SDK corrente. È quindi consigliabile eseguire sempre l'aggiornamento alla versione più recente dell'SDK quanto prima.

Avviso

Dopo il 31 agosto 2022, Azure Cosmos DB non eseguirà più correzioni di bug, aggiungerà nuove funzionalità e fornirà supporto alle versioni 1.x di Azure Cosmos DB .NET o .NET Core SDK per l'API per NoSQL. Se si preferisce non eseguire l'aggiornamento, le richieste inviate dalla versione 1.x dell'SDK continueranno a essere gestite dal servizio Azure Cosmos DB.

Versione	Data di rilascio	Data di ritiro
2.5.0	15 magg. 2023	---
2.4.0	6 maggio 2021	---
2.3.2	11 agosto 2020	---
2.3.1	30 luglio 2020	---
2.3.0	2 aprile 2020	---
2.2.8	28 ottobre 2019	---
2.2.7	14 maggio 2019	---
2.2.6	29 gennaio 2019	---
2.2.5	13 dicembre 2018	---
2.2.4	29 novembre 2018	---
2.2.3	19 novembre 2018	---
2.2.2	31 ottobre 2018	---
2.2.1	24 ottobre 2018	---
1.3.3	8 maggio 2018	---
1.3.2	18 aprile 2018	---
1.3.1	13 marzo 2018	---
1.2.0	31 ottobre 2017	---
1.1.1	29 agosto 2017	---
1.1.0	13 agosto 2017	---
1.0.0	07 luglio 2017	---

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 .