Share via

Azure Event Hubs klientbibliotek för .NET – version 5.8.1

  • Artikel

Azure Event Hubs är en mycket skalbar publiceringsprenumereringstjänst som kan mata in miljontals händelser per sekund och strömma dem till flera konsumenter. På så sätt kan du bearbeta och analysera de enorma mängder data som produceras av dina anslutna enheter och program. När Event Hubs har samlat in data kan du hämta, transformera och lagra dem med hjälp av valfri realtidsanalysprovider eller med batchbearbetning/lagringskort. Om du vill veta mer om Azure Event Hubs kanske du vill granska: Vad är Event Hubs?

Klientbiblioteket i Azure Event Hubs används till att publicera och förbruka Azure Event Hubs-händelser och kan användas till att:

  • Skicka telemetri om ditt program för Business Intelligence och diagnostiska ändamål.

  • Publicera fakta om tillståndet för ditt program som berörda parter kan observera och använda som utlösare för att vidta åtgärder.

  • Observera intressanta åtgärder och interaktioner som sker i din verksamhet eller andra ekosystem, så att löst kopplade system kan interagera utan att de behöver länkas ihop.

  • Ta emot händelser från en eller flera utgivare, transformera dem för att bättre uppfylla behoven i ditt ekosystem och publicera sedan de transformerade händelserna till en ny ström som konsumenterna kan observera.

| Källkod Paket (NuGet) | API-referensdokumentation | Produktdokumentation | Migreringsguide | Felsökningsguide

Komma igång

Förutsättningar

  • Azure-prenumeration: Om du vill använda Azure-tjänster, inklusive Azure Event Hubs, behöver du en prenumeration. Om du inte har ett befintligt Azure-konto kan du registrera dig för en kostnadsfri utvärderingsversion eller använda dina Visual Studio-prenumerationsförmåner när du skapar ett konto.

  • Event Hubs-namnrymd med en händelsehubb: Om du vill interagera med Azure Event Hubs måste du också ha ett namnområde och en händelsehubb tillgänglig. Om du inte är bekant med att skapa Azure-resurser kanske du vill följa den stegvisa guiden för att skapa en händelsehubb med hjälp av Azure Portal. Där hittar du även detaljerade instruktioner för hur du använder Azure CLI-, Azure PowerShell- eller Azure Resource Manager-mallar (ARM) för att skapa en händelsehubb.

  • C# 8.0: Azure Event Hubs-klientbiblioteket använder nya funktioner som introducerades i C# 8.0. För att kunna dra nytta av C# 8.0-syntaxen rekommenderar vi att du kompilerar med hjälp av .NET Core SDK 3.0 eller senare med en språkversion av latest.

    Visual Studio-användare som vill dra full nytta av C# 8.0-syntaxen måste använda Visual Studio 2019 eller senare. Visual Studio 2019, inklusive den kostnadsfria Community Edition, kan laddas ned här. Användare av Visual Studio 2017 kan dra nytta av C# 8-syntaxen genom att använda NuGet-paketet Microsoft.Net.Compilers och ange språkversionen, även om redigeringsupplevelsen kanske inte är idealisk.

    Du kan fortfarande använda biblioteket med tidigare C#-språkversioner, men du måste hantera asynkrona uppräkningsbara och asynkrona engångsmedlemmar manuellt i stället för att dra nytta av den nya syntaxen. Du kan fortfarande använda alla ramverksversioner som stöds av .NET Core SDK, inklusive tidigare versioner av .NET Core eller .NET Framework. Mer information finns i: så här anger du målramverk.
    Viktigt meddelande: För att kunna skapa eller köra exemplen och exemplen utan ändringar är det nödvändigt att använda C# 11.0. Du kan fortfarande köra exemplen om du bestämmer dig för att justera dem för andra språkversioner. Ett exempel på detta finns i exemplet: Tidigare språkversioner.

Om du snabbt vill skapa en grundläggande uppsättning Event Hubs-resurser i Azure och ta emot en anslutningssträng för dem kan du distribuera vår exempelmall genom att klicka på:

Distribuera till Azure

Installera paketet

Installera Azure Event Hubs-klientbiblioteket för .NET med NuGet:

dotnet add package Azure.Messaging.EventHubs

Autentisera klienten

För att Event Hubs-klientbiblioteket ska kunna interagera med en händelsehubb måste det förstå hur man ansluter och auktoriserar med den. Det enklaste sättet att göra detta är att använda en anslutningssträng som skapas automatiskt när du skapar ett Event Hubs-namnområde. Om du inte är bekant med att använda anslutningssträngar med Event Hubs kanske du vill följa den stegvisa guiden för att hämta en Event Hubs-anslutningssträng.

