Sada .NET Change Feed Processor SDK: Stažení a poznámky k verzi (starší verze)

Článek
05/24/2023

PLATÍ PRO: NoSQL

	Odkazy
Stažení sady SDK	NuGet
Dokumentace k rozhraní API	Referenční dokumentace k rozhraní API knihovny procesoru kanálu změn
Začínáme	Začínáme se sadou SDK .NET s procesorem kanálu změn
Aktuální podporovaná architektura	Microsoft .NET Framework 4.5 Microsoft .NET Core

Poznámka:

Pokud používáte procesor kanálu změn, podívejte se na nejnovější verzi 3.x sady .NET SDK, ve které je zabudovaný kanál změn.

Poznámky k verzi

Buildy v2

2.5.0

Přidání nového konstruktoru Microsoft.Azure.Documents.ChangeFeedProcessor.Logging.TraceLogProvider pro třídu, která přebírá instanci System.Diagnostics.TraceSource jako argument. To umožňuje TraceLogProviderprogramově vytvořit trasování .net z vlastní TraceSource instance inicializované ve zdrojovém kódu. Před touto změnou bylo možné nakonfigurovat trasování .net pouze pomocí souboru App.config.

2.4.0

Přidání podpory pro kolekce zapůjčení, které lze rozdělit pomocí klíče oddílu definovaného jako /partitionKey. Před touto změnou by se klíč oddílu kolekce zapůjčení musel definovat jako /ID.
Tato verze umožňuje používat kolekce zapůjčení s rozhraním API pro Gremlin, protože kolekce Gremlin nemohou mít klíč oddílu definovaný jako /ID.

2.3.2

Přidali jsme kompatibilitu úložiště zapůjčení se sadou SDK v3, která umožňuje cesty migrace horké vrstvy. Aplikace může migrovat na sadu SDK v3 a zpátky do knihovny procesoru kanálu změn bez ztráty stavu.

2.3.1

Opravili jsme situaci, kdy se důvod ukončení FeedProcessing.ChangeFeedObserverCloseReason.Unknown v případě nenalezení oblasti nebo nesouladu aktuálnosti cílové repliky s relací čtení odeslal do FeedProcessing.IChangeFeedObserver.CloseAsync. V těchto případech se teď používají důvody ukončení FeedProcessing.ChangeFeedObserverCloseReason.ResourceGone a FeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable.
Přidali jsme nový důvod ukončení FeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable, který se odešle za účelem ukončení pozorovatele kanálu změn, když není aktuálnost cílové repliky v souladu s relací čtení.

2.3.0

Přidali jsme novou metodu ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory a odpovídající veřejné rozhraní ICheckpointPartitionProcessorFactory. To umožňuje implementaci rozhraní IPartitionProcessor používat integrovaný mechanismus kontrolních bodů. Nový objekt pro vytváření je podobný stávajícímu objektu IPartitionProcessorFactory s tím rozdílem, že jeho metoda Create přijímá také parametr ILeaseCheckpointer.
Pro stejnou instanci ChangeFeedProcessorBuilder se dá použít jenom jedna z těchto dvou metod, tedy buď ChangeFeedProcessorBuilder.WithPartitionProcessorFactory, nebo ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory.

2.2.8

Vylepšení stability a diagnostiky:
- Přidali jsme podporu detekce příliš dlouhé doby čtení kanálu změn. Pokud trvá déle, než je hodnota zadaná ChangeFeedProcessorOptions.ChangeFeedTimeout vlastností, je třeba provést následující kroky:
  - Dojde k přerušení operace čtení kanálu změn v problematickém oddílu.
  - Instance procesoru kanálu změn zruší vlastnictví problematického zapůjčení. Zrušené zapůjčení se vybere během příštího kroku získání zapůjčení, který provede stejná nebo jiná instance procesoru kanálu změn. Čtení kanálu změn tak začne zase od začátku.
  - Monitoru stavu se nahlásí problém. Výchozí monitor stavu odesílá všechny nahlášené problémy do protokolu trasování.
- Přidali jsme novou veřejnou vlastnost: ChangeFeedProcessorOptions.ChangeFeedTimeout. Výchozí hodnota této vlastnosti je 10 minut.
- Přidali jsme novou veřejnou hodnotu výčtu: Monitoring.MonitoredOperation.ReadChangeFeed. Když je hodnota HealthMonitoringRecord.Operation nastavená na Monitoring.MonitoredOperation.ReadChangeFeed, znamená to, že daný problém se stavem souvisí se čtením kanálu změn.

2.2.7

