Azure Event Hubs ügyfélkódtár a .NET-hez – 5.8.1-es verzió

Cikk
04/03/2023

Azure Event Hubs egy nagymértékben skálázható közzétételi-feliratkozási szolgáltatás, amely másodpercenként több millió eseményt képes beemelni, és több fogyasztónak streamelni. Ez lehetővé teszi a csatlakoztatott eszközök és alkalmazások által létrehozott nagy mennyiségű adat feldolgozását és elemzését. Miután az Event Hubs összegyűjtötte az adatokat, bármely valós idejű elemzési szolgáltatóval vagy kötegelési/tárolási adapterekkel lekérheti, átalakíthatja és tárolhatja azokat. Ha többet szeretne megtudni a Azure Event Hubs, tekintse át a következőt: Mi az az Event Hubs?

Az Azure Event Hubs-ügyfélkódtár lehetővé teszi az Azure Event Hubs-események közzétételét és felhasználását, és a következőkre használható:

Az alkalmazással kapcsolatos telemetria kibocsátása üzleti intelligenciával kapcsolatos és diagnosztikai célokra.
Az alkalmazás állapotával kapcsolatos tények közzététele, amelyeket az érdekelt felek figyelemmel követhetnek és műveletindítóként használhatnak.
A vállalkozáson vagy más ökoszisztémán belüli érdekes műveletek és interakciók megfigyelése, hogy a lazán kapcsolódó rendszerek anélkül tudjanak kommunikálni egymással, hogy össze kéne őket kötni.
Események fogadása egy vagy több közzétevőtől, átalakításuk, hogy jobban megfeleljenek az ökoszisztéma igényeinek, majd az átalakított események közzététele egy új streamben, hogy a fogyasztók is meg tudják őket figyelni.

Első lépések

Előfeltételek

Azure-előfizetés: Az Azure-szolgáltatások, köztük a Azure Event Hubs használatához előfizetésre lesz szüksége. Ha nem rendelkezik meglévő Azure-fiókkal, regisztrálhat egy ingyenes próbaverzióra , vagy használhatja a Visual Studio-előfizetés előnyeit a fiók létrehozásakor.
Event Hubs-névtér eseményközponttal: A Azure Event Hubs használatához egy névtérnek és egy eseményközpontnak is rendelkezésre kell állnia. Ha nem ismeri az Azure-erőforrások létrehozását, érdemes lehet követnie az eseményközpontok Azure Portal használatával történő létrehozásának részletes útmutatóját. Itt részletes útmutatást talál az Azure CLI, a Azure PowerShell vagy az Azure Resource Manager (ARM) sablonok event hub létrehozásához való használatához.
C# 8.0: A Azure Event Hubs ügyfélkódtár a C# 8.0-ban bevezetett új funkciókat használja. A C# 8.0 szintaxis kihasználása érdekében javasoljuk, hogy a .NET Core SDK 3.0-s vagy újabb verzióját használja a nyelvi verziójávallatest.

A C# 8.0 szintaxist teljes mértékben kihasználni kívánó Visual Studio-felhasználóknak a Visual Studio 2019-et vagy újabb verziót kell használniuk. A Visual Studio 2019, beleértve az ingyenes Community kiadást is, itt tölthető le. A Visual Studio 2017 felhasználói a Microsoft.Net.Compilers NuGet-csomag használatával és a nyelvi verzió beállításával kihasználhatják a C# 8 szintaxis előnyeit, bár a szerkesztési élmény nem feltétlenül ideális.

A kódtárat továbbra is használhatja a korábbi C#-nyelvi verziókkal, de az új szintaxis használata helyett manuálisan kell kezelnie az aszinkron enumerálható és aszinkron eldobható tagokat. Továbbra is használhatja a .NET Core SDK által támogatott keretrendszerverziókat, beleértve a .NET Core vagy a .NET-keretrendszer korábbi verzióit is. További információ: cél-keretrendszerek megadása.
Fontos megjegyzés: A példák és a minták módosítás nélküli létrehozásához vagy futtatásához a C# 11.0 használata szükséges. A mintákat továbbra is futtathatja, ha úgy dönt, hogy más nyelvi verziókhoz módosítja őket. Erre egy példa a minta: Korábbi nyelvi verziók.

Ha gyorsan létre szeretne hozni egy alapszintű Event Hubs-erőforráskészletet az Azure-ban, és kapcsolati sztring szeretne kapni számukra, a mintasablont a következő gombra kattintva helyezheti üzembe:

A csomag telepítése

Telepítse a .NET-hez készült Azure Event Hubs ügyfélkódtárat a NuGet használatával:

dotnet add package Azure.Messaging.EventHubs

Az ügyfél hitelesítése

