إرسال الأحداث وتلقيها من Azure Event Hubs باستخدام NET. (Azure.Messaging.EventHubs)

  • مقالة
  • قراءة خلال 8 دقائق

يوضح هذا بداية سريعة كيفية إرسال الأحداث إلى مركز الأحداث وتلقيها منه باستخدام مكتبة Azure.Messaging.EventHubs NET.

المتطلبات الأساسية

إذا كنت مستخدماً جديداً لـ Azure Event Hubs، فراجع نظرة عامة على Event Hubs قبل إجراء هذا بداية سريعة.

تحتاج إلى المتطلبات الأساسية التالية لإكمال هذا بداية سريعة:

  • اشتراك Microsoft Azure. لاستخدام خدمات Azure، بما فيها Azure Event Hubs، تحتاج إلى اشتراك. إذا لم يكن حساب Azure متوفراً لديك، يمكن التسجيل للحصول على نسخة تجريبية مجانية، أو استخدام مزايا الاشتراك في MSDN عند إنشاء حساب.
  • Microsoft Visual Studio 2019. تستفيد مكتبة عملاء مراكز الأحداث في Azure من الميزات الجديدة المتوفرة في إصدار #C 8.0. لا يزال بإمكانك استخدام المكتبة مع إصدارات لغة #C السابقة، لكن بناء الجملة الجديد لن يكون متاحاً. للاستفادة من بناء الجملة الكامل، من المستحسن التحويل البرمجي إلى الإصدار 3.0 أو الأعلى من NET. Core SDK وتعيين إصدار اللغة إلى latest. إذا كنت تستخدم Visual Studio، فإن الإصدارات قبل Visual Studio 2019 غير متوافقة مع الأدوات اللازمة لإنشاء مشاريع في الإصدار 8.0 من #C. ويمكن تنزيل Visual Studio 2019، بما في ذلك إصدار المجتمع المجاني، من هنا.
  • أنشئ مساحة اسم Event Hubs ومركز أحداث. تتمثل الخطوة الأولى في استخدام ⁧⁩مدخل Microsoft Azure⁧⁩ لإنشاء مساحة اسم من نوع Event Hubs، والحصول على بيانات اعتماد الإدارة التي يحتاجها التطبيق للتواصل مع "مركز الأحداث". لإنشاء مساحة اسم ومركز أحداث، اتبع الإجراء الوارد في هذه المقالة. بعد ذلك، يلزم الحصول على ⁧⁩سلسلة الاتصال لمساحة اسم Event Hubs⁧⁩ باتباع الإرشادات الواردة في مقالة: ⁧⁩الحصول على سلسلة اتصال⁧⁩. ويمكنك استخدام سلسلة الاتصال بعد ذلك في هذا بداية سريعة.

إرسال الأحداث

يوضح هذا القسم كيفية إنشاء تطبيق وحدة تحكم NET. Core لإرسال الأحداث إلى أحد مراكز الأحداث.

قم بإنشاء تطبيق وحدة تحكم

  1. قم بتشغيل Visual Studio 2019.

  2. حدد إنشاء مشروع جديد.

  3. في مربع حوار إنشاء مشروع جديد، نفِّذ الخطوات التالية: في حال عدم رؤية مربع الحوار هذا، حدد ملف من القائمة، وحدد جديد، ثم حدد مشروع.

    1. قم بتحديد #C للغة البرمجة.

    2. قم بتحديد Console لنوع التطبيق.

    3. قم بتحديد Console Application من قائمة النتائج.

    4. ثم حدد «التالي».

      Image showing the New Project dialog box

  4. أدخل EventHubsSender لاسم المشروع وEventHubsQuickStart لاسم الحل، ثم حدد OK لإنشاء المشروع.

    Image showing the page where you enter solution and project names

إضافة حزمة NuGet لمراكز الأحداث

  1. حدد Tools>NuGet Package Manager>Package Manager Console من القائمة.

  2. استخدم الأمر التالي لتثبيت حزمة Azure.Messaging.EventHubs NuGet:

    Install-Package Azure.Messaging.EventHubs

كتابة التعليمات البرمجية لإرسال أحداث إلى مركز الأحداث

  1. أضف العبارات التالية using في الجزء العلوي من الملف Program.cs:

    using System;
