分享方式:


快速入門:使用 .NET 將事件傳送至 Azure 事件中樞並從中接收事件

在本快速入門中,您將了解如何將事件傳送至事件中樞,然後使用 Azure.Messaging.EventHubs .NET 程式庫從事件中樞接收這些事件。

注意

快速入門可讓您快速熟悉服務。 如果您已經熟悉服務,您可能會想要在 GitHub 上的 .NET SDK 存放庫中查看事件中樞的 .NET 範例: GitHub 上的事件中樞範例、 GitHub 上的事件處理器範例。

必要條件

如果您對 Azure 事件中樞並不熟悉,請在逐步進行此快速入門之前,先參閱事件中樞概觀

若要完成本快速入門,您必須符合下列必要條件:

  • Microsoft Azure 訂用帳戶。 若要使用 Azure 服務 (包括 Azure 事件中樞),您需要訂用帳戶。 如果您沒有現有的 Azure 帳戶,您可以申請免費試用,或是在建立帳戶時使用 MSDN 訂閱者權益。
  • Microsoft Visual Studio 2022。 Azure 事件中樞用戶端程式庫會使用 C# 8.0 中引進的新功能。 您仍然可以使用之前 C# 程式設計語言版本的程式庫,但無法使用新的語法。 若要使用完整的語法,建議您使用 .NET Core SDK 3.0 或更新版本,並將語言版本設為 latest 以進行編譯。 如果您使用的是 Visual Studio,則 Visual Studio 2022 之前的版本與建立 C# 8.0 專案所需的工具不相容。 Visual Studio 2022 (包括免費的 Community 版) 可以在這裡下載。
  • 建立事件中樞命名空間和事件中樞。 第一個步驟是使用 Azure 入口網站來建立事件中樞命名空間,以及在該命名空間中建立事件中樞。 然後,取得應用程式與事件中樞通訊所需的管理認證。 若要建立命名空間和事件中樞,請參閱快速入門:使用 Azure 入口網站建立事件中樞

向 Azure 驗證應用程式

本快速入門顯示兩種連線到 Azure 事件中樞的方式:

  • 無密碼 (Microsoft Entra 驗證)
  • Connection string

第一個選項顯示如何使用 Azure Active Directory 和角色型存取控制 (RBAC) 中的安全性主體來連線到事件中樞命名空間。 您不需要擔心在程式碼或設定檔或 Azure Key Vault 等安全儲存體中,有硬式編碼連接字串。

第二個選項顯示如何使用連接字串來連線到事件中樞命名空間。 如果您不熟悉 Azure,則連接字串選項可能會更容易遵循。 建議在真實世界應用程式和實際執行環境中使用無密碼選項。 如需詳細資訊,請參閱驗證與授權。 您也可以在概觀頁面上,深入了解無密碼驗證。

將角色指派給 Microsoft Entra 使用者

在本機開發時,請確定連線到 Azure 事件中樞的使用者帳戶具有正確的權限。 您需要 Azure 事件中樞資料擁有者角色,才能傳送和接收訊息。 若要將此角色指派給您自己,您需要使用者存取管理員角色,或另一個包含 Microsoft.Authorization/roleAssignments/write 動作的角色。 您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell,將 Azure RBAC 角色指派給使用者。 您可以在範圍概觀頁面上,深入了解角色指派的可用範圍。

下列範例會將 Azure Event Hubs Data Owner 角色指派給您的使用者帳戶,該角色提供對 Azure 事件中樞資源的完整存取權。 在實際案例中,遵循最低權限原則,只為使用者提供更安全實際執行環境所需的最低權限。

Azure 事件中樞的 Azure 內建角色

對於 Azure 事件中樞來說,透過 Azure 入口網站和 Azure 資源管理 API 來管理的命名空間和所有相關資源,皆已使用 Azure RBAC 模型來加以保護。 Azure 提供下列 Azure 內建角色,以授權存取事件中樞命名空間:

如果您想要建立自訂角色,請參閱事件中樞作業所需的權限

重要