Ahhoz, hogy az Event Hubs ügyféloldali kódtára kommunikáljon egy eseményközponttal, meg kell értenie, hogyan csatlakozhat hozzá, és hogyan engedélyezheti azt. Ennek legegyszerűbb módja egy kapcsolati sztring használata, amely automatikusan jön létre az Event Hubs-névtér létrehozásakor. Ha nem ismeri az Event Hubs kapcsolati sztringjeinek használatát, érdemes lehet követnie a részletes útmutatót az Event Hubs kapcsolati sztring beszerzéséhez.

Fő fogalmak

Az Event Hub-ügyfél az event hubs-ügyfélkódtárat kezelő fejlesztők elsődleges felülete. Számos különböző Event Hub-ügyfél létezik, amelyek mindegyike az Event Hubs adott használatára van kiállítva, például események közzétételére vagy felhasználására.
Az Event Hub-előállítók olyan ügyféltípusok, amelyek telemetriai adatok, diagnosztikai információk, használati naplók vagy egyéb naplóadatok forrásaként szolgálnak beágyazott eszközmegoldás, mobileszköz-alkalmazás, konzolon vagy más eszközön futó játékcím, ügyfél- vagy kiszolgálóalapú üzleti megoldás vagy webhely részeként.
Az Eseményközpont-fogyasztó olyan ügyféltípus, amely adatokat olvas be az eseményközpontból, és lehetővé teszi azok feldolgozását. A feldolgozás magában foglalhatja az összesítést, az összetett számítást és a szűrést. A feldolgozás magában foglalhatja az információk nyers vagy átalakított módon történő terjesztését vagy tárolását is. Az Event Hub felhasználói gyakran robusztus és nagy léptékű platforminfrastruktúra-részek, amelyek beépített elemzési képességekkel rendelkeznek, például az Azure Stream Analytics, az Apache Spark vagy az Apache Storm.
A partíció egy eseményközpontban tárolt események rendezett sorozata. A partíciók az eseményfelhasználók által megkövetelt párhuzamossághoz kapcsolódó adatszervezési eszközök. Azure Event Hubs egy particionált fogyasztói mintán keresztül biztosítja az üzenetek streamelésének folyamatát, amelyben minden fogyasztó csak az üzenetstream egy adott részhalmazát vagy partícióját olvassa be. Ha új esemény érkezik, az a sorozat végére kerül. A partíciók száma az eseményközpont létrehozásakor van megadva, és nem módosítható.
A fogyasztói csoport egy teljes eseményközpont nézete. A fogyasztói csoportok lehetővé teszik, hogy több fogyasztó alkalmazás külön nézetet biztosítson az eseménystreamről, és a streamet a saját tempójukban és a saját helyzetüktől függetlenül olvassák. Fogyasztói csoportonként legfeljebb 5 egyidejű olvasó lehet egy partíción; azonban ajánlott egy adott partíció- és fogyasztóicsoport-párosításhoz csak egy aktív fogyasztót létrehozni. Minden aktív olvasó megkapja az összes eseményt a partíciójáról; ha több olvasó is található ugyanazon a partíción, akkor ismétlődő eseményeket kapnak.

További fogalmakért és részletesebb ismertetésért lásd: Event Hubs-szolgáltatások.

Ügyfélélettartam

Az Event Hubs-ügyféltípusok mindegyike biztonságosan gyorsítótárazható és használható egyszeriként az alkalmazás teljes élettartama során, ami az események közzétételekor vagy rendszeres olvasásakor ajánlott. Az ügyfelek felelősek a hálózat, a CPU és a memóriahasználat hatékony felügyeletéért, és azon dolgoznak, hogy a használat alacsony maradjon inaktivitási időszakokban. CloseAsync A hálózati erőforrások és más nem felügyelt objektumok megfelelő törlésének biztosításához vagy DisposeAsync az ügyfél hívására van szükség.

Menetbiztonság

Garantáljuk, hogy minden ügyfélpéldány-metódus szálbiztos és független egymástól (útmutató). Ez biztosítja, hogy az ügyfélpéldányok újrafelhasználására vonatkozó javaslat mindig biztonságos legyen, még a szálak között is.

Az adatmodellek típusai, például EventData a és EventDataBatch a nem szálbiztosak. Nem oszthatók meg a szálak között, és nem használhatók egyidejűleg az ügyfélmetókkal.

További fogalmak

Ügyfélbeállítások | Hibák | kezelése Diagnosztika | Gúnyos

Példák

Eseményközpont vizsgálata

Számos Eseményközpont-művelet egy adott partíció hatókörén belül történik. Mivel a partíciók az eseményközpont tulajdonában vannak, a nevük a létrehozáskor lesz hozzárendelve. Az elérhető partíciók megismeréséhez az eseményközpontot az egyik Event Hub-ügyféllel kérdezheti le. Az ábrát EventHubProducerClient az alábbi példák szemléltetik, de a koncepció és az űrlap gyakori az ügyfeleknél.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
    string[] partitionIds = await producer.GetPartitionIdsAsync();
}