using System.Text;
using System.Threading.Tasks;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Producer;

  2. أضف ثوابت إلى فئة Program لسلسلة اتصال Event Hubs واسم مركز الأحداث.

        // connection string to the Event Hubs namespace
    private const string connectionString = "<EVENT HUBS NAMESPACE - CONNECTION STRING>";

    // name of the event hub
    private const string eventHubName = "<EVENT HUB NAME>";

    // number of events to be sent to the event hub
    private const int numOfEvents = 3;

    ملاحظة

    استبدل قيم العنصر النائب بسلسلة الاتصال في مساحة الاسم وفي اسم مركز الأحداث. وتأكد من أن سلسلة الاتصال هي سلسلة اتصال على مستوى مساحة الاسم.

  3. أضف الخاصية الثابتة التالية إلى الفئة Program. راجع تعليقات التعليمات البرمجية.

        // The Event Hubs client types are safe to cache and use as a singleton for the lifetime
    // of the application, which is best practice when events are being published or read regularly.
    static EventHubProducerClient producerClient;

  4. استبدل طريقة Main بطريقة async Main التالية. راجع تعليقات التعليمات البرمجية لمعرفة التفاصيل. فيما يلي الخطوات الهامة من التعليمات البرمجية.

    1. ينشئ عنصر EventHubProducerClient باستخدام سلسلة الاتصال الأساسية لمساحة الاسم واسم محور الحدث.
    2. استدعاء الأسلوب CreateBatchAsync في عنصر EventHubProducerClient لإنشاء عنصر EventDataBatch.
    3. أضف الأحداث إلى الدفعة باستخدام طريقة EventDataBatch.TryAdd.
    4. يرسل مجموعة الرسائل إلى مركز الحدث باستخدام الأسلوب EventHubProducerClient.SendAsync.
        static async Task Main()
    {
        // Create a producer client that you can use to send events to an event hub
        producerClient = new EventHubProducerClient(connectionString, eventHubName);

        // Create a batch of events 
        using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();

        for (int i = 1; i <= numOfEvents; i++)
        {
            if (! eventBatch.TryAdd(new EventData(Encoding.UTF8.GetBytes($"Event {i}"))))
            {
                // if it is too large for the batch
                throw new Exception($"Event {i} is too large for the batch and cannot be sent.");
            }
        }

        try
        {
            // Use the producer client to send the batch of events to the event hub
            await producerClient.SendAsync(eventBatch);
            Console.WriteLine($"A batch of {numOfEvents} events has been published.");
        }
        finally
        {
            await producerClient.DisposeAsync();
        }
    }

  5. أنشئ المشروع، وتأكد من عدم وجود أخطاء.

  6. ابدأ تشغيل البرنامج وانتظر وصول رسالة التأكيد.

    A batch of 3 events has been published.

  7. في مدخل Microsoft Azure، يمكنك التحقق من تلقي مركز الأحداث للأحداث. بدّل إلى طريقة عرض Messages في قسم Metrics. أعد تنشيط الصفحة لتحديث المخطط. وقد يستغرق إظهار تلقي الرسائل بضع ثوانٍ.

    Image of the Azure portal page to verify that the event hub received the events

    ملاحظة

    للحصول على التعليمات البرمجية للمصدر الكامل والمزيد من التعليقات المعلوماتية، راجع هذا الملف على GitHub

تلقي الأحداث

يوضح هذا القسم كيفية كتابة تطبيق وحدة تحكم NET. Core الذي يتلقى الأحداث من أحد مراكز الأحداث باستخدام معالج أحداث. ويعمل معالج الأحداث على تبسيط عملية تلقي الأحداث من مراكز الأحداث عن طريق إدارة نقاط التحقق الثابتة والرسائل المتوازية التي يتم تلقيها من مراكز الأحداث تلك. ويتم إقران معالج أحداث بمركز أحداث معين ومجموعة مستهلكين. ويتلقى الأحداث من أقسام متعددة في مركز الأحداث ويتم تمريرها إلى معالج مفوض بالمعالجة باستخدام التعليمات البرمجية التي توفرها.

تحذير

