.NET Change Feed Processor SDK: Letöltési és kiadási megjegyzések (örökölt)

Cikk
01/10/2024

A KÖVETKEZŐRE VONATKOZIK: NoSQL

	Hivatkozások
SDK letöltése	NuGet
API-dokumentáció	A Change Feed Processor kódtár API referenciadokumentációja
Első lépések	Bevezetés a Change Feed Processor .NET SDK használatába
Jelenleg támogatott keretrendszer	Microsoft .NET-keretrendszer 4.5 Microsoft .NET Core

Feljegyzés

Ha a változáscsatorna-feldolgozót használja, tekintse át a .NET SDK legújabb, 3.x verzióját, amelybe bele van építve a változáscsatorna.

Kibocsátási megjegyzések

2-es verziójú buildek

2.5.0

Új konstruktort adott hozzá ahhoz az Microsoft.Azure.Documents.ChangeFeedProcessor.Logging.TraceLogProvider osztályhoz, amely argumentumként veszi fel a System.Diagnostics.TraceSource példányt. Ez lehetővé teszi a TraceLogProvider.net-nyomkövetéshez használt , programozott módon történő létrehozását egy forráskódban inicializált egyéni TraceSource példányból. A módosítás előtt csak az App.config fájl használatával lehetett konfigurálni a .net-nyomkövetést.

2.4.0

A /partitionKey néven definiált partíciókulccsal particionált bérletgyűjtemények támogatása hozzáadva. A módosítás előtt a bérletgyűjtemény partíciókulcsát /id néven kell definiálni.
Ez a kiadás lehetővé teszi a bérletgyűjtemények használatát a Gremlin API-val, mivel a Gremlin-gyűjtemények nem rendelkeznek /id partíciókulcsmal.

2.3.2

Mostantól a címbérlettárolók kompatibilisek a 3-as verziójú SDK-val, ami lehetővé teszi a gyors migrálási útvonalak használatát. Az alkalmazások migrálhatók a 3-as verziójú SDK-ra, és visszamigrálhatók a változáscsatorna-feldolgozó kódtárába, állapotvesztés nélkül.

2.3.1

Javítottuk azt az esetet, amikor a FeedProcessing.ChangeFeedObserverCloseReason.Unknown bezárási ok lett elküldve a FeedProcessing.IChangeFeedObserver.CloseAsync részére, ha a partíció nem található, vagy ha a célreplika nem naprakész az olvasási munkamenethez képest. Ezekben az esetekben már a FeedProcessing.ChangeFeedObserverCloseReason.ResourceGone és FeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable bezárási okokat használjuk.
Valamint hozzáadtunk egy új FeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable bezárási okot, amely azért küldhető el, hogy bezárja a változáscsatorna-figyelőt, ha a célreplika nem naprakész az olvasási munkamenethez képest.

2.3.0

Hozzáadtunk egy új ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory metódust és a hozzá tartozó ICheckpointPartitionProcessorFactory nyilvános felületet. Ez lehetővé teszi a IPartitionProcessor interfész implementálását, amely így a beépített ellenőrzőpont-mechanizmust használja. Az új előállító hasonló a meglévő IPartitionProcessorFactory előállítóhoz, azzal a különbséggel, hogy Create metódusa a ILeaseCheckpointer paramétert is használja.
A két metódus közül csak az egyik, tehát vagy a ChangeFeedProcessorBuilder.WithPartitionProcessorFactory, vagy a ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory használható egy adott ChangeFeedProcessorBuilder-példány esetében.

2.2.8

Stabilitási és diagnosztabilitási fejlesztések:
- Mostantól támogatott annak az észlelése, ha a változáscsatorna olvasása túl sokáig tart. Ha a tulajdonság által ChangeFeedProcessorOptions.ChangeFeedTimeout megadott értéknél hosszabb időt vesz igénybe, a következő lépéseket kell végrehajtania:
  - Megszakítja a változáscsatorna olvasásának műveletét a problémás partíción.
  - A változáscsatorna-feldolgozó példány elveti a problémás bérlet tulajdonjogát. Az elvetett bérlet a következő bérletbeolvasási lépés során lesz újra felvéve, amelyet ugyanaz a változáscsatorna-feldolgozó példány vagy egy másik változáscsatorna-feldolgozó példány is végrehajthat. Ezáltal a változáscsatorna olvasása elölről kezdődik.
  - A rendszer jelenti a problémát az állapotfigyelő felé. Az alapértelmezett állapotfigyelő az összes jelentett problémát elküldi a nyomkövetési naplóba.
