共用方式為

.NET Aspire Azure Event Hubs 整合

  • 發行項

在本文中，您將瞭解如何使用 .NET AspireAzure Event Hubs 整合。 Aspire.Azure.Messaging.EventHubs 程式庫提供註冊下列類型的選項：

這些類型會在 DI 容器中註冊，以連線到 Azure Event Hubs。

先決條件

  • Azure 訂用帳戶：建立一個免費的。
  • Azure Event Hubs 命名空間：如需詳細資訊，請參閱 新增事件中樞命名空間。 或者，您可以使用連接字串，在生產環境中不建議這麼做。

開始

若要開始使用 .NET AspireAzure Event Hubs 整合，請安裝 📦Aspire。Azure。Messaging.EventHubsclient-consuming 專案中的 NuGet 套件，也就是使用 Azure Event Hubsclient的應用程式專案。

dotnet add package Aspire.Azure.Messaging.EventHubs

如需詳細資訊，請參閱 dotnet add package 或 管理 .NET 應用程式中的套件相依性。

具有選項類別的支援用戶端

程式庫支援下列客戶端，以及其對應的選項和設定類別：

Azure Client 類型 Azure Options 類別 .NET .NET Aspire Settings 類別
EventHubProducerClient EventHubProducerClientOptions AzureMessagingEventHubsProducerSettings
EventHubBufferedProducerClient EventHubBufferedProducerClientOptions AzureMessagingEventHubsBufferedProducerSettings
EventHubConsumerClient EventHubConsumerClientOptions AzureMessagingEventHubsConsumerSettings
EventProcessorClient EventProcessorClientOptions AzureMessagingEventHubsProcessorSettings
PartitionReceiver PartitionReceiverOptions AzureMessagingEventHubsPartitionReceiverSettings

client 類型來自適用於 .NET的 Azure SDK，對應的選項類別也一樣。 設定類別是由 .NET AspireAzure Event Hubs 整合連結庫所提供。

範例使用方式

下列範例假設您已建立 Azure Event Hubs 命名空間和事件中樞，並想要設定 EventHubProducerClient 將事件傳送至事件中樞。 EventHubBufferedProducerClient、EventHubConsumerClient、EventProcessorClient和 PartitionReceiver會以類似的方式設定。

在您 client取用專案的 Program.cs 檔案中，呼叫 AddAzureEventHubProducerClient 擴充功能，以透過相依性注入容器註冊並使用 EventHubProducerClient。

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

接著，您可以使用依賴注入來擷取 EventHubProducerClient 實體。 例如，若要從服務中擷取 "client"：

public class ExampleService(EventHubProducerClient client)
{
    // Use client...
}

如需詳細資訊，請參閱 Azure。Messaging.EventHubs 檔，以取得使用 EventHubProducerClient的範例。

應用程式主機使用方式

若要將 Azure 事件中樞託管支援新增至您的 IDistributedApplicationBuilder，請在 應用程式主機 專案中安裝 NuGet 套件 📦Aspire. Hosting.Azure. EventHubs。

dotnet add package Aspire.Hosting.Azure.EventHubs

在您的應用程式主機專案中，新增事件中樞連接和事件中樞資源，然後使用下列方法來使用此連接：

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("eventHubsConnectionName")
                       .AddEventHub("MyHub");

var exampleService = builder.AddProject<Projects.ExampleService>()
                            .WithReference(eventHubs);

AddAzureEventHubs 方法會從 AppHost 的組態（例如，從「用戶密碼」）讀取 ConnectionStrings:eventHubsConnectionName 組態密鑰下的連線資訊。 WithReference 方法會將該連接資訊傳遞至 ExampleService 項目中名為 eventHubsConnectionName 的連接字串。

自 .NET Aspire 8.1 起，.NET Aspire 的 Azure EventHubs 擴充功能支持啟動 EventHubs 的本機模擬器。 您可以套用 RunAsEmulator() 擴充方法，以使用模擬器，如下所示：

var eventHubs = builder.AddAzureEventHubs("eventHubsConnectionName")
                       .RunAsEmulator()
                       .AddEventHub("MyHub");

Azure EventHubs 的模擬器會導致基於事件中樞資源名稱的兩個容器資源在 .NET Aspire 中被啟動。

