.NET AspireAzure Event Hubs 統合

含まれているもの: ホスティング統合 —および— Client 統合

Azure Event Hubs はクラウド内のネイティブ データ ストリーミング サービスであり、任意のソースから任意の宛先に、待機時間が短い数百万のイベントを 1 秒あたりにストリーミングできます。 .NET AspireAzure Event Hubs 統合により、Azure Event Hubs アプリケーションから .NET インスタンスに接続できます。

ホスティング統合

.NET.NET AspireAzure Event Hubs ホスティング統合は、さまざまな Event Hub リソースを次の種類としてモデル化します。

• AzureEventHubsResource: ハブのコレクションと、基になる Azure Event Hubs リソースへの接続情報を表すために使用される、最上位レベルの Azure リソースを表します。
• AzureEventHubResource: 1 つのイベント ハブ リソースを表します。
• AzureEventHubsEmulatorResource: コンテナー リソースとして Azure Event Hubs エミュレーターを表します。
• AzureEventHubConsumerGroupResource: イベント ハブ リソース内のコンシューマー グループを表します。

これらの種類と API にアクセスしてアプリ ホストプロジェクト内で表現するには、📦Aspire.Hosting.Azure.EventHubs NuGet パッケージをインストールしてください。

dotnet add package Aspire.Hosting.Azure.EventHubs

<PackageReference Include="Aspire.Hosting.Azure.EventHubs"
                  Version="*" />

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

Azure Event Hubs リソースを追加する

アプリ ホスト プロジェクトに AzureEventHubsResource を追加するには、名前を指定して AddAzureEventHubs メソッドを呼び出し、AddHubを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs");
eventHubs.AddHub("messages");

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

// After adding all resources, run the app...

Azure Event Hubs リソースをアプリ ホストに追加すると、Event Hub リソース、コンシューマー グループ、明示的なプロビジョニング構成を追加する他の便利な API が公開され、Azure Event Hubs エミュレーターの使用が可能になります。 上記のコードは、Azure Event Hubs という名前の event-hubs リソースと、messages という名前のイベント ハブをアプリ ホスト プロジェクトに追加します。 WithReference メソッドは、接続情報を ExampleService プロジェクトに渡します。

プロビジョニングによって生成されたBicep

Bicep を初めて使用する場合は、Azureリソースを定義するためのドメイン固有の言語です。 .NET.NET Aspireでは、Bicep を手動で記述する必要はありません。代わりに、プロビジョニング API によって Bicep が生成されます。 アプリを発行すると、生成された Bicep がマニフェスト ファイルと共に出力されます。 Azure Event Hubs リソースを追加すると、次の Bicep が生成されます。

@description('The ___location for the resource(s) to be deployed.')
param ___location string = resourceGroup().___location

param sku string = 'Standard'

resource event_hubs 'Microsoft.EventHub/namespaces@2024-01-01' = {
  name: take('event_hubs-${uniqueString(resourceGroup().id)}', 256)
  ___location: ___location
  sku: {
    name: sku
  }
  tags: {
    'aspire-resource-name': 'event-hubs'
  }
}

resource messages 'Microsoft.EventHub/namespaces/eventhubs@2024-01-01' = {
  name: 'messages'
  parent: event_hubs
}

output eventHubsEndpoint string = event_hubs.properties.serviceBusEndpoint

output name string = event_hubs.name

上記の Bicep は、 Azure Event Hubs リソースをプロビジョニングするモジュールです。 さらに、ロールの割り当ては、別のモジュールで Azure リソースに対して作成されます。

@description('The ___location for the resource(s) to be deployed.')
param ___location string = resourceGroup().___location

param event_hubs_outputs_name string

param principalType string

param principalId string

resource event_hubs 'Microsoft.EventHub/namespaces@2024-01-01' existing = {
  name: event_hubs_outputs_name
}

resource event_hubs_AzureEventHubsDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(event_hubs.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'f526a384-b230-433a-b45c-95f59c4a2dec'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'f526a384-b230-433a-b45c-95f59c4a2dec')
    principalType: principalType
  }
  scope: event_hubs
}

生成された Bicep は開始点であり、C# のプロビジョニング インフラストラクチャへの変更の影響を受ける。 Bicep ファイルのカスタマイズは直接上書きされるため、C# プロビジョニング API を通じて変更を加えて、生成されたファイルに反映されるようにします。