- Hozzáadtunk egy új nyilvános tulajdonságot: ChangeFeedProcessorOptions.ChangeFeedTimeout. E tulajdonság alapértelmezett értéke 10 perc.
- Hozzáadtunk egy új felsorolási értéket: Monitoring.MonitoredOperation.ReadChangeFeed. Ha a HealthMonitoringRecord.Operation tulajdonság beállítása Monitoring.MonitoredOperation.ReadChangeFeed, az azt jelzi, hogy az állapotbeli probléma a változáscsatorna olvasásával kapcsolatos.

2.2.7

Továbbfejlesztett terheléselosztási stratégia az olyan helyzetekhez, amikor az összes bérlet lekérése hosszabb időt vesz igénybe, mint a bérlet lejárati időköze, például hálózati problémák miatt:
- Ebben a forgatókönyvben a terheléselosztási algoritmus tévesen tekintette lejártnak a bérleteket, és ezzel az aktív tulajdonosok elől vett el bérleteket. Ez időnként sok bérlet felesleges újraosztását eredményezte.
- A problémát ebben a kiadásban úgy orvosoltuk, hogy ütközés esetén a rendszer ne próbálkozzon újra az olyan lejárt bérletek lekérésével, amelynek a tulajdonosa nem változott, és halassza el a lejárt bérletek lekérését a terheléselosztás következő iterációjáig.

2.2.6

Javult a figyelői kivételek kezelése.
Részletesebb információ a megfigyelői hibákról:
- Ha a rendszer bezár egy figyelőt egy kivétel miatt, amelyet a figyelő ProcessChangesAsync feladata váltott ki, akkor a CloseAsync esetében az okparaméter értéke a következő lesz: ChangeFeedObserverCloseReason.ObserverError.
- Nyomkövetések lettek hozzáadva, amelyekkel azonosíthatók a felhasználói kódokon belüli hibák a figyelőkben.

2.2.5

Mostantól támogatott a felosztások kezelése az olyan gyűjteményekben, amelyek megosztott átviteli sebességet használnak az adatbázisokhoz.
- Ebben a kiadásban javítottunk egy problémát, amely akkor fordulhatott elő, ha az adatbázisokhoz megosztott átviteli sebességet használó gyűjteményekben elvégeztünk egy felosztást, amely a partíció terhelésének újraelosztását eredményezte, de csak egy alárendelt partíciókulcs-tartomány jött létre, nem kettő. Ebben az esetben a változáscsatorna-feldolgozó gyakran elakadt a régi partíciókulcs-tartomány bérletének törlésénél, és nem hozott létre új bérleteket. A probléma javítva lett ebben a kiadásban.

2.2.4

Hozzáadtuk a ChangeFeedProcessorOptions.StartContinuation tulajdonságot, amely lehetővé teszi a változáscsatorna elindítását a folytatási jogkivonat kérésével. Ez csak akkor használatos, ha egy bérletgyűjtemény üres, vagy nincs beállítva a ContinuationToken tulajdonsága. Az olyan bérletgyűjteményeknél, amelyeknek be van állítva a ContinuationToken tulajdonsága, a rendszer a ContinuationToken tulajdonságot használja, és a ChangeFeedProcessorOptions.StartContinuation tulajdonságot figyelmen kívül hagyja.

2.2.3

Mostantól támogatott az egyéni tárolók használata a folytonossági jogkivonatok partíciónként történő megőrzéséhez.
- Például egy egyéni bérlettároló lehet egy Azure Cosmos DB-bérletgyűjtemény, amely bármilyen egyéni módon particionálható.
- Az egyéni bérlettárolók használhatják az új ChangeFeedProcessorBuilder.WithLeaseStoreManager(ILeaseStoreManager) bővítési pontot és az ILeaseStoreManager nyilvános felületet.
- Az ILeaseManager interfész újra lett bontva több szerepkör-interfészre.
Kisebb kompatibilitástörő változás: a ChangeFeedProcessorBuilder.WithLeaseManager(ILeaseManager) bővítési pont el lett távolítva, ehelyett használja a ChangeFeedProcessorBuilder.WithLeaseStoreManager(ILeaseStoreManager) bővítési pontot.

2.2.2

Ebben a kiadásban kijavítottunk egy problémát, amely egy megfigyelt gyűjteményben található felosztás feldolgozásakor és a particionált bérletgyűjtemények használatakor fordult elő. A felosztott partíció bérletének feldolgozásakor előfordulhat, hogy a partíciónak megfelelő bérlet nem törölhető. A probléma javítva lett ebben a kiadásban.

2.2.1

Kijavítottuk a becslő számításának működését a több írási régióval rendelkező fiókok esetében, és a munkamenet-jogkivonat formátuma megújult.

2.2.0

Mostantól támogatottak a particionált bérletgyűjtemények. A partíciókulcsot a következőképpen kell megadni: /id.
Kisebb kompatibilitástörő változás: az IChangeFeedDocumentClient felület és a ChangeFeedDocumentClient osztály metódusai módosultak, és mostantól tartalmazzák a RequestOptions és a CancellationToken paramétert. Az IChangeFeedDocumentClient egy speciális bővíthetőségi pont, amely lehetővé teszi a dokumentumügyfél egyéni implementálását a változáscsatorna-feldolgozóval való használatra, például díszítheti a DocumentClientet, és elfoghatja a hívásokat, hogy további nyomkövetést, hibakezelést stb. végezhessenek. Ezzel a frissítéssel az IChangeFeedDocumentClient implementálási kódját módosítani kell, hogy új paramétereket is belefoglaljon a megvalósításba.
Kisebb diagnosztikai fejlesztések.

2.1.0

Új API érhető el: a Task<IReadOnlyList<RemainingPartitionWork>> IRemainingWorkEstimator.GetEstimatedRemainingWorkPerPartitionAsync(). Az API az egyes partíciókhoz kapcsolódó becsült munka megjelenítésére használható.
Támogatja a Microsoft.Azure.DocumentDB SDK 2.0-t. A használatához a Microsoft.Azure.DocumentDB 2.0-s vagy újabb verziója szükséges.

2.0.6

Mostantól elérhető a ChangeFeedEventHost.HostName nyilvános tulajdonság az 1-es verzióval való kompatibilitáshoz.

2.0.5

Kijavítottuk a partíciófelosztás során bekövetkező versenyhelyzetet. A versenyhelyzet a bérlet megszerzéséhez, majd azonnali elvesztéséhez vezethet a partíciófelosztás során, ami versenyt okoz. A versenyhelyzettel kapcsolatos probléma javítva lett ebben a kiadásban.

2.0.4

GA SDK

2.0.3 – előzetes kiadás

Az alábbi problémákat javítja:
- Amikor partíciófelosztás történt, a felosztás előtt módosított dokumentumok feldolgozása ismétlődően megtörténhetett.
- A GetEstimatedRemainingWork API 0 értéket adott vissza, amikor nem voltak bérletek a bérletgyűjteményben.
Nyilvánosak lettek az alábbi kivételek. Az IPartitionProcessort implementáló bővítmények okozhatják ezeket a kivételeket.
- 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 – előzetes kiadás

Kisebb API-módosítások:
- El lett távolítva az elavultként megjelölt ChangeFeedProcessorOptions.IsAutoCheckpointEnabled.

2.0.1 – előzetes kiadás

