.NET için Azure Event Hubs istemci kitaplığı - sürüm 5.8.1
Azure Event Hubs saniyede milyonlarca olay alıp bunları birden çok tüketiciye aktarabilen yüksek oranda ölçeklenebilir bir yayımlama-abone olma hizmetidir. Bu sayede bağlı cihazlarınız ve uygulamalarınız tarafından üretilen çok büyük miktarlardaki verileri işleyip analiz edebilirsiniz. Event Hubs verileri topladıktan sonra, herhangi bir gerçek zamanlı analiz sağlayıcısını kullanarak veya toplu işlem/depolama bağdaştırıcılarıyla verileri alabilir, dönüştürebilir ve depolayabilirsiniz. Azure Event Hubs hakkında daha fazla bilgi edinmek isterseniz şunları gözden geçirmek isteyebilirsiniz: Event Hubs nedir?
Azure Event Hubs istemci kitaplığı, Azure Event Hubs olaylarını yayımlamaya ve kullanmaya olanak tanır ve şunları yapmak için kullanılabilir:
İş zekası ve tanılama amaçları için uygulamanız hakkında telemetri yayma.
İlgili tarafların, eylemde bulunmak için bir tetikleyici olarak gözlemleyip kullanabileceği uygulamanızın durumu hakkında olgular yayımlama.
İşletmenizin veya diğer ekosistemin içinde gerçekleşen ilginç işlemleri ve etkileşimleri gözlemleyin, böylece gevşek bir şekilde bağlanmış sistemleri birbirine bağlamanıza gerek kalmadan sistemler etkileşime geçebilir.
Bir veya daha fazla yayımcıdan etkinlikler alın, ekosisteminizin ihtiyaçlarını daha iyi karşılayacak şekilde dönüştürün ve ardından dönüştürülen etkinlikleri, tüketiciler için yeni bir akışta yayımlayın.
Kaynak kodu | Paket (NuGet) | API başvuru belgeleri | Ürün belgeleri | Geçiş kılavuzu | Sorun giderme kılavuzu
Başlarken
Önkoşullar
Azure Aboneliği: Azure Event Hubs dahil olmak üzere Azure hizmetlerini kullanmak için bir aboneliğe ihtiyacınız vardır. Mevcut bir Azure hesabınız yoksa ücretsiz deneme sürümüne kaydolabilir veya hesap oluştururkenVisual Studio Aboneliği avantajlarınızı kullanabilirsiniz.
Olay Hub'ı ile Event Hubs ad alanı: Azure Event Hubs etkileşime geçmek için bir ad alanı ve Olay Hub'ına da sahip olmanız gerekir. Azure kaynakları oluşturma hakkında bilginiz yoksa, Azure portal kullanarak Olay Hub'ı oluşturmak için adım adım kılavuzu izlemek isteyebilirsiniz. Burada, Olay Hub'ı oluşturmak için Azure CLI, Azure PowerShell veya Azure Resource Manager (ARM) şablonlarını kullanmaya yönelik ayrıntılı yönergeleri de bulabilirsiniz.
C# 8.0: Azure Event Hubs istemci kitaplığı, C# 8.0'da tanıtılan yeni özellikleri kullanır. C# 8.0 söz diziminin avantajlarından yararlanmak için dil sürümüyle.NET Core SDK 3.0 veya üzerini
latestkullanarak derlemeniz önerilir.C# 8.0 söz diziminin tüm avantajlarından yararlanmak isteyen Visual Studio kullanıcılarının Visual Studio 2019 veya sonraki bir sürümünü kullanması gerekir. Ücretsiz Community sürümü de dahil olmak üzere Visual Studio 2019 buradan indirilebilir. Visual Studio 2017 kullanıcıları , Microsoft.Net.Compilers NuGet paketini kullanarak ve dil sürümünü ayarlayarak C# 8 söz diziminin avantajlarından yararlanabilir, ancak düzenleme deneyimi ideal olmayabilir.
Kitaplığı önceki C# dil sürümleriyle kullanmaya devam edebilirsiniz, ancak yeni söz diziminden yararlanmak yerine zaman uyumsuz numaralandırılabilir ve zaman uyumsuz atılabilir üyeleri el ile yönetmeniz gerekir. .NET Core SDK'nız tarafından desteklenen .NET Core veya .NET framework'ün önceki sürümleri de dahil olmak üzere herhangi bir çerçeve sürümünü hedeflemeye devam edebilirsiniz. Daha fazla bilgi için bkz. Hedef çerçeveleri belirtme.
Önemli Not:Örnekleri ve örnekleri değişiklik yapmadan derlemek veya çalıştırmak için C# 11.0 kullanılması gerekir. Örnekleri diğer dil sürümleri için ayarlamaya karar verirseniz yine de çalıştırabilirsiniz. Bunu yapma örneği örnekte verilmiştir: Önceki Dil Sürümleri.
Azure'da hızlı bir şekilde temel bir Event Hubs kaynakları kümesi oluşturmak ve bunlar için bir bağlantı dizesi almak için, aşağıdakilere tıklayarak örnek şablonumuzu dağıtabilirsiniz:
Paketi yükleme
NuGet ile .NET için Azure Event Hubs istemci kitaplığını yükleyin:
dotnet add package Azure.Messaging.EventHubs
İstemcinin kimliğini doğrulama
Event Hubs istemci kitaplığının bir Olay Hub'ı ile etkileşim kurması için, bu kitaplıkla nasıl bağlantı kurulacağını ve yetkilendirileceğini anlaması gerekir. Bunu yapmanın en kolay yolu, Event Hubs ad alanı oluşturulurken otomatik olarak oluşturulan bir bağlantı dizesi kullanmaktır. Event Hubs ile bağlantı dizelerini kullanmayı bilmiyorsanız, Event Hubs bağlantı dizesini almak için adım adım kılavuzu izlemek isteyebilirsiniz.
Önemli kavramlar
Event Hub istemcisi, Event Hubs istemci kitaplığıyla etkileşim kuran geliştiriciler için birincil arabirimdir. Her biri olayları yayımlama veya kullanma gibi belirli bir Event Hubs kullanımına ayrılmış birkaç farklı Olay Hub'ı istemcisi vardır.
Olay Hub'ı üreticisi, ekli cihaz çözümü, mobil cihaz uygulaması, konsolda veya başka bir cihazda çalışan oyun başlığı, bazı istemci veya sunucu tabanlı iş çözümü ya da bir web sitesinin parçası olarak telemetri verileri, tanılama bilgileri, kullanım günlükleri veya diğer günlük verilerinin kaynağı olarak hizmet veren bir istemci türüdür.
Olay Hub'ı tüketicisi, Olay Hub'ından bilgileri okuyan ve işlenmesine izin veren bir istemci türüdür. İşleme toplama, karmaşık hesaplama ve filtreleme içerebilir. İşleme, bilgilerin ham veya dönüştürülmüş bir şekilde dağıtılmasını veya depolanmasını da içerebilir. Event Hub tüketicileri genellikle Azure Stream Analytics, Apache Spark veya Apache Storm gibi yerleşik analiz özelliklerine sahip sağlam ve yüksek ölçekli platform altyapı parçalarıdır.
Bölüm, Olay Hub'ında tutulan sıralı bir olay dizisidir. Bölümler, olay tüketicilerinin gerektirdiği paralellikle ilişkili bir veri düzenleme aracıdır. Azure Event Hubs, her tüketicinin ileti akışının yalnızca belirli bir alt kümesini veya bölümünü okuduğu bölümlenmiş bir tüketici deseni üzerinden ileti akışı sağlar. Yeni olaylar geldikçe dizinin sonuna eklenir. Bölüm sayısı bir Olay Hub'ı oluşturulduğunda belirtilir ve değiştirilemez.
Tüketici grubu, Olay Hub'ının tamamının görünümüdür. Tüketici grupları, her biri olay akışının ayrı bir görünümüne sahip olmak ve akışı kendi hızlarında ve kendi konumlarından bağımsız olarak okumak için birden çok kullanan uygulama sağlar. Tüketici grubu başına bir bölümde en fazla 5 eşzamanlı okuyucu olabilir; ancak belirli bir bölüm ve tüketici grubu eşleştirmesi için yalnızca bir etkin tüketici olması önerilir. Her etkin okuyucu, bölümünden tüm olayları alır; Aynı bölümde birden çok okuyucu varsa, yinelenen olayları alırlar.
Daha fazla kavram ve daha ayrıntılı tartışma için bkz. Event Hubs Özellikleri.
İstemci ömrü
Event Hubs istemci türlerinin her biri önbelleğe alınır ve uygulamanın ömrü boyunca tekil olarak kullanılır. Bu, olaylar düzenli olarak yayımlandığında veya okunduğunda en iyi uygulamadır. İstemciler, etkin olmayan dönemlerde kullanımı düşük tutmak için çalışan ağ, CPU ve bellek kullanımının verimli yönetiminden sorumludur. CloseAsync Ağ kaynaklarının ve diğer yönetilmeyen nesnelerin düzgün bir şekilde temizlendiğinden emin olmak için istemcide veya DisposeAsync çağrısı yapmak gerekir.
İş parçacığı güvenliği
Tüm istemci örneği yöntemlerinin iş parçacığı açısından güvenli ve birbirinden bağımsız olduğunu garanti ediyoruz (kılavuz). Bu, istemci örneklerini yeniden kullanma önerisinin iş parçacıkları arasında bile her zaman güvenli olmasını sağlar.
ve EventDataBatch gibi EventData veri modeli türleri iş parçacığı açısından güvenli değildir. bunlar iş parçacıkları arasında paylaşılmamalı veya istemci yöntemleriyle eşzamanlı olarak kullanılmamalıdır.
Ek kavramlar
İstemci seçenekleri | Hataları | işleme Tanılama | Alaycı
Örnekler
Olay Hub'larını inceleme
Birçok Olay Hub'ı işlemi belirli bir bölüm kapsamında gerçekleşir. Bölümler Olay Hub'ına ait olduğundan, bölümlerin adları oluşturma sırasında atanır. Hangi bölümlerin kullanılabilir olduğunu anlamak için Olay Hub'ı istemcilerinden birini kullanarak Olay Hub'ını sorgularsınız. Çizim için, EventHubProducerClient bu örneklerde gösterilmiştir, ancak kavram ve form istemciler arasında ortaktır.
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();
}
Olayları Olay Hub'ına yayımlama
Olayları yayımlamak için bir EventHubProducerClientoluşturmanız gerekir. Üreticiler olayları toplu olarak yayımlar ve belirli bir bölüm isteyebilir veya Event Hubs hizmetinin hangi bölüm olaylarında yayımlanması gerektiğine karar vermesine izin verebilir. Olayların yayımlanmasının yüksek oranda kullanılabilir olması gerektiğinde veya olay verilerinin bölümler arasında eşit dağıtılması gerektiğinde otomatik yönlendirmeyi kullanmanız önerilir. Örneğimiz otomatik yönlendirmeden yararlanacaktır.
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);
}
Olay Hub'ından olayları okuma
Olay Hub'ından olayları okumak için belirli bir tüketici grubu için bir EventHubConsumerClient oluşturmanız gerekir. Bir Olay Hub'ı oluşturulduğunda, Event Hubs'ı keşfetmeye başlamak için kullanılabilecek varsayılan bir tüketici grubu sağlar. Örneğimizde, yineleyici kullanarak Olay Hub'ında yayımlanmış olan tüm olayları okumaya odaklanacağız.
Not: Bu kullanım yaklaşımının Event Hubs istemci kitaplığını keşfetme ve prototip oluşturma deneyimini iyileştirmeye yönelik olduğunu unutmayın. Üretim senaryolarında kullanılmaması önerilir. Üretim kullanımı için, daha sağlam ve performanslı bir deneyim sağladığından Olay İşlemcisi İstemcisi'ni kullanmanızı öneririz.
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.
}
}
Olay Hub'ı bölümünden olayları okuma
Olay Hub'ı bölümünün olaylarını okumak için belirli bir tüketici grubu için bir EventHubConsumerClient oluşturmanız gerekir. Bir Olay Hub'ı oluşturulduğunda, Event Hubs'ı keşfetmeye başlamak için kullanılabilecek varsayılan bir tüketici grubu sağlar. Belirli bir bölümden okumak için tüketicinin olayları almaya başlamak için olay akışında nerede olduğunu belirtmesi de gerekir; örneğimizde, Olay Hub'ının ilk bölümü için yayımlanan tüm olayları okumaya odaklanacağız.
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.
}
}
Olay İşlemcisi istemcisi kullanarak olayları işleme
Üretim senaryolarının çoğu için, olayları okumak ve işlemek için Olay İşlemcisi İstemcisi'nin kullanılması önerilir. İşlemci, bir Olay Hub'ının tüm bölümlerindeki olayları yüksek performanslı ve hataya dayanıklı bir şekilde işlemek için güçlü bir deneyim sağlarken, durumunu kalıcı hale getirmek için bir araç sağlamayı amaçlar. Olay İşlemcisi istemcileri ayrıca belirli bir Olay Hub'ı için bir tüketici grubu bağlamında işbirliği içinde çalışabilir ve burada örnekler grup için kullanılabilir veya kullanılamaz hale geldikçe çalışmanın dağıtımını ve dengelemesini otomatik olarak yönetirler.
EventProcessorClient durumunun kalıcılığı için Azure Depolama bloblarına bağımlılığı olduğundan, kullanılacak depolama hesabı ve kapsayıcı için yapılandırılmış olan işlemci için bir BlobContainerClient sağlamanız gerekir.
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;
}
Daha fazla ayrıntı Olay İşlemcisi İstemciSI BENİOKU ve birlikte verilen örneklerde bulunabilir.
Olay Hub'ı istemcileriyle Active Directory sorumlusu kullanma
Azure Kimlik kitaplığı, Event Hubs da dahil olmak üzere Azure istemci kitaplıkları için kullanılabilecek Azure Active Directory kimlik doğrulaması desteği sağlar.
Bir Active Directory sorumlusunu kullanmak için, Event Hubs istemcisi oluşturulurken kitaplıktan kullanılabilir kimlik bilgilerinden Azure.Identity biri belirtilir. Buna ek olarak, tam Event Hubs ad alanı ve istenen Olay Hub'ının adı Event Hubs bağlantı dizesi yerine sağlanır. Çizim için, EventHubProducerClient bu örneklerde gösterilmiştir, ancak kavram ve form istemciler arasında ortaktır.
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);
}
Azure Active Directory kullanırken, sorumlunuza rol gibi Azure Event Hubs Data Owner Event Hubs'a erişim izni veren bir rol atanmalıdır. Event Hubs ile Azure Active Directory yetkilendirmesini kullanma hakkında daha fazla bilgi için lütfen ilişkili belgelere bakın.
Sorun giderme
Ayrıntılı sorun giderme bilgileri için lütfen Event Hubs Sorun Giderme Kılavuzu'na bakın.
Günlüğe kaydetme ve tanılama
Event Hubs istemci kitaplığı, bilgileri yaymak için .NET EventSource kullanarak çeşitli ayrıntı düzeylerinde bilgileri günlüğe kaydetmek için tam olarak izlenmiştir. Günlük her işlem için gerçekleştirilir ve işlemin başlangıç noktasını, tamamlanmasını ve karşılaşılan özel durumları işaretleme desenini izler. İçgörü sunabilecek ek bilgiler de ilişkili işlem bağlamında günlüğe kaydedilir.
Event Hubs istemci günlükleri, "Azure-Messaging-EventHubs" adlı kaynağı kabul ederek veya "AzureEventSource" özelliğine sahip tüm kaynakları kabul ederek herkes EventListener tarafından kullanılabilir. Azure istemci kitaplıklarından günlükleri yakalamayı kolaylaştırmak için Event Azure.Core Hubs tarafından kullanılan kitaplık bir AzureEventSourceListenersunar. Daha fazla bilgi için bkz. AzureEventSourceListener kullanarak Event Hubs günlüklerini yakalama.
Event Hubs istemci kitaplığı, Application Insights veya OpenTelemetry kullanılarak dağıtılmış izleme için de izlenmiştir. Azure.Core Tanılama örneğinde daha fazla bilgi bulabilirsiniz.
Sonraki adımlar
Azure Event Hubs istemci kitaplığı, açıklanan giriş senaryolarının ötesinde, Azure Event Hubs hizmetinin tam özellik kümesinden yararlanmaya yardımcı olmak için ek senaryolar için destek sunar. Bu senaryolardan bazılarını keşfetmeye yardımcı olmak için Event Hubs istemci kitaplığı, yaygın senaryolara yönelik bir çizim görevi görecek bir örnek projesi sunar. Ayrıntılar için lütfen BENIOKU örneklerine bakın.
Katkıda bulunma
Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.
Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.
Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorular veya yorumlarla iletişime geçin opencode@microsoft.com .
Daha fazla bilgi için lütfen katkıda bulunma kılavuzumuza bakın.
Geri Bildirim
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz. https://aka.ms/ContentUserFeedback.
Gönderin ve geri bildirimi görüntüleyin