在大部分情況下,角色指派在 Azure 中傳播只需要一兩分鐘。 在罕見的情況下,可能需要高達八分鐘的時間。 如果您第一次執行程式碼時收到驗證錯誤,請稍候片刻再試一次。

  1. 在 Azure 入口網站中,使用主要搜尋列或左側導覽找出您的事件中樞命名空間。

  2. 在概觀頁面上,從左側功能表中選取 [存取控制 (IAM)]

  3. 在 [存取控制 (IAM)] 頁面上,選取 [角色指派] 索引標籤。

  4. 從頂端功能表選取 [+ 新增],然後從產生的下拉功能表中選取 [新增角色指派]

    顯示如何指派角色的螢幕快照。

  5. 使用搜尋方塊,從結果篩選出所需的角色。 在此範例中,搜尋 Azure Event Hubs Data Owner 並選取相符的結果。 接著,選擇 [下一步]

  6. 在 [存取權指派對象為] 下,選取 [使用者、群組或服務主體],然後選擇 [+ 選取成員]

  7. 在對話方塊中,搜尋 Microsoft Entra 使用者名稱 (通常是您的 user@domain 電子郵件地址),然後在對話方塊底部選擇 [選取]

  8. 選取 [檢閱 + 指派] 以移至最終頁面,然後再次選取 [檢閱 + 指派] 以完成此程序。

啟動 Visual Studio 並登入 Azure

您可以使用下列步驟來授權存取服務匯流排命名空間:

  1. 啟動 Visual Studio。 如果您看到 [開始使用] 視窗,請選取右窗格中的 [繼續但不開啟程式碼] 連結。

  2. 選取 Visual Studio 右上方的 [登入] 按鈕。

    顯示使用 Visual Studio 登入 Azure 的按鈕螢幕快照。

  3. 使用您先前指派角色的 Microsoft Entra 帳戶來登入。

    顯示帳戶選取項目的螢幕快照。

將事件傳送至事件中樞

本節顯示如何建立 .NET Core 主控台應用程式,以將事件傳送至您建立的事件中樞。

建立主控台應用程式

  1. 如果您已經開啟 Visual Studio 2022,請選取功能表上的 [檔案],選取 [新增],然後再選取 [專案]。 否則,請啟動 Visual Studio 2022,然後在看到快顯視窗時,選取 [建立新專案]

  2. 在 [建立新專案] 對話框中,執行下列步驟:如果您沒有看到此對話框,請選取功能表上的 [檔案],選取 [新增],然後再選取 [專案]

    1. 選取 [C#] 作為程式設計語言。

    2. 選取 [主控台] 作為應用程式的類型。

    3. 從結果清單選取 [主控台應用程式]

    4. 然後選取下一步

      顯示 [新增專案] 對話框的影像

  3. 輸入 EventHubsSender 作為專案名稱、輸入 EventHubsQuickStart 作為解決方案名稱,然後選取 [下一步]

    顯示您輸入方案和專案名稱之頁面的影像

  4. 在 [其他資訊] 頁面上,選取 [建立]

將 NuGet 套件新增至專案

  1. 從功能表選取 [工具]>[NuGet 套件管理員]>[套件管理員主控台]

  2. 執行下列命令來安裝 Azure.Messaging.EventHubsAzure.Identity NuGet 套件。 按下 ENTER 鍵,執行第二個命令。

    Install-Package Azure.Messaging.EventHubs
    Install-Package Azure.Identity
    

撰寫程式碼以將事件傳送至事件中樞

  1. Program.cs 檔案中的現有程式碼取代為下列範例程序碼。 然後,將 EventHubProducerClient 參數的 <EVENT_HUB_NAMESPACE><HUB_NAME> 預留位置值,取代為事件中樞命名空間的名稱和事件中樞的名稱。 例如:"spehubns0309.servicebus.windows.net""spehub"

    以下是程式碼的重要步驟:

    1. 使用命名空間和事件中樞名稱建立 EventHubProducerClient 物件。
    2. EventHubProducerClient 物件上叫用 CreateBatchAsync 方法,以建立 EventDataBatch 物件。
    3. 使用 EventDataBatch.TryAdd 方法將事件新增至批次。
    4. 使用 EventHubProducerClient.SendAsync 方法,將訊息的批次傳送至事件中樞。
    using Azure.Identity;
    using Azure.Messaging.EventHubs;
    using Azure.Messaging.EventHubs.Producer;
    using System.Text;
    
    // number of events to be sent to the event hub
    int numOfEvents = 3;
    
    // 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.
    // TODO: Replace the <EVENT_HUB_NAMESPACE> and <HUB_NAME> placeholder values
    EventHubProducerClient producerClient = new EventHubProducerClient(
        "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
        "<HUB_NAME>",
        new DefaultAzureCredential());
    
    // 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.");
        Console.ReadLine();
    }
    finally
    {
        await producerClient.DisposeAsync();
    }
    
  1. 建置專案,並確定沒有任何錯誤。

  2. 執行程式,並等待確認訊息。

    A batch of 3 events has been published.
    

    重要

    如果您使用無密碼 (Azure Active Directory 的角色型 存取控制) 驗證,請選取 [工具],然後選取 [選項]。 在 [ 選項] 視窗中,展開 [Azure 服務驗證],然後選取 [ 帳戶選取]。 確認您在事件中樞命名空間上使用已新增至 Azure 事件中樞 數據擁有者角色的帳戶。

  3. 在 Azure 入口網站的 [事件中樞命名空間] 頁面上,您會在 [訊息] 圖表中看到三則內送郵件。 請視需要重新整理頁面以更新圖表。 可能需要幾秒鐘的時間,頁面才會顯示已收到訊息。

    Azure 入口網站 頁面的影像,以確認事件中樞已收到事件

    注意

    如需完整的原始程式碼和更多資訊註解,請參閱 GitHub 上的此檔案