Viktiga begrepp

  • En Event Hub-klient är det primära gränssnittet för utvecklare som interagerar med Event Hubs-klientbiblioteket. Det finns flera olika Event Hub-klienter, som var och en är dedikerade till en specifik användning av Event Hubs, till exempel publicering eller användning av händelser.

  • En händelsehubbproducent är en typ av klient som fungerar som källa för telemetridata, diagnostikinformation, användningsloggar eller andra loggdata, som en del av en inbäddad enhetslösning, ett mobilt enhetsprogram, en speltitel som körs på en konsol eller annan enhet, en klient- eller serverbaserad affärslösning eller en webbplats.

  • En händelsehubbkonsument är en typ av klient som läser information från händelsehubben och tillåter bearbetning av den. Bearbetningen kan omfatta aggregering, komplex beräkning och filtrering. Bearbetningen kan också omfatta distribution eller lagring av informationen på ett obearbetat eller transformerat sätt. Event Hub-konsumenter är ofta robusta och storskaliga plattformsinfrastrukturdelar med inbyggda analysfunktioner som Azure Stream Analytics, Apache Spark eller Apache Storm.

  • En partition är en ordnad sekvens av händelser som lagras i en händelsehubb. Partitioner är ett sätt att organisera data som är associerade med den parallellitet som krävs av händelsekonsumenter. Azure Event Hubs tillhandahåller meddelandeströmning via ett partitionerat konsumentmönster där varje konsument endast läser en viss delmängd, eller partition, av meddelandeströmmen. När nya händelser anländer läggs de till i slutet av denna sekvens. Antalet partitioner anges när en händelsehubb skapas och kan inte ändras.

  • En konsumentgrupp är en vy över en hel händelsehubb. Konsumentgrupper gör det möjligt för flera konsumerande program att ha en separat vy över händelseströmmen och att läsa dataströmmen oberoende av varandra i sin egen takt och från sin egen position. Det kan finnas högst 5 samtidiga läsare på en partition per konsumentgrupp. Vi rekommenderar dock att det bara finns en aktiv konsument för en viss partition och parkoppling av konsumentgrupper. Varje aktiv läsare tar emot alla händelser från partitionen. Om det finns flera läsare på samma partition får de duplicerade händelser.

Fler begrepp och djupare diskussion finns i: Event Hubs-funktioner.

Klientlivslängd

Var och en av Event Hubs-klienttyperna är säkra att cachelagrar och använda som en singleton under programmets livslängd, vilket är bästa praxis när händelser publiceras eller läss regelbundet. Klienterna ansvarar för effektiv hantering av nätverk, CPU och minnesanvändning, och arbetar för att hålla användningen låg under perioder av inaktivitet. Du måste anropa antingen CloseAsync eller DisposeAsync på en klient för att säkerställa att nätverksresurser och andra ohanterade objekt rensas korrekt.

Trådsäkerhet

Vi garanterar att alla klientinstansmetoder är trådsäkra och oberoende av varandra (riktlinje). Detta säkerställer att rekommendationen att återanvända klientinstanser alltid är säker, även över trådar.

Datamodelltyperna, till exempel EventData och EventDataBatch är inte trådsäkra. De bör inte delas mellan trådar eller användas samtidigt med klientmetoder.

Ytterligare begrepp

Klientalternativ | Hantera fel | Diagnostik | Gäckande

Exempel

Inspektera en händelsehubb

Många Event Hub-åtgärder utförs inom omfånget för en specifik partition. Eftersom partitioner ägs av händelsehubben tilldelas deras namn när de skapas. För att förstå vilka partitioner som är tillgängliga kan du fråga händelsehubben med hjälp av en av Event Hub-klienterna. Som illustration EventHubProducerClient visas i de här exemplen, men konceptet och formuläret är vanliga mellan klienter.

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

Publicera händelser till en händelsehubb

För att kunna publicera händelser måste du skapa en EventHubProducerClient. Producenter publicerar händelser i batchar och kan begära en specifik partition, eller tillåta att Event Hubs-tjänsten bestämmer vilka partitionshändelser som ska publiceras till. Vi rekommenderar att du använder automatisk routning när publiceringen av händelser måste ha hög tillgänglighet eller när händelsedata ska distribueras jämnt mellan partitionerna. Vårt exempel drar nytta av automatisk routning.

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

Läsa händelser från en händelsehubb

För att kunna läsa händelser från en händelsehubb måste du skapa en EventHubConsumerClient för en viss konsumentgrupp. När en händelsehubb skapas tillhandahåller den en standardkonsumentgrupp som kan användas för att komma igång med att utforska Event Hubs. I vårt exempel fokuserar vi på att läsa alla händelser som har publicerats till händelsehubben med hjälp av en iterator.