Vylepšená strategie vyrovnávání zatížení pro scénář, kdy získání všech zapůjčení trvá déle než interval vypršení platnosti zapůjčení, například kvůli problémům se sítí:
- V tomto scénáři algoritmus vyrovnávání zatížení nesprávně považoval zapůjčení za zapůjčení s prošlou platností, což vedlo k rušení zapůjčení aktivním vlastníkům. To by mohlo způsobit zbytečné vyrovnávání mnoha zapůjčení.
- Tento problém jsme v této verzi opravili, takže už se při konfliktech během získávání zapůjčení s prošlou platností, jejichž vlastník se nezměnil, neprovádí opakované pokusy a získání zapůjčení s prošlou platností se odkládá na další iteraci vyrovnávání zatížení.

2.2.6

Vylepšené zpracování výjimek pozorovatele.
Bohatší informace o chybách pozorovatele:
- Když se pozorovatel ukončí kvůli výjimce metody ProcessChangesAsync pozorovatele, metoda CloseAsync teď dostane parametr důvodu nastavený na hodnotu ChangeFeedObserverCloseReason.ObserverError.
- Přidali jsme trasování za účelem identifikaci chyb v uživatelském kódu v pozorovateli.

2.2.5

Přidali jsme podporu pro zpracování rozdělení v kolekcích, které využívají propustnost sdílené databáze.
- Tato verze opravuje problém, ke kterému může dojít během rozdělení v kolekcích využívajících propustnost sdílené databáze, když rozdělení vede k vyrovnávání oddílů jen s jedním vytvořeným rozsahem klíčů podřízeného oddílu namísto dvou. Pokud k tomu dojde, může se procesor kanálu změn při odstraňování zapůjčení starého rozsahu klíčů oddílu zablokovat, takže pak nevytváří nová zapůjčení. Tento problém je v této verzi opravený.

2.2.4

Přidali jsme novou vlastnost ChangeFeedProcessorOptions.StartContinuation, která podporuje spuštění kanálu změn od tokenu pro pokračování požadavku. Používá se jen tehdy, když je kolekce zapůjčení prázdná nebo když nemá zapůjčení nastavený token ContinuationToken. U zapůjčení v kolekci zapůjčení, která mají nastavený token ContinuationToken, se použije tento token ContinuationToken a vlastnost ChangeFeedProcessorOptions.StartContinuation se ignoruje.

2.2.3

Přidali jsme podporu použití vlastního úložiště k zachování tokenů pro pokračování každého oddílu.
- Vlastní úložiště zapůjčení může být třeba kolekce zapůjčení Azure Cosmos DB rozdělená jakýmkoli vlastním způsobem.
- Vlastní úložiště zapůjčení můžou využívat nový bod rozšiřitelnosti ChangeFeedProcessorBuilder.WithLeaseStoreManager(ILeaseStoreManager) a veřejné rozhraní ILeaseStoreManager.
- Došlo k refaktorování rozhraní ILeaseManager do rozhraní s více rolemi.
Menší změna způsobující chybu: Došlo k odebrání bodu rozšiřitelnosti ChangeFeedProcessorBuilder.WithLeaseManager(ILeaseManager), použijte místo něj bod rozšiřitelnosti ChangeFeedProcessorBuilder.WithLeaseStoreManager(ILeaseStoreManager).

2.2.2

Tato verze opravuje problém, ke kterému dochází při zpracování rozdělení v monitorované kolekci a při používání kolekce zapůjčení rozdělené na oddíly. Při zpracování zapůjčení pro rozdělený oddíl se může stát, že se neodstraní zapůjčení odpovídající tomuto oddílu. Tento problém je v této verzi opravený.

2.2.1

Opravený výpočet nástroje pro posouzení pro účty s více oblastmi zápisu a novým formátem tokenu relace.

2.2.0

Přidali jsme podporu kolekcí zapůjčení rozdělených na oddíly. Klíč oddílu musí být definovaný jako /id.
Menší změna způsobující chybu: Došlo ke změně metod rozhraní IChangeFeedDocumentClient interface a třídy ChangeFeedDocumentClient, takže teď zahrnují parametry RequestOptions a CancellationToken. IChangeFeedDocumentClient je pokročilý bod rozšiřitelnosti, který umožňuje poskytnout vlastní implementaci klienta dokumentu, která se má použít s procesorem kanálu změn, například ozdobit DocumentClient a zachytit všechna volání k provádění dodatečného trasování, zpracování chyb atd. V této aktualizaci bude nutné změnit kód, který implementuje IChangeFeedDocumentClient, aby zahrnoval nové parametry v implementaci.
Menší vylepšení diagnostiky.

2.1.0