從事件中樞接收事件

本節將說明如何撰寫一個使用事件處理器從事件中樞接收事件的 .NET Core 主控台應用程式。 事件處理器可簡化從事件中樞接收事件。

建立 Azure 儲存體帳戶和 Blob 容器

在本快速入門中,您會使用 Azure 儲存體作為檢查點存放區。 請遵循這些步驟來建立 Azure 儲存體帳戶。

  1. 建立 Azure 儲存體帳戶
  2. 建立 Blob 容器
  3. 使用 Microsoft Entra ID (無密碼) 驗證或命名空間的連接字串,對 Blob 容器進行驗證。

使用 Azure Blob 儲存體作為檢查點存放區時,請遵循下列建議:

  • 針對每個取用者群組使用不同的容器。 您可以使用相同的儲存體帳戶,但每個群組各使用一個容器。
  • 請勿將容器用於其他任何項目,也不會將儲存體帳戶用於其他任何項目。
  • 儲存體帳戶應位於與已部署應用程式所在的相同區域中。 如果應用程式是內部部署,請嘗試選擇最接近的區域。

在 Azure 入口網站的 [儲存體帳戶] 頁面上,於 [Blob 服務] 區段中,確定已停用下列設定。

  • 階層式命名空間
  • Blob 虛刪除
  • 版本控制

在本機開發時,請確定存取 Blob 資料的使用者帳戶具有正確的權限。 您需要儲存體 Blob 資料參與者才能讀取和寫入 Blob 資料。 若要指派此角色給您自己,您需要被指派使用者存取管理員角色,或另一個包含 Microsoft.Authorization/roleAssignments/write 動作的角色。 您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell,將 Azure RBAC 角色指派給使用者。 您可以在範圍概觀頁面上深入了解角色指派的可用範圍。

在此案例中,您會將權限指派給使用者帳戶 (以儲存體帳戶為範圍),以遵循最低權限原則。 此做法只為使用者提供所需的最低權限,並建立更安全的實際執行環境。

下列範例將儲存體 Blob 資料參與者角色指派給使用者帳戶,以針對儲存體帳戶中的 Blob 資料提供讀取和寫入存取權。

重要

在大部分情況下,角色指派在 Azure 中傳播只需要一兩分鐘,但在罕見情況下,可能需要長達八分鐘。 如果您第一次執行程式碼時收到驗證錯誤,請稍候片刻再試一次。

  1. 在 Azure 入口網站中,使用主要搜尋列或左側導覽找出您的儲存體帳戶。

  2. 在儲存體帳戶概觀頁面上,從左側功能表中選取 [存取控制 (IAM)]

  3. 在 [存取控制 (IAM)] 頁面上,選取 [角色指派] 索引標籤。

  4. 從頂端功能表選取 [+ 新增],然後從產生的下拉功能表中選取 [新增角色指派]

    顯示如何指派記憶體帳戶角色的螢幕快照。

  5. 使用搜尋方塊,從結果篩選出所需的角色。 在此範例中,搜尋「儲存體 Blob 資料參與者」,選取相符的結果,然後選擇 [下一步]

  6. 在 [存取權指派對象為] 下,選取 [使用者、群組或服務主體],然後選擇 [+ 選取成員]

  7. 在對話方塊中,搜尋 Microsoft Entra 使用者名稱 (通常是您的 user@domain 電子郵件地址),然後在對話方塊底部選擇 [選取]

  8. 選取 [檢閱 + 指派] 以移至最終頁面,然後再次選取 [檢閱 + 指派] 以完成此程序。

為接收者建立專案

  1. 在 [方案總管] 視窗中,以滑鼠右鍵按一下 [EventHubQuickStart] 解決方案,並指向 [新增],然後選取 [新增專案]
  2. 選取 [主控台應用程式],然後選取 [下一步]
  3. 輸入 EventHubsReceiver 作為專案名稱,然後選取 [建立]
  4. 在 [方案總管] 視窗中,以滑鼠右鍵按一下 [EventHubsReceiver],然後選取 [設定為啟動專案]