プロビジョニング インフラストラクチャをカスタマイズする

すべての .NET AspireAzure リソースは、AzureProvisioningResource 型のサブクラスです。 この種類の型を使うことで、Azure API を利用して ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) リソースを構成する流暢な API が提供され、生成された Bicep をカスタマイズすることができます。 たとえば、kind、consistencyPolicy、locationsなどを構成できます。 次の例では、AzureAzure Cosmos DB リソースをカスタマイズする方法を示します。

builder.AddAzureEventHubs("event-hubs")
    .ConfigureInfrastructure(infra =>
    {
        var eventHubs = infra.GetProvisionableResources()
                             .OfType<EventHubsNamespace>()
                             .Single();

        eventHubs.Sku = new EventHubsSku()
        {
            Name = EventHubsSkuName.Premium,
            Tier = EventHubsSkuTier.Premium,
            Capacity = 7,
        };
        eventHubs.PublicNetworkAccess = EventHubsPublicNetworkAccess.SecuredByPerimeter;
        eventHubs.Tags.Add("ExampleKey", "Example value");
    });

前述のコード:

• ConfigureInfrastructure API への呼び出しを連鎖させます。
  • infra パラメーターは、AzureResourceInfrastructure 型のインスタンスです。
  • プロビジョニング可能なリソースは、GetProvisionableResources() メソッドを呼び出すことによって取得されます。
  • 単一の EventHubsNamespace リソースが取得されます。
  • EventHubsNamespace.Sku プロパティは、EventHubsSku の名前と層を持つ Premium の新しいインスタンスに、Capacityの 7 として割り当てられます。
  • PublicNetworkAccess プロパティは、SecuredByPerimeterに割り当てられます。
  • ExampleKey のキーと値が Example valueのタグが Event Hubs リソースに追加されます。

Event Hubs リソース リソースをカスタマイズするために使用できる構成オプションは他にも多数あります。 詳細については、Azure.Provisioning.PostgreSqlを参照してください。 詳細については、「 Azure.Provisioning カスタマイズ」を参照してください。

既存の Azure Event Hubs 名前空間に接続する

接続する既存の Azure Event Hubs サービスがある場合があります。 呼び出しをチェーンして、AzureEventHubsResource が既存のリソースであることを注釈付けることができます。

var builder = DistributedApplication.CreateBuilder(args);

var existingEventHubsName = builder.AddParameter("existingEventHubsName");
var existingEventHubsResourceGroup = builder.AddParameter("existingEventHubsResourceGroup");

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                    .AsExisting(existingEventHubsName, existingEventHubsResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(eventHubs);

// After adding all resources, run the app...

Azure Event Hubs リソースを既存のリソースとして扱う方法の詳細については、「既存のAzure リソースを使用する」を参照してください。

イベント ハブ コンシューマー グループの追加

コンシューマー グループを追加するには、IResourceBuilder<AzureEventHubsResource> の呼び出しを AddConsumerGroup API にチェーンします。

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs");
var messages = eventHubs.AddHub("messages");
messages.AddConsumerGroup("messagesConsumer");

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

// After adding all resources, run the app...

AddConsumerGroupを呼び出すと、messages Event Hub リソースが構成され、messagesConsumerという名前のコンシューマー グループが作成されます。 コンシューマー グループは、先ほど追加した Azure Event Hubs によって表される AzureEventHubsResource 名前空間に作成されます。 詳細については、「 Azure Event Hubs: コンシューマー グループ」を参照してください。

エミュレーターリソースAzure Event Hubsを追加する

.NET AspireAzure Event Hubs ホスティング統合では、mcr.microsoft.com/azure-messaging/eventhubs-emulator/latest コンテナー イメージに基づいて、Event Hubs リソースをエミュレーターとしてローカルで実行できます。 これは、開発およびテスト目的で Event Hubs リソースをローカルで実行する場合に役立ちます。これにより、Azure リソースをプロビジョニングしたり、既存の Azure Event Hubs サーバーに接続したりする必要がなくなります。

Event Hubs リソースをエミュレーターとして実行するには、RunAsEmulator メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator();

eventHubs.AddHub("messages");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(eventHubs);

// After adding all resources, run the app...

上記のコードでは、コンテナー内でローカルに実行するように Azure Event Hubs リソースを構成します。 詳細については、「 Azure Event Hubs Emulator」を参照してください。

Event Hubs エミュレーター コンテナーを構成する

コンテナー リソースにはさまざまな構成が用意されています。たとえば、コンテナーのポート、データ バインド マウント、データ ボリュームを構成したり、すべてをオーバーライドする wholistic JSON 構成を提供したりできます。

Event Hubs エミュレーター コンテナーのホスト ポートを構成する

既定では、.NET.NET Aspireによって構成された Event Hubs エミュレーター コンテナーは、次のエンドポイントを公開します。

リッスンしているポートは、既定では動的です。 コンテナーが起動すると、ポートはホスト コンピューター上のランダムなポートにマップされます。 エンドポイント ポートを構成するには、RunAsEmulator メソッドによって提供されるコンテナー リソース ビルダーの呼び出しをチェーンし、次の例に示すように WithHostPort(IResourceBuilder<AzureEventHubsEmulatorResource>, Nullable<Int32>) します。

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithHostPort(7777);
                       });