重要

雖然我們在建立命名空間的同時也創建了事件中樞 AddEventHub，但從 .NET.NET Aspire 版本 preview-5起，連接字串不會包含 EntityPath 屬性，因此必須在針對偏好的 client之設定回呼中設定 EventHubName 屬性。 未來的 Aspire 版本將會在連接字串中包含 EntityPath 屬性，而且不需要在此案例中設定 EventHubName 屬性。

在 ExampleService的 Program.cs 檔案中，呼叫支援的事件中樞 client 擴充方法，即可使用 來取用連線：

builder.AddAzureEventProcessorClient(
    "eventHubsConnectionName",
    static settings =>
    {
        settings.EventHubName = "MyHub";
    });

配置

.NET Aspire Azure Event Hubs 連結庫提供多個選項，根據專案的需求和慣例來設定 Azure Event Hubs 連線。 必須提供 FullyQualifiedNamespace 或 ConnectionString 任一項。

使用連接字串

從 [ConnectionStrings 組態] 區段使用連接字串時，請在呼叫 builder.AddAzureEventHubProducerClient() 和其他支援的事件中樞用戶端時，提供連接字串的名稱。 在這裡範例中，連接字串不包含 EntityPath 屬性，因此必須在設定回呼中設定 EventHubName 屬性：

builder.AddAzureEventHubProducerClient(
    "eventHubsConnectionName",
    static settings =>
    {
        settings.EventHubName = "MyHub";
    });

然後，將會從 [ConnectionStrings 組態] 區段擷取連線資訊。 支援兩種連線格式：

完整命名空間 （FQN）

建議的方法是使用完整命名空間，其可與 AzureMessagingEventHubsSettings.Credential 屬性搭配使用，以建立連線。 如果未設定認證，則會使用 DefaultAzureCredential。

{
  "ConnectionStrings": {
    "eventHubsConnectionName": "{your_namespace}.servicebus.windows.net"
  }
}

連接字串

或者，使用連接字串：

{
  "ConnectionStrings": {
    "eventHubsConnectionName": "Endpoint=sb://mynamespace.servicebus.windows.net/;SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey;EntityPath=MyHub"
  }
}

使用組態提供者

.NET Aspire Azure Event Hubs 連結庫支援 Microsoft.Extensions.Configuration。 它會使用 Aspire:Azure:Messaging:EventHubs: 鍵前綴，從配置中載入 AzureMessagingEventHubsSettings 和相關聯的選項，例如 EventProcessorClientOptions，後面接著是使用的特定 client 的名稱。 例如，請考慮 appsettings.json，它設定了一些 EventProcessorClient的選項：

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "EventHubs": {
          "EventProcessorClient": {
            "EventHubName": "MyHub",
            "ClientOptions": {
              "Identifier": "PROCESSOR_ID"
            }
          }
        }
      }
    }
  }
}

您也可以使用 AddAzureEventProcessorClient 方法的選擇性 Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder 參數來設定選項類型。 例如，若要設定此 client的處理器 client 識別碼：

builder.AddAzureEventProcessorClient(
    "eventHubsConnectionName",
    configureClientBuilder: clientBuilder => clientBuilder.ConfigureOptions(
        options => options.Identifier = "PROCESSOR_ID"));

可檢視性和遙測

.NET .NET Aspire 整合會自動設定記錄、追蹤和指標組態，有時稱為 可觀察性的支柱。 如需整合可觀察性和遙測的詳細資訊，請參閱 .NET.NET Aspire 整合概觀。 視支援服務而定，某些整合可能只支援其中一些功能。 例如，某些整合支援記錄和追蹤，但不支援計量。 您也可以使用 組態 一節中呈現的技術來停用遙測功能。

伐木

.NET Aspire Azure Event Hubs 整合會使用下列記錄類別：

  • Azure.Core
  • Azure.Identity

追蹤

.NET Aspire Azure Event Hubs 整合會使用 OpenTelemetry發出下列追蹤活動：

  • “Azure。Messaging.EventHubs.*”

指標

.NET Aspire Azure Event Hubs 整合目前預設不支援度量，因為 Azure SDK 對於 .NET的限制。 如果未來發生該變更，本節將會更新以反映這些變更。

另請參閱