Observera: Det är viktigt att notera att den här metoden för användning är avsedd att förbättra upplevelsen av att utforska Event Hubs-klientbiblioteket och prototyper. Vi rekommenderar att den inte används i produktionsscenarier. För produktionsanvändning rekommenderar vi att du använder eventprocessorklienten, eftersom den ger en mer robust och högpresterande upplevelse.

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

Läsa händelser från en Event Hub-partition

För att kunna läsa händelser för en Event Hub-partition måste du skapa en EventHubConsumerClient för en viss konsumentgrupp. När en händelsehubb skapas tillhandahåller den en standardkonsumentgrupp som kan användas för att komma igång med att utforska Event Hubs. Om du vill läsa från en specifik partition måste konsumenten också ange var i händelseströmmen som ska börja ta emot händelser. I vårt exempel fokuserar vi på att läsa alla publicerade händelser för den första partitionen i händelsehubben.

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

Bearbeta händelser med en händelseprocessorklient

För de flesta produktionsscenarier rekommenderar vi att händelsebearbetningsklienten används för att läsa och bearbeta händelser. Processorn är avsedd att ge en robust upplevelse för bearbetning av händelser över alla partitioner i en händelsehubb på ett högpresterande och feltolerant sätt samtidigt som det ger ett sätt att bevara dess tillstånd. Event Processor-klienter kan också arbeta tillsammans inom ramen för en konsumentgrupp för en viss händelsehubb, där de automatiskt hanterar distribution och balansering av arbete när instanser blir tillgängliga eller otillgängliga för gruppen.

EventProcessorClient Eftersom har ett beroende av Azure Storage-blobar för beständighet för dess tillstånd, måste du ange en BlobContainerClient för processorn, som har konfigurerats för lagringskontot och containern som ska användas.

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

Mer information finns i README för händelsebearbetningsklienten och tillhörande exempel.

Använda ett Active Directory-huvudnamn med Event Hub-klienterna

Azure Identity-biblioteket tillhandahåller Azure Active Directory-autentiseringsstöd som kan användas för Azure-klientbiblioteken, inklusive Event Hubs.

Om du vill använda ett Active Directory-huvudnamn anges en av de tillgängliga autentiseringsuppgifterna Azure.Identity från biblioteket när du skapar Event Hubs-klienten. Dessutom tillhandahålls det fullständigt kvalificerade Event Hubs-namnområdet och namnet på önskad händelsehubb i stället för Event Hubs-anslutningssträngen. Som illustration EventHubProducerClient visas i de här exemplen, men konceptet och formuläret är vanliga mellan klienter.

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

När du använder Azure Active Directory måste huvudkontot tilldelas en roll som ger åtkomst till Event Hubs, till exempel Azure Event Hubs Data Owner rollen . Mer information om hur du använder Azure Active Directory-auktorisering med Event Hubs finns i den associerade dokumentationen.

Felsökning

Detaljerad felsökningsinformation finns i felsökningsguiden för Event Hubs.

Loggning och diagnostik

Event Hubs-klientbiblioteket är helt instrumenterat för loggning av information på olika detaljnivåer med hjälp av .NET EventSource för att generera information. Loggning utförs för varje åtgärd och följer mönstret för att markera startpunkten för åtgärden, dess slutförande och eventuella undantag som påträffas. Ytterligare information som kan ge insikter loggas också i kontexten för den associerade åtgärden.

Event Hubs-klientloggarna är tillgängliga för alla EventListener genom att välja källan "Azure-Messaging-EventHubs" eller välja alla källor som har egenskapen "AzureEventSource". För att göra det enklare att samla in loggar från Azure-klientbiblioteken Azure.Core erbjuder biblioteket som används av Event Hubs en AzureEventSourceListener. Mer information finns i Avbilda Event Hubs-loggar med hjälp av AzureEventSourceListener.

Event Hubs-klientbiblioteket instrumenteras också för distribuerad spårning med Application Insights eller OpenTelemetry. Mer information finns i Exemplet på Azure.Core-diagnostik.

Nästa steg

Utöver de inledande scenarier som diskuteras erbjuder Azure Event Hubs-klientbiblioteket stöd för ytterligare scenarier för att dra nytta av den fullständiga funktionsuppsättningen i Azure Event Hubs-tjänsten. För att hjälpa till att utforska några av dessa scenarier erbjuder Event Hubs-klientbiblioteket ett projekt med exempel som fungerar som en illustration för vanliga scenarier. Mer information finns i README-exempel .

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.

Mer information finns i vår bidragsguide .

Visningar