將 NuGet 套件新增至專案

  1. 從功能表選取 [工具]>[NuGet 套件管理員]>[套件管理員主控台]

  2. 在 [套件管理員主控台] 視窗中,確認已針對 [預設專案] 選取 [EventHubsReceiver]。 如果不是,請使用下拉式清單選取 [EventHubsReceiver]

  3. 執行下列命令以安裝 Azure.Messaging.EventHubsAzure.Identity NuGet 套件。 按下 ENTER 鍵,執行最後一個命令。

    Install-Package Azure.Messaging.EventHubs
    Install-Package Azure.Messaging.EventHubs.Processor
    Install-Package Azure.Identity
    

更新程式碼

使用下列程式碼取代 Program.cs 的內容:

  1. Program.cs 檔案中的現有程式碼取代為下列範例程序碼。 然後,取代 BlobContainerClient URI 的 <STORAGE_ACCOUNT_NAME><BLOB_CONTAINER_NAME> 預留位置值。 也取代 EventProcessorClient<EVENT_HUB_NAMESPACE><HUB_NAME> 預留位置值。

    以下是程式碼的重要步驟:

    1. 使用事件中樞命名空間和事件中樞名稱,建立 EventProcessorClient 物件。 您必須針對您稍早所建立 Azure 儲存體中的容器來建置 BlobContainerClient 物件。
    2. 指定 EventProcessorClient 物件的 ProcessEventAsyncProcessErrorAsync 事件的處理常式。
    3. EventProcessorClient 物件上叫用 StartProcessingAsync 以開始處理事件。
    4. EventProcessorClient 物件上叫用 StopProcessingAsync,以在 30 秒後停止處理事件。
    using Azure.Identity;
    using Azure.Messaging.EventHubs;
    using Azure.Messaging.EventHubs.Consumer;
    using Azure.Messaging.EventHubs.Processor;
    using Azure.Storage.Blobs;
    using System.Text;
    
    // Create a blob container client that the event processor will use
    // TODO: Replace <STORAGE_ACCOUNT_NAME> and <BLOB_CONTATINAER_NAME> with actual names
    BlobContainerClient storageClient = new BlobContainerClient(
        new Uri("https://<STORAGE_ACCOUNT_NAME>.blob.core.windows.net/<BLOB_CONTAINER_NAME>"),
        new DefaultAzureCredential());
    
    // Create an event processor client to process events in the event hub
    // TODO: Replace the <EVENT_HUBS_NAMESPACE> and <HUB_NAME> placeholder values
    var processor = new EventProcessorClient(
        storageClient,
        EventHubConsumerClient.DefaultConsumerGroupName,
        "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
        "<HUB_NAME>",
        new DefaultAzureCredential());
    
    // 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();
    
    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()));
        Console.ReadLine();
        return Task.CompletedTask;
    }
    
    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);
        Console.ReadLine();
        return Task.CompletedTask;
    }
    
  1. 建置專案,並確定沒有任何錯誤。

    注意

    如需完整的原始程式碼和更多資訊註解,請參閱 GitHub 上的此檔案

  2. 執行接收者應用程式。

  3. 您應該會看到訊息,指出已收到事件。 在您看到收到的事件訊息之後,按 ENTER 鍵。

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

    這些事件是您稍早透過執行寄件者程式傳送至事件中樞的三個事件。

  4. 在 Azure 入口網站中,您可以確認有三個外寄郵件,由事件中樞傳送至接收應用程式。 請重新整理頁面來更新圖表。 可能需要幾秒鐘的時間,頁面才會顯示已收到訊息。

    Azure 入口網站 頁面的影像,以確認事件中樞已將事件傳送至接收應用程式

事件中樞 SDK 型應用程式的結構描述驗證

當您使用事件中樞 SDK 型應用程式來串流資料時,您可以使用 Azure 結構描述登錄來執行結構描述驗證。 事件中樞的 Azure 結構描述登錄提供集中式存放庫來管理結構描述,而且您可以順暢地將新的或現有的應用程式與結構描述登錄連線。

若要深入了解,請參閱使用事件中樞 SDK 來驗證結構描述

範例與參考

本快速入門提供實作情節的逐步指示,說明如何將一批事件傳送至事件中樞,然後再加以接收。 如需更多範例,請選取下列連結。

如需完整的 .NET 程式庫參考,請參閱 SDK 文件

清除資源

刪除具有事件中樞命名空間的資源群組,若想保留資源群組,則僅刪除命名空間。

請參閱下列教學課程: