.NET Aspire Azure Event Hubs 統合
この記事では、.NET AspireAzure Event Hubs 統合を使用する方法について説明します。
Aspire.Azure.Messaging.EventHubs ライブラリには、次の種類を登録するためのオプションが用意されています。
- EventHubProducerClient
- EventHubBufferedProducerClient
- EventHubConsumerClient
- EventProcessorClient
- PartitionReceiver
これらの型は、Azure Event Hubsに接続するために DI コンテナーに登録されます。
前提 条件
- Azure サブスクリプション: 無料でを作成してください。
- Azure Event Hubs 名前空間: 詳細については、「Event Hubs 名前空間 を追加する」を参照してください。 または、運用環境では推奨されない接続文字列を使用することもできます。
作業の開始
.NET Aspire Azure Event Hubs 統合を開始するには、📦Aspireをインストールします。Azure.Messaging.EventHubs クライアントを使用するプロジェクト (つまり、Azure Event Hubs クライアントを使用するアプリケーションのプロジェクト) の NuGet パッケージです。
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 |
クライアントの種類は、対応するオプション クラスと同様に、.NET用の Azure SDK から取得されます。 設定クラスは、.NET AspireAzure Event Hubs 統合ライブラリによって提供されます。
使用例
次の例では、Azure Event Hubs 名前空間と Event Hub が作成されており、イベント ハブにイベントを送信するように EventHubProducerClient を構成することを前提としています。
EventHubBufferedProducerClient、EventHubConsumerClient、EventProcessorClient、および PartitionReceiverも同様の方法で構成されます。
クライアントを使用するプロジェクトの Program.cs ファイルで、AddAzureEventHubProducerClient 拡張子を呼び出して、依存関係挿入コンテナーを介して使用する EventHubProducerClient を登録します。
builder.AddAzureEventHubProducerClient("eventHubsConnectionName");
その後、依存関係の挿入を使用して EventHubProducerClient インスタンスを取得できます。 たとえば、サービスからクライアントを取得するには、次のようにします。
public class ExampleService(EventHubProducerClient client)
{
// Use client...
}
詳細については、Azureを参照してください。Messaging.EventHubs のドキュメントEventHubProducerClientの使用例を示します。
アプリ ホストの使用状況
AzureにIDistributedApplicationBuilder イベント ハブ ホスティングのサポートを追加するには、📦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 メソッドは、その接続情報を、eventHubsConnectionName プロジェクトの ExampleService という名前の接続文字列に渡します。
.NET Aspire 8.1 の時点で、Azure 用の .NET Aspire 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 プロパティが含まれていないため、優先クライアントの設定コールバックで EventHubName プロパティを設定する必要があります。 今後のバージョンの Aspire では、接続文字列に EntityPath プロパティが含まれる予定であり、このシナリオでは EventHubName プロパティを設定する必要はありません。
ExampleServiceの Program.cs ファイルでは、サポートされている Event Hubs クライアント拡張メソッドを呼び出すことによって接続を使用できます。
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がサポートされています。
AzureMessagingEventHubsSettings と関連付けられたオプション (EventProcessorClientOptionsなど) を、Aspire:Azure:Messaging:EventHubs: キー プレフィックスを使用して構成から読み込み、その後に使用されている特定のクライアントの名前を読み込みます。 たとえば、appsettings.jsonのオプションの一部を構成する EventProcessorClient について考えてみましょう。
{
"Aspire": {
"Azure": {
"Messaging": {
"EventHubs": {
"EventProcessorClient": {
"EventHubName": "MyHub",
"ClientOptions": {
"Identifier": "PROCESSOR_ID"
}
}
}
}
}
}
}
オプションの Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder メソッドの AddAzureEventProcessorClient パラメーターを使用して、Options 型を設定することもできます。 たとえば、このクライアントのプロセッサのクライアント ID を設定するには、次のようにします。
builder.AddAzureEventProcessorClient(
"eventHubsConnectionName",
configureClientBuilder: clientBuilder => clientBuilder.ConfigureOptions(
options => options.Identifier = "PROCESSOR_ID"));
可観測性とテレメトリ
伐採
.NET Aspire Azure Event Hubs 統合では、次のログ カテゴリが使用されます。
Azure.CoreAzure.Identity
トレーシング
.NET Aspire Azure Event Hubs 統合では、OpenTelemetryを使用して次のトレース アクティビティが出力されます。
- "Azure.Messaging.EventHubs.*"
メトリック
現在、.NET AspireAzure Event Hubs 統合では、Azure用の .NET SDK の制限により、メトリックは既定でサポートされていません。 今後その変更が行われる場合は、これらの変更を反映するようにこのセクションが更新されます。
関連項目
.NET Aspire