Stabilitási fejlesztések:
- A bérlettároló inicializálásának jobb kezelése. Ha a bérlettároló üres, akkor a feldolgozónak csak egy példánya inicializálhatja, a többinek várakoznia kell.
- Stabilabb/hatékonyabb bérletmegújítás/-kiadás. Olyan bérlet megújítása és kiadása, amelytől egyetlen partíció függ, a többi bérlet megújításától függetlenül történik. Az 1-es verzióban ezt a rendszer egymást követően hajtotta végre minden partícióra vonatkozóan.
Új v2 API:
- Buildelőminta a feldolgozó rugalmas összeállításához: a ChangeFeedProcessorBuilder osztály.
  - A paraméterek tetszőleges kombinációját felveheti.
  - DocumentClient-példányt is felvehet monitorozáshoz és/vagy bérletgyűjtéshez (nem elérhető el az 1-es verzióban).
- Az IChangeFeedObserver.ProcessChangesAsync már felveszi a CancellationToken paramétert.
- IRemainingWorkEstimator – a hátralévő munka becslője a feldolgozótól függetlenül használható.
- Új bővíthetőségi pontok:
  - IPartitionLoadBalancingStrategy – a partícióknak a feldolgozó példányai közötti egyéni terheléselosztásához.
  - ILease, ILeaseManager – egyéni bérletkezeléshez.
  - IPartitionProcessor – egyéni feldolgozási módosításokhoz a partíciókon.
Naplózás – a LibLog kódtárat használja.
100%-ban visszamenőlegesen kompatibilis az 1-es verziójú API-val.
Új kódbázis.
Az SQL .NET SDK 1.21.1-es és újabb verzióival kompatibilis.

1-es verziójú buildek

1.3.3

További naplózási lehetőségek érhetők el.
Kijavít egy DocumentClient-hiányosságot a függőben lévő munka becslésének többszöri meghívásakor.

1.3.2

Javítások a függőben lévő munka becslésében.

1.3.1

Stabilitással kapcsolatos fejlesztések.
- Kijavítja a megszakított feladatok kezelésével kapcsolatos problémát, amely a figyelők egyes partíciókon való leállítását eredményezhette.
Ellenőrzőpontok manuális létrehozásának támogatása.
Az SQL .NET SDK 1.21-es és újabb verzióival kompatibilis.

1.2.0

Mostantól a .NET Standard 2.0 támogatott. A csomag már támogatja a(z) netstandard2.0 és net451 keretrendszer-monikert.
Az SQL .NET SDK 1.17.0-s és újabb verzióival kompatibilis.
Az SQL .NET Core SDK 1.5.1-es és újabb verzióival kompatibilis.

1.1.1

Kijavítja a hátralévő munka becslésének kiszámításával kapcsolatos problémát, amely akkor jelentkezett, amikor a változáscsatorna üres volt, vagy nem volt függőben lévő munka.
Az SQL .NET SDK 1.13.2-es és újabb verzióival kompatibilis.

1.1.0

Új metódus érhető el a változáscsatornában feldolgozandó hátralévő munka becslésének beszerzéséhez.
Az SQL .NET SDK 1.13.2-es és újabb verzióival kompatibilis.

1.0.0

GA SDK
Az SQL .NET SDK 1.14.1-es és korábbi verzióival kompatibilis.

Kiadási és kivonási dátumok

A Microsoft legalább 12 hónappal előre biztosít értesítést az SDK-k kivonásáról az újabb vagy támogatott verzióra való zökkenőmentes váltás érdekében. Új szolgáltatásokkal, funkciókkal és optimalizálásokkal csak az aktuális SDK bővül, ezért azt javasoljuk, hogy a mindig lehető leghamarabb frissítsen a legújabb SDK-verzióra.

Figyelmeztetés

2022. augusztus 31-e után az Azure Cosmos DB már nem fog hibajavításokat végezni, új funkciókat ad hozzá, és támogatást nyújt az Azure Cosmos DB .NET vagy a .NET Core SDK for API for NoSQL 1.x verziójához. Ha nem szeretné frissíteni, az SDK 1.x-es verziójából küldött kéréseket továbbra is kiszolgálja az Azure Cosmos DB szolgáltatás.