Přidali jsme nové rozhraní API Task<IReadOnlyList<RemainingPartitionWork>> IRemainingWorkEstimator.GetEstimatedRemainingWorkPerPartitionAsync(). Dá se použít k získání odhadu objemu práce v každém oddílu.
Podporuje sadu Microsoft.Azure.DocumentDB SDK 2.0. Vyžaduje Microsoft.Azure.DocumentDB 2.0 nebo vyšší.

2.0.6

Kvůli kompatibilitě s verzí 1 jsme přidali veřejnou vlastnost ChangeFeedEventHost.HostName.

2.0.5

Opravili jsme konflikt časování, ke kterému dochází při rozdělení oddílu. Konflikt časování může vést k tomu, že se během dělení oddílu získá zapůjčení a hned se zase zruší, což může způsobovat spory. Problém s konfliktem časování je v této verzi vyřešený.

2.0.4

Sada GA SDK

2.0.3 – předběžná verze

Opravené následující problémy:
- Po rozdělení oddílu by mohlo docházet k duplicitnímu zpracování dokumentů upravených před rozdělením.
- Když kolekce zapůjčení neobsahovala žádná zapůjčení, rozhraní API GetEstimatedRemainingWork vrátilo hodnotu 0.
Zveřejnili jsme následující výjimky. Tyto výjimky můžou vydávat rozšíření, která implementují rozhraní IPartitionProcessor.
- 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 – předběžná verze

Menší změny rozhraní API:
- Došlo k odebrání položky ChangeFeedProcessorOptions.IsAutoCheckpointEnabled, kterou jsme označili za zastaralou.

2.0.1 – předběžná verze

Vylepšení stability:
- Lepší zpracování inicializace úložiště zapůjčení. Pokud je úložiště zapůjčení prázdné, může ho inicializovat jenom jedna instance procesoru a ostatní budou čekat.
- Stabilnější/efektivnější prodloužení/uvolnění zapůjčení. Prodloužení a uvolnění zapůjčení z jednoho oddílu není závislé na prodloužení jiných zapůjčení. Ve verzi 1 tento proces probíhal postupně pro všechny oddíly.
Nové rozhraní API v2:
- Vzor tvůrce pro flexibilní konstrukci procesoru: třída ChangeFeedProcessorBuilder.
  - Přijímá libovolnou kombinaci parametrů.
  - Může přijmout instanci DocumentClient pro monitorování nebo kolekci zapůjčení (ve verzi 1 není k dispozici).
- IChangeFeedObserver.ProcessChangesAsync teď přijímá parametr CancellationToken.
- IRemainingWorkEstimator – nástroj pro posouzení zbývající práce se dá používat nezávisle na procesoru.
- Nové body rozšiřitelnosti:
  - IPartitionLoadBalancingStrategy – pro vlastní vyrovnávání zatížení oddílů mezi instancemi procesoru.
  - ILease, ILeaseManager – pro vlastní správu zapůjčení.
  - IPartitionProcessor – pro vlastní změny zpracování v určitém oddílu.
Logging – využívá knihovnu LibLog.
100% zpětně kompatibilní s rozhraním API verze 1.
Nový základ kódu.
Kompatibilní se sadou SQL .NET SDK verze 1.21.1 a vyšší.

Buildy v1

1.3.3

Přidali jsme další protokolování.
Opravili jsme únik třídy DocumentClient při vícenásobném volání odhadu nedokončené práce.

1.3.2

Opravuje odhad nedokončené práce.

1.3.1

Vylepšení stability.
- Oprava problému se zpracováním zrušených úloh, který mohl v některých oddílech způsobit zastavení pozorovatelů.
Podpora ručního vytváření kontrolních bodů.
Kompatibilní se sadou SQL .NET SDK verze 1.21 a vyšší.

1.2.0

Přidává podporu platformy .NET Standard 2.0. Balíček teď podporuje monikery architektury netstandard2.0 a net451.
Kompatibilní se sadou SQL .NET SDK verze 1.17.0 a vyšší.
Kompatibilní se sadou .NET Core SDK verze 1.5.1 a vyšší.

1.1.1

Opravuje problém s výpočtem odhadu zbývající práce, pokud byl kanál změn prázdný nebo nebyla k dispozici žádná nevyřízená práce.
Kompatibilní se sadou SQL .NET SDK verze 1.13.2 a vyšší.

1.1.0

Přidali jsme metodu pro získání odhadu zbývající práce, která se má zpracovat v kanálu změn.
Kompatibilní se sadou SQL .NET SDK verze 1.13.2 a vyšší.

1.0.0

Sada GA SDK
Kompatibilní se sadou SQL .NET SDK verze 1.14.1 nebo nižší.

Data vydání a vyřazení z provozu