eventHubs.AddHub("messages");

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

// After adding all resources, run the app...

上記のコードでは、Azure イベント エミュレーター コンテナーの既存の emulator エンドポイントをポート 7777でリッスンするように構成します。 Azure イベント エミュレーター コンテナーのポートは、次の表に示すようにホスト ポートにマップされます。

データ ボリュームを使用して Event Hubs エミュレーターを追加する

Event Hubs エミュレーター リソースにデータ ボリュームを追加するには、Event Hubs エミュレーター リソースで WithDataVolume メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithDataVolume();
                       });

eventHubs.AddHub("messages");

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

// After adding all resources, run the app...

データ ボリュームは、Event Hubs エミュレーター のデータをコンテナーのライフサイクル外に保持するために使用されます。 データ ボリュームは、コンテナー内の /data パスにマウントされます。 set name パラメーターを指定しない限り、名前はランダムに生成されます。 データ ボリュームの詳細と、 バインド マウントよりも優先される理由の詳細については、「 Docker ドキュメント: ボリューム」を参照してください。

データ バインド マウントを使用して Event Hubs エミュレーターを追加する

次の例に示すように、Event Hubs エミュレーター コンテナーにバインド マウントを追加し、WithDataBindMount API への呼び出しをチェーンします。

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithDataBindMount("/path/to/data");
                       });

eventHubs.AddHub("messages");

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

// After adding all resources, run the app...

データ バインド マウントは、ホスト マシンのファイルシステムに依存して、コンテナーの再起動時に Azure Event Hubs エミュレーター リソース データを保持します。 データ バインド マウントは、コンテナー内のホスト コンピューターの /path/to/data パスにマウントされます。 データ バインド マウントの詳細については、「 Docker ドキュメント: バインド マウント」を参照してください。

Event Hubs エミュレーター コンテナー JSON 構成を構成する

Event Hubs エミュレーター コンテナーは、既定の config.json ファイルで実行されます。 このファイルを完全に置き換えることも、JSON 設定を JsonNode 設定の表現で更新することもできます。

カスタム JSON 構成ファイルを指定するには、WithConfigurationFile(IResourceBuilder<AzureEventHubsEmulatorResource>, String) メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithConfigurationFile("./messaging/custom-config.json");
                       });

eventHubs.AddHub("messages");

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

// After adding all resources, run the app...

上記のコードでは、Event Hubs エミュレーター コンテナーが、JSONにあるカスタム ./messaging/custom-config.json 構成ファイルを使用するように構成します。 これは、読み取り専用ファイルとして、コンテナーの /Eventhubs_Emulator/ConfigFiles/Config.json パスにマウントされます。 代わりに、既定の構成で特定のプロパティをオーバーライドするには、WithConfiguration(IResourceBuilder<AzureEventHubsEmulatorResource>, Action<JsonNode>) メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithConfiguration(
                               (JsonNode configuration) =>
                               {
                                   var userConfig = configuration["UserConfig"];
                                   var ns = userConfig["NamespaceConfig"][0];
                                   var firstEntity = ns["Entities"][0];
                                   
                                   firstEntity["PartitionCount"] = 5;
                               });
                       });

eventHubs.AddHub("messages");

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

// After adding all resources, run the app...

上記のコードは、既定の構成から UserConfig ノードを取得します。 次に、最初のエンティティの PartitionCount を 5に更新します。

ホスティング統合の正常性チェック

