次の方法で共有

.NET Aspire Azure Event Hubs 統合

  • [アーティクル]

この記事では、.NET AspireAzure Event Hubs 統合を使用する方法について説明します。 Aspire.Azure.Messaging.EventHubs ライブラリには、次の種類を登録するためのオプションが用意されています。

これらの型は、Azure Event Hubsに接続するために DI コンテナーに登録されます。

前提 条件

  • Azure サブスクリプション: 無料でを作成してください。
  • Azure Event Hubs 名前空間: 詳細については、「Event Hubs 名前空間 を追加する」を参照してください。 または、運用環境では推奨されない接続文字列を使用することもできます。

作業の開始

.NET Aspire Azure Event Hubs 統合を始めるには、📦Aspireをインストールしてください。Azure.Messaging.EventHubs NuGet パッケージを、つまり Azure Event Hubsclientを使用するアプリケーションのプロジェクトである clientを利用するプロジェクトに含めます。

dotnet add package Aspire.Azure.Messaging.EventHubs

詳細については、「dotnet パッケージ の追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

オプション クラスでサポートされているクライアント

ライブラリでは、対応するオプションと設定クラスと共に、次のクライアントがサポートされています。

Azure Client 型 Azure オプション クラス .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 名前空間と Event Hub が作成されており、イベント ハブにイベントを送信するように EventHubProducerClient を構成することを前提としています。 EventHubBufferedProducerClient、EventHubConsumerClient、EventProcessorClient、および PartitionReceiverも同様の方法で構成されます。

client-consuming プロジェクトの Program.cs ファイルで、AddAzureEventHubProducerClient 拡張子を呼び出して、依存関係挿入コンテナーを介して使用する EventHubProducerClient を登録します。

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

その後、依存関係の挿入を使用して EventHubProducerClient インスタンスを取得できます。 たとえば、サービスから client を取得するには、次のようにします。

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

詳細については、Azureを参照してください。Messaging.EventHubs のドキュメントEventHubProducerClientの使用例を示します。

アプリ ホストの使用状況

IDistributedApplicationBuilderにAzure イベント ハブ ホスティングのサポートを追加するには、📦Aspire.Hoisting.Azure.EventHubs NuGet パッケージをアプリ ホスト プロジェクトにインストールします。

dotnet add package Aspire.Hosting.Azure.EventHubs

アプリ ホスト プロジェクトで、Event Hubs 接続と Event Hub リソースを追加し、次の方法を使用して接続を使用します。

var builder = DistributedApplication.CreateBuilder(args);

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

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

AddAzureEventHubs メソッドは、ConnectionStrings:eventHubsConnectionName 構成キーの下にある AppHost の構成 ("ユーザー シークレット" など) から接続情報を読み取ります。 WithReference メソッドは、その接続情報を、ExampleService プロジェクトの eventHubsConnectionName という名前の接続文字列に渡します。

.NET Aspire 8.1 の時点で、.NET Aspire 用の Azure EventHubs 拡張機能では、EventHubs 用のローカル エミュレーターの起動がサポートされています。 エミュレーターを使用する場合は、次のように RunAsEmulator() 拡張メソッドを適用します。

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

Azure EventHubs のエミュレーターでは、Event Hubs リソース名から派生 .NET Aspire 内で 2 つのコンテナー リソースが起動されます。

大事な

名前空間と同時に AddEventHub を使用してイベント ハブを作成していますが、.NET.NET Aspire バージョンの preview-5の時点では、接続文字列には EntityPath プロパティが含まれていないため、優先 clientの設定コールバックで EventHubName プロパティを設定する必要があります。 今後のバージョンの Aspire では、接続文字列に EntityPath プロパティが含まれる予定であり、このシナリオでは EventHubName プロパティを設定する必要はありません。

ExampleServiceの Program.cs ファイルでは、サポートされている Event Hubs client 拡張メソッドを呼び出すことで接続を使用できます。

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

構成

.NET Aspire Azure Event Hubs ライブラリには、プロジェクトの要件と規則に基づいて Azure Event Hubs 接続を構成するための複数のオプションが用意されています。 FullyQualifiedNamespace または ConnectionString が提供される必要があります。

接続文字列を使用する

ConnectionStrings 構成セクションの接続文字列を使用する場合は、builder.AddAzureEventHubProducerClient() およびその他のサポートされている Event Hubs クライアントを呼び出すときに接続文字列の名前を指定します。 この例では、接続文字列に EntityPath プロパティが含まれていないため、EventHubName プロパティを設定コールバックで設定する必要があります。

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

接続情報は、ConnectionStrings 構成セクションから取得されます。 次の 2 つの接続形式がサポートされています。

完全修飾名前空間 (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 の名前を読み込みます。 たとえば、EventProcessorClientのオプションの一部を構成する appsettings.json について考えてみましょう。

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

オプションの AddAzureEventProcessorClient メソッドの Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder パラメーターを使用して、Options 型を設定することもできます。 たとえば、この clientのプロセッサの client ID を設定するには、次のようにします。

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

可観測性とテレメトリ

統合により、ログ記録、トレース、メトリックの構成が自動的に設定されます。これは、監視の柱 とも呼ばれます。 統合の可観測性とテレメトリの詳細については、統合の概要 参照してください。 バッキング サービスによっては、一部の統合でこれらの機能の一部のみがサポートされる場合があります。 たとえば、一部の統合ではログ記録とトレースがサポートされますが、メトリックはサポートされません。 テレメトリ機能は、「構成」セクションに記載されている手法を使用して無効にすることもできます。

伐採

.NET Aspire Azure Event Hubs 統合では、次のログ カテゴリが使用されます。

  • Azure.Core
  • Azure.Identity

トレーシング

.NET Aspire Azure Event Hubs 統合では、OpenTelemetryを使用して次のトレース アクティビティが出力されます。

  • "Azure.Messaging.EventHubs.*"

メトリック

現在、.NET AspireAzure Event Hubs 統合では、.NET用の Azure SDK の制限により、メトリックは既定でサポートされていません。 今後その変更が行われる場合は、これらの変更を反映するようにこのセクションが更新されます。

関連項目