Microsoft bude o vyřazení sady SDK informovat s předstihem nejméně 12 měsíců, aby mohlo dojít k bezproblémovému přechodu na novější/podporovanou verzi. Nové funkce, možnosti a optimalizace se přidávají jen do aktuální sady SDK, proto vám doporučujeme, abyste vždy co nejdříve provedli aktualizaci na nejnovější verzi sady SDK.

Upozorňující

Po 31. srpnu 2022 už Azure Cosmos DB nebude provádět opravy chyb, přidávat nové funkce a poskytovat podporu pro verze 1.x sady Azure Cosmos DB .NET nebo .NET Core SDK pro rozhraní API pro NoSQL. Pokud nechcete provést upgrade, služba Azure Cosmos DB bude dál zpracovávat požadavky odeslané z verze 1.x sady SDK.

Verze	Datum vydání	Datum vyřazení
2.5.0	15. května 2023	---
2.4.0	6. května 2021	---
2.3.2	11. srpna 2020	---
2.3.1	30. července 2020	---
2.3.0	2. dubna 2020	---
2.2.8	28. října 2019	---
2.2.7	14. května 2019	---
2.2.6	29. ledna 2019	---
2.2.5	13. prosince 2018	---
2.2.4	29. listopadu 2018	---
2.2.3	19. listopadu 2018	---
2.2.2	31. října 2018	---
2.2.1	24. října 2018	---
1.3.3	8. května 2018	---
1.3.2	18. dubna 2018	---
1.3.1	13. března 2018	---
1.2.0	31. října 2017	---
1.1.1	29. srpna 2017	---
1.1.0	13. srpna 2017	---
1.0.0	7. července 2017	---

Často kladené dotazy

Jak se dozvím o vyřazení sady SDK?

Microsoft oznámí ukončení podpory vyřazené sady SDK s 12měsíčním předstihem, aby mohlo dojít k bezproblémovému přechodu na podporovanou sadu SDK. Budeme vás informovat pomocí různých komunikačních kanálů: webu Azure Portal, aktualizací Azure a přímých zpráv určeným správcům služeb.

Můžu během těchto 12 měsíců vytvářet aplikace pomocí sady SDK Azure Cosmos DB určené k vyřazení z provozu?

Ano, během těchto 12 měsíců budete moct pomocí sady SDK Azure Cosmos DB určené k vyřazení z provozu vytvářet, nasazovat a upravovat aplikace. Doporučujeme vám během tohoto 12měsíčního období provést migraci na novější podporovanou verzi sady SDK Azure Cosmos DB.

Co se stane po datu vyřazení z provozu s aplikacemi, které používají nepodporovanou sadu SDK Azure Cosmos DB?

Po datu vyřazení už Azure Cosmos DB nebude u vyřazených verzí sady SDK provádět opravy chyb, přidávat nové funkce ani poskytovat podporu. Pokud nechcete provést upgrade, služba Azure Cosmos DB bude dál zpracovávat požadavky odeslané z vyřazených verzí sady SDK.

Které verze sady SDK budou mít nejnovější funkce a aktualizace?

Nové funkce a aktualizace se budou přidávat jenom do nejnovější podverze nejnovější podporované hlavní verze sady SDK. Doporučujeme vám vždy používat nejnovější verzi, abyste mohli využívat nové funkce, vylepšení výkonu a opravy chyb. Pokud používáte starou nevyřazenou verzi sady SDK, požadavky na Azure Cosmos DB budou pořád fungovat, ale nebudete mít přístup k žádným novým funkcím.

Co mám dělat, když nemůžu aktualizovat aplikaci před datem přerušení?

Doporučujeme vám co nejdřív provést upgrade na nejnovější sadu SDK. Jakmile označíme některou sadu SDK k vyřazení, máte na aktualizaci své aplikace ještě 12 měsíců. Pokud se vám nepodaří provést aktualizaci do data vyřazení, Azure Cosmos DB bude dál zpracovávat požadavky odeslané z vyřazených verzí sady SDK, takže vaše spuštěné aplikace budou dál fungovat. Azure Cosmos DB už ale nebude u vyřazených verzí sady SDK provádět opravy chyb, přidávat nové funkce ani poskytovat podporu.

Pokud máte plán podpory a potřebujete technickou podporu, kontaktujte nás vytvořením lístku podpory.

Jak můžu požádat o přidání funkcí do sady SDK nebo konektoru?

Nové funkce se vždy nepřidávají do každé sady SDK nebo konektoru okamžitě. Pokud není podporovaná funkce, kterou byste chtěli přidat, přidejte nám prosím svůj názor na fóru komunity.

Viz také

Další informace o službě Azure Cosmos DB najdete na stránce služby Microsoft Azure Cosmos DB .