Azure Event Hubs ホスティング統合により、Event Hubs リソースの正常性チェックが自動的に追加されます。 正常性チェックでは、Event Hubs が実行されていること、およびイベント ハブへの接続を確立できることを確認します。

ホスティング統合は、AspNetCore.HealthChecks.📦Azureに依存します。Messaging.EventHubs NuGet パッケージ。

Client 統合

.NET AspireAzure Event Hubs クライアント統合を始めるには、📦 NuGet パッケージをイベント ハブ クライアントを使用するアプリケーションのプロジェクト、すなわちクライアントを消費するプロジェクトでインストールします。

dotnet add package Aspire.Azure.Messaging.EventHubs

<PackageReference Include="Aspire.Azure.Messaging.EventHubs"
                  Version="*" />

サポートされている Event Hubs クライアントの種類

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

クライアントの種類は、対応するオプション クラスと同様に、Azure用の .NET SDK から取得されます。 設定クラスは、.NET.NET Aspireによって提供されます。 設定クラスは、クライアント インスタンスを構成するために使用されます。

Event Hubs プロデューサー クライアントを追加する

クライアントを使用するプロジェクトの Program.cs ファイルで、任意の AddAzureEventHubProducerClient で IHostApplicationBuilder 拡張メソッドを呼び出して、依存関係挿入コンテナーを介して使用する EventHubProducerClient を登録します。 このメソッドは、接続名パラメーターを受け取ります。

builder.AddAzureEventHubProducerClient(connectionName: "event-hubs");

EventHubProducerClientを追加した後、依存関係の挿入を使用してクライアント インスタンスを取得できます。 たとえば、サンプル サービスからデータ ソース オブジェクトを取得するには、それをコンストラクター パラメーターとして定義し、ExampleService クラスが依存関係挿入コンテナーに登録されていることを確認します。

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

詳細については、以下を参照してください。

• Azureを参照してください。
• 依存関係の挿入の詳細については、.NETにおける依存関係の挿入をご参照ください。

考慮すべき追加 API

クライアント統合には、クライアント インスタンスを構成するための追加の API が用意されています。 Event Hubs クライアントを登録する必要がある場合は、次の API を検討してください。

前述のすべての API には、クライアント インスタンスを構成するための省略可能なパラメーターが含まれています。

キー付き Event Hubs プロデューサー クライアントを追加する

接続名が異なる複数の EventHubProducerClient インスタンスを登録する場合があります。 キー付き Event Hubs クライアントを登録するには、AddKeyedAzureServiceBusClient メソッドを呼び出します。

builder.AddKeyedAzureEventHubProducerClient(name: "messages");
builder.AddKeyedAzureEventHubProducerClient(name: "commands");

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

public class ExampleService(
    [KeyedService("messages")] EventHubProducerClient messagesClient,
    [KeyedService("commands")] EventHubProducerClient commandsClient)
{
    // Use clients...
}

詳細については、.NETのキー付きサービスを参照してください。

考慮すべきその他のキー付き API

クライアント統合には、キー付きクライアント インスタンスを構成するための追加の API が用意されています。 キー付き Event Hubs クライアントを登録する必要がある場合は、次の API を検討してください。

前述のすべての API には、クライアント インスタンスを構成するための省略可能なパラメーターが含まれています。

構成

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

接続文字列を使用する

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

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

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

完全修飾名前空間 (FQN)

AzureMessagingEventHubsSettings.Credential プロパティと連携して接続を確立する完全修飾名前空間を使用することをお勧めします。 資格情報が構成されていない場合は、DefaultAzureCredential が使用されます。

{
  "ConnectionStrings": {
    "event-hubs": "{your_namespace}.servicebus.windows.net"
  }
}

接続文字列

または、接続文字列を使用します。

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

構成プロバイダーを使用する

.NET AspireAzure 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"
            }
          }
        }
      }
    }
  }
}

完全なAzure Event Hubsクライアント統合JSONスキーマについては、Aspire.Azure.Messaging.EventHubs/ConfigurationSchema.jsonを参照してください。

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

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

可観測性とテレメトリ

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

伐採

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

• Azure.Core
• Azure.Identity

追跡

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

• Azure.Messaging.EventHubs.*

メトリック

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

関連項目

• Azure Event Hubs
• .NET AspireAzure 統合の概要
• .NET.NET Aspire 統合
• .NET AspireGitHub レポ