Események közzététele eseményközpontban

Az események közzétételéhez létre kell hoznia egy EventHubProducerClient. Az előállítók kötegekben tesznek közzé eseményeket, és igényelhetnek egy adott partíciót, vagy engedélyezhetik az Event Hubs szolgáltatásnak, hogy eldöntse, melyik partícióeseményeket kell közzétenni. Ajánlott automatikus útválasztást használni, ha az események közzétételének magas rendelkezésre állásúnak kell lennie, vagy ha az eseményadatokat egyenletesen kell elosztani a partíciók között. A példánk az automatikus útválasztás előnyeit fogja kihasználni.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
    using EventDataBatch eventBatch = await producer.CreateBatchAsync();
    eventBatch.TryAdd(new EventData(new BinaryData("First")));
    eventBatch.TryAdd(new EventData(new BinaryData("Second")));

    await producer.SendAsync(eventBatch);
}

Események olvasása eseményközpontból

Ahhoz, hogy eseményeket olvashasson egy eseményközpontból, létre kell hoznia egy EventHubConsumerClient adott fogyasztói csoporthoz tartozót. Az eseményközpont létrehozásakor egy alapértelmezett fogyasztói csoportot biztosít, amely az Event Hubs felfedezésének első lépéseihez használható. A példánkban az eseményközpontban közzétett összes esemény olvasására fogunk összpontosítani egy iterátor használatával.

Megjegyzés: Fontos megjegyezni, hogy a használat ezen megközelítése az Event Hubs-ügyfélkódtár és a prototípus-készítés élményének javítására szolgál. Ajánlott éles forgatókönyvekben nem használni. Éles környezetben az Event Processor-ügyfél használatát javasoljuk, mivel robusztusabb és hatékonyabb élményt nyújt.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

await using (var consumer = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName))
{
    using var cancellationSource = new CancellationTokenSource();
    cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

    await foreach (PartitionEvent receivedEvent in consumer.ReadEventsAsync(cancellationSource.Token))
    {
        // At this point, the loop will wait for events to be available in the Event Hub.  When an event
        // is available, the loop will iterate with the event that was received.  Because we did not
        // specify a maximum wait time, the loop will wait forever unless cancellation is requested using
        // the cancellation token.
    }
}

Események olvasása egy Event Hub-partícióról

Egy Eseményközpont-partíció eseményeinek olvasásához létre kell hoznia egy EventHubConsumerClient adott fogyasztói csoportot. Az eseményközpont létrehozásakor egy alapértelmezett fogyasztói csoportot biztosít, amely az Event Hubs felfedezésének első lépéseihez használható. Egy adott partícióból való olvasáshoz a fogyasztónak azt is meg kell adnia, hogy az eseménystreamben hol kezdje el fogadni az eseményeket; A példánkban az eseményközpont első partíciójához tartozó összes közzétett esemény olvasására fogunk összpontosítani.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

await using (var consumer = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName))
{
    EventPosition startingPosition = EventPosition.Earliest;
    string partitionId = (await consumer.GetPartitionIdsAsync()).First();

    using var cancellationSource = new CancellationTokenSource();
    cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

    await foreach (PartitionEvent receivedEvent in consumer.ReadEventsFromPartitionAsync(partitionId, startingPosition, cancellationSource.Token))
    {
        // At this point, the loop will wait for events to be available in the partition.  When an event
        // is available, the loop will iterate with the event that was received.  Because we did not
        // specify a maximum wait time, the loop will wait forever unless cancellation is requested using
        // the cancellation token.
    }
}

Események feldolgozása eseményfeldolgozó ügyféllel

Az éles forgatókönyvek többségénél az eseményfeldolgozó ügyfél használata javasolt az események olvasásához és feldolgozásához. A processzor arra szolgál, hogy hatékony élményt nyújtson az eseményközpont összes partíciójának eseményeinek feldolgozásához, teljesítménnyel és hibatűrő módon, miközben módot biztosít az állapot megőrzésére. Az Event Processor-ügyfelek képesek együttműködni egy adott eseményközpont fogyasztói csoportjának kontextusában, ahol automatikusan kezelik a munka elosztását és kiegyensúlyozását, amint a példányok elérhetővé válnak vagy elérhetetlenné válnak a csoport számára.

Mivel a EventProcessorClient az állapotának megőrzése érdekében függ az Azure Storage-bloboktól, meg kell adnia egy BlobContainerClient processzort, amely konfigurálva lett a használni kívánt tárfiókhoz és tárolóhoz.

var cancellationSource = new CancellationTokenSource();
cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

var storageConnectionString = "<< CONNECTION STRING FOR THE STORAGE ACCOUNT >>";
var blobContainerName = "<< NAME OF THE BLOB CONTAINER >>";

var eventHubsConnectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var consumerGroup = "<< NAME OF THE EVENT HUB CONSUMER GROUP >>";

Task processEventHandler(ProcessEventArgs eventArgs) => Task.CompletedTask;
Task processErrorHandler(ProcessErrorEventArgs eventArgs) => Task.CompletedTask;

var storageClient = new BlobContainerClient(storageConnectionString, blobContainerName);
var processor = new EventProcessorClient(storageClient, consumerGroup, eventHubsConnectionString, eventHubName);

processor.ProcessEventAsync += processEventHandler;
processor.ProcessErrorAsync += processErrorHandler;

await processor.StartProcessingAsync();

try
{
    // The processor performs its work in the background; block until cancellation
    // to allow processing to take place.

    await Task.Delay(Timeout.Infinite, cancellationSource.Token);
}
catch (TaskCanceledException)
{
    // This is expected when the delay is canceled.
}

try
{
    await processor.StopProcessingAsync();
}
finally
{
    // To prevent leaks, the handlers should be removed when processing is complete.

    processor.ProcessEventAsync -= processEventHandler;
    processor.ProcessErrorAsync -= processErrorHandler;
}

További részleteket az Event Processor Client README és a hozzá tartozó minták között talál.

Active Directory-rendszerbiztonsági tag használata az Event Hub-ügyfelekkel

Az Azure Identity-kódtár Azure Active Directory-hitelesítést biztosít, amely az Azure-ügyfélkódtárakhoz használható, beleértve az Event Hubsot is.

Az Active Directory-rendszerbiztonsági tag használatához meg kell adnia a Azure.Identity tárban elérhető hitelesítő adatok egyikét az Event Hubs-ügyfél létrehozásakor. Emellett a teljes Event Hubs-névtér és a kívánt eseményközpont neve is meg van adva az Event Hubs kapcsolati sztring helyett. Az ábrát EventHubProducerClient az alábbi példák szemléltetik, de a koncepció és az űrlap gyakori az ügyfeleknél.

var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var credential = new DefaultAzureCredential();

await using (var producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential))
{
    using EventDataBatch eventBatch = await producer.CreateBatchAsync();
    eventBatch.TryAdd(new EventData(new BinaryData("First")));
    eventBatch.TryAdd(new EventData(new BinaryData("Second")));

    await producer.SendAsync(eventBatch);
}

Az Azure Active Directory használatakor a rendszerbiztonsági taghoz olyan szerepkört kell hozzárendelni, amely lehetővé teszi az Event Hubshoz való hozzáférést, például a Azure Event Hubs Data Owner szerepkört. Az Azure Active Directory-hitelesítés event hubokkal való használatával kapcsolatos további információkért tekintse meg a kapcsolódó dokumentációt.

Hibaelhárítás

Részletes hibaelhárítási információkért tekintse meg az Event Hubs hibaelhárítási útmutatóját.

Naplózás és diagnosztika

Az Event Hubs ügyféloldali kódtára teljes mértékben az információk naplózására szolgál különböző részletességi szinteken a .NET EventSource használatával az információk kibocsátásához. A rendszer minden művelethez naplózást végez, és követi a művelet kezdőpontjának, befejezésének és a tapasztalt kivételeknek a megjelölésére szolgáló mintát. A rendszer további információkat is naplóz a kapcsolódó művelet kontextusában.

Az Event Hubs-ügyfélnaplók bármelyike EventListener számára elérhetők az "Azure-Messaging-EventHubs" nevű forrás kiválasztásával, vagy az "AzureEventSource" tulajdonságú összes forrás kiválasztásával. Az Event Hubs által használt kódtár megkönnyíti Azure.Core a naplók Azure-ügyfélkódtárakból való rögzítését AzureEventSourceListener. További információ: Event Hubs-naplók rögzítése az AzureEventSourceListener használatával.

Az Event Hubs-ügyfélkódtár az Application Insights vagy az OpenTelemetry használatával történő elosztott nyomkövetéshez is kialakításra kerül. További információt az Azure.Core diagnosztikai mintájában talál.

Következő lépések

A tárgyalt bevezető forgatókönyveken túl az Azure Event Hubs ügyfélkódtár további forgatókönyveket is támogat, amelyek segítenek kihasználni az Azure Event Hubs szolgáltatás teljes funkciókészletét. Az Event Hubs ügyféloldali kódtára néhány ilyen forgatókönyv megismeréséhez mintaprojektet kínál, amely a gyakori forgatókönyvek szemléltetésére szolgál. Részletekért tekintse meg a README mintákat.

Közreműködés

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. További részletekért lásd: https://cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes olyan tárházban, amely a CLA-t használja.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.

További információért tekintse meg közreműködői útmutatónkat .

Megjelenések

Share via