وإذا استخدمت التعليمات البرمجية على Azure Stack Hub، فسوف تواجه أخطاء وقت التشغيل إلا إذا كنت تستهدف إصدار Storage API معيناً. نظراً لأن Event Hubs SDK تستخدم أحدث إصدار من واجهة برمجة تطبيقات Azure Storage متوفر في Azure، وقد لا يتوفر على نظام Azure Stack Hub الأساسي. وقد يدعم Azure Stack Hub إصداراً مختلفاً من Storage Blob SDK عن الإصدار المتوفر عادةً على Azure. إذا كنت تستخدم Azure Blob Storage كمخزن نقطة تحقق، فسيلزم التحقق من إصدار Azure Storage API المدعوم لإنشاء Azure Stack Hub واستهداف هذا الإصدار في التعليمات البرمجية.

على سبيل المثال، إذا كنت تقوم بتشغيل إصدار Azure Stack Hub لعام 2005، فسيلزم العمل بالإصدار المتوفر الأعلى لخدمة Storage وهو الإصدار الصادر في 2019-02-02. بشكل افتراضي، تستخدم مكتبة عملاء Event Hubs SDK الإصدار المتوفر الأعلى على Azure (2019-07-07 وقت إصدار SDK). في هذه الحالة، وبالإضافة إلى الخطوات التالية في هذا القسم، ستحتاج أيضاً إلى إضافة تعليمات برمجية لاستهداف إصدار Storage service API الصادر في 2019-02-02. للحصول على مثال حول كيفية استهداف إصدار Storage API معين، راجع هذه العينة على GitHub.

إنشاء Azure Storage وحاوية الكائنات الثنائية كبيرة الحجم

يمكنك في هذا بداية سريعة استخدام Azure Storage كمخزن نقطة تحقق. اتبع هذه الخطوات لإنشاء حساب Azure Storage.

  1. إنشاء حساب تخزين Azure

  2. إنشاء حاوية BLOB

  3. الحصول على سلسة الاتصال بحساب التخزين

    رجاءً تدوين سلسلة الاتصال واسم الحاوية. حيث إنه سيتم استخدامها في التعليمات البرمجية الخاصة بالتلقي.

إنشاء مشروع للمستلم

  1. في نافذة مستكشف الحلول، انقر بزر الماوس الأيمن فوق حل EventHubQuickStart، ثم أشر إلى Add، وحدد New Project.
  2. حدد Console application ثم حدد Next.
  3. أدخل EventHubsReceiver لخانة Project name وحدد Create.
  4. في نافذة مستكشف الحلول، انقر بزر الماوس الأيمن فوق EventHubsReceiver، وحدد Set as a Startup Project.

إضافة حزمة Event Hubs NuGet

  1. حدد Tools>NuGet Package Manager>Package Manager Console من القائمة.

  2. في نافذة Package Manager Console، تأكد من تحديد EventHubsReceiverللمشروع الافتراضي. وفي حال عدم التحديد، استخدم القائمة المنسدلة لتحديد EventHubsReceiver.

  3. استخدم الأمر التالي لتثبيت حزمة Azure.Messaging.EventHubs NuGet:

    Install-Package Azure.Messaging.EventHubs

  4. استخدم الأمر التالي لتثبيت حزمة NuGet Azure.Messaging.EventHubs.Processor:

    Install-Package Azure.Messaging.EventHubs.Processor

تحديث الأسلوب الرئيسي

  1. أضف عبارات using التالية في الجزء العلوي من ملف Program.cs.

    using System;