Verzió	Kiadás dátuma	Kivonás dátuma
2.5.0	2023. május 15.	---
2.4.0	2021. május 6.	---
2.3.2	2020. augusztus 11.	---
2.3.1	2020. július 30.	---
2.3.0	2020. április 2.	---
2.2.8	2019. október 28.	---
2.2.7	2019. május 14.	---
2.2.6	2019. január 29.	---
2.2.5	2018. december 13.	---
2.2.4	2018. november 29.	---
2.2.3	2018. november 19.	---
2.2.2	2018. október 31.	---
2.2.1	2018. október 24.	---
1.3.3	2018. május 8.	---
1.3.2	2018. április 18.	---
1.3.1	2018. március 13.	---
1.2.0	2017. október 31.	---
1.1.1	2017. augusztus 29.	---
1.1.0	2017. augusztus 13.	---
1.0.0	2017. július 7.	---

GYIK

Hogyan fogok értesülni az SDK kivezetéséről?

A Microsoft értesítést küld 12 hónappal a kivezetett SDK támogatásának vége előtt, megkönnyítve a zökkenőmentes áttérést egy támogatott SDK-ra. Az értesítéseket különböző kommunikációs csatornákon továbbítjuk: az Azure Portalon, Azure-frissítés útján, valamint a hozzárendelt szolgáltatásadminisztrátorok közvetlen értesítésével.

Létrehozhatok alkalmazásokat egy hamarosan kivezetendő Azure Cosmos DB SDK-val ebben a 12 hónapos időszakban?

Igen, a 12 hónapos értesítési időszakban is lehet alkalmazásokat létrehozni, üzembe helyezni és módosítani a hamarosan kivezetendő Azure Cosmos DB SDK-val. Javasoljuk, hogy a 12 hónap folyamán lehetőleg mielőbb térjen át az Azure Cosmos DB SDK újabb, támogatott verziójára.

A kivezetési dátum után mi lesz a már nem támogatott Azure Cosmos DB SDK-t használó alkalmazásokkal?

A kivezetési dátum után az Azure Cosmos DB nem biztosít több hibajavítást, új funkciót és támogatást a kivezetett SDK-verziókhoz. Ha nem frissíti az SDK-t, az Azure Cosmos DB szolgáltatás továbbra is kiszolgálja az SDK kivezetett verziói által küldött kéréseket.

Melyik SDK-verziók kapják meg a legújabb funkciókat és frissítéseket?

Az új funkciók és frissítések csak a legújabb támogatott fő SDK-verzió legújabb alverziójában lesznek hozzáadva. Javasoljuk, hogy mindig használja a legújabb verziót, hogy hozzájusson az új funkciókhoz, teljesítménybeli fejlesztésekhez és hibajavításokhoz. Ha egy régebbi, még nem kivezetett SDK-verziót használ, akkor az Azure Cosmos DB felé küldött kérései továbbra is működni fognak, de nem lesz hozzáférése az új lehetőségekhez.

Mit tegyek, ha nem tudom frissíteni az alkalmazásomat egy megszűnési dátum előtt?

Javasoljuk, hogy mindig a lehető leghamarabb frissítsen a legújabb SDK-verzióra. Miután egy SDK kivezetendő megjelölést kap, 12 hónap áll rendelkezésre az alkalmazás frissítésére. Ha nem tudja elvégezni a frissítést a kivezetési dátumig, az Azure Cosmos DB szolgáltatás továbbra is kiszolgálja az SDK kivezetett verziói által küldött kéréseket, így a futó alkalmazások továbbra is működni fognak. Azonban az Azure Cosmos DB nem biztosít több hibajavítást, új funkciót és támogatást a kivezetett SDK-verziókhoz.

Ha rendelkezik támogatási csomaggal és műszaki támogatásra van szüksége, lépjen kapcsolatba velünk egy támogatási jegy beküldésével.

Hogyan kérhetem, hogy funkciók legyenek hozzáadva egy SDK-hoz vagy összekötőhöz?

Az új funkciók nem mindig jelennek meg azonnal minden SDK-hoz vagy összekötőhöz. Ha egy olyan funkció nem támogatott, amelyet hozzá szeretne adni, küldjön visszajelzést a közösségi fórumunkra.

Lásd még

Az Azure Cosmos DB-ről további információt a Microsoft Azure Cosmos DB szolgáltatásoldalán talál.