Sdílet prostřednictvím

Azure Event Hubs klientské knihovny pro .NET – verze 5.8.1

  • Článek

Azure Event Hubs je vysoce škálovatelná služba publikování a odběru, která může ingestovat miliony událostí za sekundu a streamovat je více příjemcům. To vám umožní zpracovávat a analyzovat obrovské objemy dat generovaných připojenými zařízeními a aplikacemi. Jakmile služba Event Hubs shromáždí data, můžete je načítat, transformovat a ukládat pomocí libovolného poskytovatele analýz v reálném čase nebo pomocí adaptérů dávkování a úložiště. Pokud se chcete o Azure Event Hubs dozvědět více, můžete si projít téma Co je Event Hubs.

Klientská knihovna služby Azure Event Hubs umožňuje publikovat a využívat události služby Azure Event Hubs a můžete ji použít k následujícím účelům:

  • Generování telemetrie o vaší aplikaci pro účely business intelligence a diagnostiky

  • Publikování faktů o stavu vaší aplikace, které můžou sledovat zúčastněné strany a používat je jako triggery pro aktivaci akcí

  • Sledování zajímavých operací a interakcí v rámci vašeho podnikového nebo jiného ekosystému, aby spolu mohly komunikovat volně propojené systémy bez nutnosti mezi nimi vytvářet vazby

  • Příjem událostí od jednoho nebo více vydavatelů, jejich transformace tak, aby lépe vyhovovaly potřebám vašeho ekosystému, a následné publikování transformovaných událostí do nového streamu, ve kterém je můžou sledovat příjemci

Zdrojový kód | Balíček (NuGet) | Referenční dokumentace k | rozhraní API Dokumentace k | produktu Průvodce | migrací Průvodce odstraňováním potíží

Začínáme

Požadavky

  • Předplatné Azure: Abyste mohli používat služby Azure, včetně Azure Event Hubs, budete potřebovat předplatné. Pokud nemáte existující účet Azure, můžete si při vytváření účtu zaregistrovat bezplatnou zkušební verzi nebo využít výhody předplatného sady Visual Studio.

  • Obor názvů služby Event Hubs s centrem událostí: Abyste mohli pracovat s Azure Event Hubs, musíte mít také k dispozici obor názvů a centrum událostí. Pokud nemáte zkušenosti s vytvářením prostředků Azure, možná budete chtít postupovat podle podrobného průvodce vytvořením centra událostí pomocí Azure Portal. Najdete tam také podrobné pokyny k vytvoření centra událostí pomocí šablon Azure CLI, Azure PowerShell nebo Azure Resource Manager (ARM).

  • C# 8.0: Klientská knihovna Azure Event Hubs využívá nové funkce, které byly zavedeny v jazyce C# 8.0. Pokud chcete využít syntaxi jazyka C# 8.0, doporučujeme zkompilovat pomocí sady .NET Core SDK 3.0 nebo vyšší s jazykovou verzí nástroje latest.

    Uživatelé sady Visual Studio, kteří chtějí plně využít syntaxi jazyka C# 8.0, budou muset použít Visual Studio 2019 nebo novější. Visual Studio 2019, včetně bezplatné edice Community, si můžete stáhnout tady. Uživatelé sady Visual Studio 2017 můžou využít syntaxi jazyka C# 8 tak, že využijí balíček NuGet Microsoft.Net.Compilers a nastaví jazykovou verzi, i když prostředí pro úpravy nemusí být ideální.

    Knihovnu můžete dál používat s předchozími verzemi jazyka C#, ale budete muset spravovat asynchronní výčet a asynchronní jednorázové členy ručně, místo toho, abyste mohli využívat výhod nové syntaxe. Stále můžete cílit na libovolnou verzi architektury podporovanou sadou .NET Core SDK, včetně starších verzí .NET Core nebo rozhraní .NET Framework. Další informace najdete v tématu Určení cílových architektur.
    Důležitá poznámka: Abyste mohli sestavit nebo spustit příklady a ukázky bez úprav, je nutné použít C# 11.0. Pokud se rozhodnete je upravit pro jiné jazykové verze, můžete je přesto spustit. Příklad, jak to udělat, je k dispozici v ukázce: Starší jazykové verze.

Pokud chcete rychle vytvořit základní sadu prostředků služby Event Hubs v Azure a získat pro ně připojovací řetězec, můžete naši ukázkovou šablonu nasadit kliknutím na:

Nasazení do Azure

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Event Hubs pro .NET pomocí NuGetu:

dotnet add package Azure.Messaging.EventHubs

Ověření klienta

Aby klientská knihovna Služby Event Hubs komunikovali s centrem událostí, musí vědět, jak se s ním připojit a autorizovat s ním. Nejjednodušší způsob, jak to udělat, je použít připojovací řetězec, který se vytvoří automaticky při vytváření oboru názvů služby Event Hubs. Pokud nejste obeznámeni s používáním připojovacích řetězců se službou Event Hubs, možná budete chtít získat připojovací řetězec služby Event Hubs podle podrobného průvodce.