using System.Text;
using System.Threading.Tasks;
using Azure.Storage.Blobs;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Consumer;
using Azure.Messaging.EventHubs.Processor;

  2. أضف ثوابت إلى فئة Program لسلسلة اتصال مراكز الأحداث واسم مركز الأحداث. استبدل العناصر النائبة الموجودة بين قوسين بالقيم المناسبة التي حصلت عليها عند إنشاء مركز الأحداث. استبدل العناصر النائبة الموجودة بين قوسين بالقيم المناسبة التي حصلت عليها عند إنشاء مركز الأحداث وحساب التخزين (مفاتيح الوصول - سلسلة الاتصال الرئيسية). وتأكد من أن {Event Hubs namespace connection string} هي سلسلة اتصال على مستوى مساحة الاسم وليست سلسلة مركز أحداث.

        private const string ehubNamespaceConnectionString = "<EVENT HUBS NAMESPACE - CONNECTION STRING>";
    private const string eventHubName = "<EVENT HUB NAME>";
    private const string blobStorageConnectionString = "<AZURE STORAGE CONNECTION STRING>";
    private const string blobContainerName = "<BLOB CONTAINER NAME>";

  3. أضف الخصائص الثابتة التالية إلى الفئة Program.

        static BlobContainerClient storageClient;

    // The Event Hubs client types are safe to cache and use as a singleton for the lifetime
    // of the application, which is best practice when events are being published or read regularly.        
    static EventProcessorClient processor;

  4. استبدل طريقة Main بطريقة async Main التالية. راجع تعليقات التعليمات البرمجية لمعرفة التفاصيل. فيما يلي الخطوات الهامة من التعليمات البرمجية.

    1. إنشاء عنصر EventProcessorClient باستخدام سلسلة الاتصال الأساسية لمساحة الاسم ومركز الحدث. تحتاج إلى إنشاء عنصر BlobContainerClient للحاوية في تخزين Azure الذي أنشأته سابقاً.
    2. تحدد معالجات لأحداث ProcessEventAsync وProcessErrorAsync لعنصر EventProcessorClient.
    3. يبدأ معالجة الأحداث عن طريق استدعاء StartProcessingAsync في عنصر EventProcessorClient.
    4. عندما يضغط المستخدم على مفتاح لإنهاء المعالجة، فإنه يستدعي StopProcessingAsync في عنصر EventProcessorClient.
        static async Task Main()
    {
        // Read from the default consumer group: $Default
        string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

        // Create a blob container client that the event processor will use 
        storageClient = new BlobContainerClient(blobStorageConnectionString, blobContainerName);

        // Create an event processor client to process events in the event hub
        processor = new EventProcessorClient(storageClient, consumerGroup, ehubNamespaceConnectionString, eventHubName);

        // Register handlers for processing events and handling errors
        processor.ProcessEventAsync += ProcessEventHandler;
        processor.ProcessErrorAsync += ProcessErrorHandler;

        // Start the processing
        await processor.StartProcessingAsync();

        // Wait for 30 seconds for the events to be processed
        await Task.Delay(TimeSpan.FromSeconds(30));

        // Stop the processing
        await processor.StopProcessingAsync();
    }

  5. ويلزم الآن، إضافة أساليب معالج الأخطاء والأحداث التالية إلى الفئة.

        static async Task ProcessEventHandler(ProcessEventArgs eventArgs)
    {
        // Write the body of the event to the console window
        Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray()));

        // Update checkpoint in the blob storage so that the app receives only new events the next time it's run
        await eventArgs.UpdateCheckpointAsync(eventArgs.CancellationToken);
    }

    static Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
    {
        // Write details about the error to the console window
        Console.WriteLine($"\tPartition '{ eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
        Console.WriteLine(eventArgs.Exception.Message);
        return Task.CompletedTask;
    }

  6. أنشئ المشروع، وتأكد من عدم وجود أخطاء.

    ملاحظة

    للحصول على التعليمات البرمجية للمصدر الكامل والمزيد من التعليقات المعلوماتية، راجع هذا الملف على GitHub.

  7. استخدم تطبيق المتلقي.

  8. وسيمكنك رؤية رسالة تلقي الأحداث.

    Received event: Event 1
Received event: Event 2
Received event: Event 3

    وتلك الأحداث هي الأحداث الثلاثة التي أرسلتها إلى مركز الأحداث في وقت سابق عن طريق استخدام برنامج المرسل.

  9. في مدخل Microsoft Azure، يمكنك التحقق من وجود 3 رسائل صادرة. هذه هي الرسائل التي يتم إرسالها من Event Hubs إلى التطبيق المستلم. أعد تنشيط الصفحة لتحديث المخطط. وقد يستغرق إظهار تلقي الرسائل بضع ثوانٍ.

    Image of the Azure portal page to verify that the event hub sent events to the receiving app

الخطوات التالية

توفر هذه البداية السريعة إرشادات خطوة بخطوة لتنفيذ سيناريو بسيط لإرسال مجموعة من الأحداث إلى مركز أحداث ثم استلامها. لمزيد من العينات على السيناريوهات الأخرى والمتقدمة، اسحب العينات التالية على GitHub.