Klíčové koncepty

  • Klient centra událostí je primárním rozhraním pro vývojáře, kteří pracují s klientskou knihovnou služby Event Hubs. Existuje několik různých klientů centra událostí, z nichž každý je vyhrazený pro konkrétní použití služby Event Hubs, jako je publikování nebo využívání událostí.

  • Producent centra událostí je typ klienta, který slouží jako zdroj telemetrických dat, diagnostických informací, protokolů využití nebo jiných dat protokolů jako součást řešení vložených zařízení, aplikace pro mobilní zařízení, herního titulu běžícího na konzoli nebo jiném zařízení, některého klientského nebo serverového obchodního řešení nebo webu.

  • Příjemce centra událostí je typ klienta, který čte informace z centra událostí a umožňuje jejich zpracování. Zpracování může zahrnovat agregaci, komplexní výpočty a filtrování. Zpracování může také zahrnovat distribuci nebo ukládání informací nezpracovaným nebo transformovaným způsobem. Příjemci centra událostí jsou často robustní a vysoce škálovatelné součásti infrastruktury platformy s integrovanými analytickými funkcemi, jako jsou Azure Stream Analytics, Apache Spark nebo Apache Storm.

  • Oddíl je seřazená posloupnost událostí, která se nachází v centru událostí. Oddíly jsou prostředky organizace dat spojené s paralelismem vyžadovaným příjemci událostí. Azure Event Hubs poskytuje streamování zpráv prostřednictvím modelu rozděleného příjemce, ve kterém každý příjemce čte pouze určitou podmnožinu nebo oddíl streamu zpráv. Události, které nově přichází, se zařazují na konec této posloupnosti. Počet oddílů je zadaný v okamžiku vytvoření centra událostí a nelze ho změnit.

  • Skupina příjemců je zobrazení celého centra událostí. Skupiny příjemců umožňují, aby každá z nich měla samostatné zobrazení streamu událostí a mohla stream číst nezávisle vlastním tempem a z vlastní pozice. Na oddílu na skupinu příjemců může být maximálně 5 souběžných čtenářů. Doporučuje se však, aby pro daný oddíl a párování skupin příjemců existoval pouze jeden aktivní příjemce. Každý aktivní čtenář obdrží všechny události ze svého oddílu; Pokud je ve stejném oddílu více čtenářů, obdrží duplicitní události.

Další koncepty a hlubší diskuzi najdete v tématu Funkce služby Event Hubs.

Životnost klienta

Každý z typů klientů služby Event Hubs se dá bezpečně ukládat do mezipaměti a používat je jako jednoúčelový po celou dobu životnosti aplikace, což je osvědčený postup při pravidelném publikování nebo čtení událostí. Klienti zodpovídají za efektivní správu využití sítě, procesoru a paměti a pracují na tom, aby během období nečinnosti udrželi nízké využití. Volání klienta CloseAsync nebo DisposeAsync na klientovi je vyžadováno, aby se zajistilo, že síťové prostředky a další nespravované objekty jsou správně vyčištěny.

Bezpečnost vlákna

Zaručujeme, že všechny metody instance klienta jsou bezpečné pro přístup z více vláken a nezávislé na sobě (pokyny). Tím se zajistí, že doporučení opakovaného použití instancí klienta bude vždy bezpečné, a to i napříč vlákny.

Typy datového modelu, například EventData a EventDataBatch , nejsou bezpečné pro přístup z více vláken. Neměly by se sdílet mezi vlákny ani používat souběžně s klientskými metodami.

Další koncepty

Možnosti | klienta Zpracování selhání | Diagnostika | Zesměšňovat

Příklady

Kontrola centra událostí

Mnoho operací centra událostí probíhá v rámci konkrétního oddílu. Vzhledem k tomu, že oddíly vlastní centrum událostí, přiřazují se jejich názvy v okamžiku vytvoření. Abyste pochopili, jaké oddíly jsou k dispozici, dotazujete centrum událostí pomocí jednoho z klientů centra událostí. Pro ilustraci EventHubProducerClient je to znázorněno v těchto příkladech, ale koncept a forma jsou společné napříč klienty.

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();
}

Publikování událostí do centra událostí

Abyste mohli publikovat události, musíte vytvořit EventHubProducerClient. Producenti publikují události v dávkách a můžou si vyžádat konkrétní oddíl nebo umožnit službě Event Hubs, aby se rozhodla o tom, na které události oddílu se mají publikovat. Automatické směrování se doporučuje použít v případě, že publikování událostí musí být vysoce dostupné nebo když mají být data událostí rovnoměrně distribuována mezi oddíly. Náš příklad bude využívat automatické směrování.

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);
}

Čtení událostí z centra událostí

Abyste mohli číst události z centra událostí, budete muset vytvořit EventHubConsumerClient pro danou skupinu příjemců. Když je centrum událostí vytvořené, poskytuje výchozí skupinu příjemců, kterou můžete použít k seznámení se službou Event Hubs. V našem příkladu se zaměříme na čtení všech událostí publikovaných v centru událostí pomocí iterátoru.

Poznámka: Je důležité si uvědomit, že tento přístup ke využívání má zlepšit prostředí při zkoumání klientské knihovny služby Event Hubs a vytváření prototypů. Doporučuje se, aby se nepoužíval v produkčních scénářích. Pro použití v produkčním prostředí doporučujeme použít klienta event processor, protože poskytuje robustnější a výkonnější prostředí.

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.
    }
}

Čtení událostí z oddílu centra událostí

Abyste mohli číst události pro oddíl centra událostí, budete muset vytvořit EventHubConsumerClient pro danou skupinu příjemců. Když je centrum událostí vytvořené, poskytuje výchozí skupinu příjemců, kterou můžete použít k seznámení se službou Event Hubs. Chcete-li číst z konkrétního oddílu, příjemce bude také muset určit, kde ve streamu událostí začít přijímat události; v našem příkladu se zaměříme na čtení všech publikovaných událostí pro první oddíl centra událostí.

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.
    }
}

Zpracování událostí pomocí klienta Event Processor

Pro většinu produkčních scénářů se pro čtení a zpracování událostí doporučuje používat klienta event processoru . Cílem procesoru je poskytovat robustní prostředí pro zpracování událostí napříč všemi oddíly centra událostí výkonným způsobem odolným proti chybám a zároveň poskytuje způsob, jak zachovat svůj stav. Klienti procesoru událostí jsou také schopni spolupracovat v kontextu skupiny příjemců pro dané centrum událostí, kde budou automaticky spravovat distribuci a vyrovnávání práce, jakmile budou instance dostupné nebo nedostupné pro skupinu.

EventProcessorClient Vzhledem k tomu, že objekt má závislost na objektech blob služby Azure Storage pro trvalost svého stavu, budete muset pro procesor zadat BlobContainerClient objekt, který je nakonfigurovaný pro účet úložiště a kontejner, který se má použít.

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;
}

Další podrobnosti najdete v souboru README klienta procesoru událostí a v doprovodných ukázkách.

Použití objektu zabezpečení služby Active Directory s klienty centra událostí

Knihovna identit Azure poskytuje podporu ověřování Azure Active Directory, kterou je možné použít pro klientské knihovny Azure, včetně služby Event Hubs.

Pokud chcete použít objekt zabezpečení služby Active Directory, je při vytváření klienta služby Event Hubs zadán jeden z dostupných přihlašovacích údajů z Azure.Identity knihovny. Kromě toho se plně kvalifikovaný obor názvů služby Event Hubs a název požadovaného centra událostí zadává namísto připojovacího řetězce služby Event Hubs. Pro ilustraci EventHubProducerClient je to znázorněno v těchto příkladech, ale koncept a forma jsou společné napříč klienty.

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);
}

Pokud používáte Azure Active Directory, musí mít objekt zabezpečení přiřazenou roli, která umožňuje přístup ke službě Event Hubs, například k Azure Event Hubs Data Owner této roli. Další informace o použití autorizace Azure Active Directory se službou Event Hubs najdete v související dokumentaci.

Řešení potíží

Podrobné informace o řešení potíží najdete v průvodci odstraňováním potíží se službou Event Hubs.

Protokolování a diagnostika

Klientská knihovna služby Event Hubs je plně instrumentovaná pro protokolování informací na různých úrovních podrobností pomocí rozhraní .NET EventSource k vygenerování informací. Protokolování se provádí pro každou operaci a řídí se vzorem označení počátečního bodu operace, její dokončení a případných zjištěných výjimek. Další informace, které můžou nabídnout přehled, se také protokolují v kontextu přidružené operace.

Protokoly klienta služby Event Hubs jsou dostupné všem EventListener uživatelům tak, že se přihlásíte ke zdroji s názvem "Azure-Messaging-EventHubs" nebo se přihlásíte ke všem zdrojům, které mají vlastnost AzureEventSource. Pro usnadnění Azure.Core zachytávání protokolů z klientských knihoven Azure nabízí knihovna používaná službou Event Hubs .AzureEventSourceListener Další informace najdete v tématu Zachycení protokolů služby Event Hubs pomocí azureEventSourceListener.

Klientská knihovna služby Event Hubs je také instrumentovaná pro distribuované trasování pomocí Application Insights nebo OpenTelemetry. Další informace najdete v ukázce diagnostiky Azure.Core.

Další kroky

Kromě probíraných úvodních scénářů nabízí klientská knihovna Azure Event Hubs podporu pro další scénáře, které vám pomůžou využít úplnou sadu funkcí služby Azure Event Hubs. Klientská knihovna Služby Event Hubs nabízí projekt ukázek, které slouží jako ilustrace pro běžné scénáře, aby vám pomohla prozkoumat některé z těchto scénářů. Podrobnosti najdete v ukázkách SOUBORU README .

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo se obraťte na opencode@microsoft.com případné další dotazy nebo komentáře.

Další informace najdete v našem průvodci přispívání .

Imprese