.NET .NET Aspire でのイベント

[アーティクル]
12/13/2024

.NET .NET Aspireでは、イベントを利用すると、さまざまなアプリホストライフサイクル中にイベントの発行およびサブスクライブが可能です。イベントは、ライフサイクルイベントよりも柔軟です。どちらもイベントコールバック中に任意のコードを実行できますが、イベント処理では、イベントのタイミング、発行、およびカスタムイベントのサポートを細かく制御できます。

.NET .NET Aspire のイベントメカニズムは、📦Aspireの一部です。NuGet パッケージホストします。このパッケージには、.NET.NET Aspire アプリホストプロジェクトのイベントの発行とサブスクライブに使用する、Aspire.Hosting.Eventing 名前空間のインターフェイスとクラスのセットが用意されています。イベントのスコープは、アプリホスト自体と内部のリソースです。

この記事では、.NET.NET Aspireでイベント機能を使用する方法について説明します。

アプリホストのイベント管理

次のイベントはアプリホストで使用でき、次の順序で発生します。

BeforeStartEvent: このイベントは、アプリホストが起動する前に発生します。
AfterEndpointsAllocatedEvent: このイベントは、アプリが割り当てられたエンドポイントをホストした後に発生します。
AfterResourcesCreatedEvent: このイベントは、アプリホストがリソースを作成した後に発生します。

上記のすべてのイベントは、アプリホストのライフサイクルに似ています。つまり、IDistributedApplicationLifecycleHook の実装では、これらのイベントを同じように処理できます。ただし、イベント API では、これらのイベントが発生したときに任意のコードを実行し、イベントによってカスタムイベント (IDistributedApplicationEvent インターフェイスを実装する任意のイベント) を定義できます。

組み込みのアプリホストイベントをサブスクライブするには、イベント API を使用します。分散アプリケーションビルダーインスタンスを作成したら、IDistributedApplicationBuilder.Eventing プロパティにアクセスし、Subscribe<T>(Func<T,CancellationToken,Task>) API を呼び出します。次のサンプルアプリホスト Program.cs ファイルについて考えてみましょう。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiService = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(cache)
    .WaitFor(cache)
    .WithReference(apiService)
    .WaitFor(apiService);

builder.Eventing.Subscribe<BeforeStartEvent>(
    static (@event, cancellationToken) =>
    {
        var logger = @event.Services.GetRequiredService<ILogger<Program>>();

        logger.LogInformation("1. BeforeStartEvent");

        return Task.CompletedTask;
    });

builder.Eventing.Subscribe<AfterEndpointsAllocatedEvent>(
    static (@event, cancellationToken) =>
    {
        var logger = @event.Services.GetRequiredService<ILogger<Program>>();

        logger.LogInformation("2. AfterEndpointsAllocatedEvent");

        return Task.CompletedTask;
    });

builder.Eventing.Subscribe<AfterResourcesCreatedEvent>(
    static (@event, cancellationToken) =>
    {
        var logger = @event.Services.GetRequiredService<ILogger<Program>>();

        logger.LogInformation("3. AfterResourcesCreatedEvent");

        return Task.CompletedTask;
    });

builder.Build().Run();

上記のコードは、Subscribe API への呼び出しを追加したスターターテンプレートに基づいています。 Subscribe<T> API は、イベントのサブスクライブ解除に使用できる DistributedApplicationEventSubscription インスタンスを返します。通常、アプリホストがシャットダウンされるとアプリ全体が破棄されるため、イベントのサブスクライブを解除する必要はないので、返されるサブスクリプションを破棄するのが一般的です。

アプリホストを実行すると、.NET.NET Aspire ダッシュボードが表示される時点までに、コンソールに次のログ出力が表示されます。

info: Program[0]
      1. BeforeStartEvent
info: Aspire.Hosting.DistributedApplication[0]
      Aspire version: 9.0.0
info: Aspire.Hosting.DistributedApplication[0]
      Distributed application starting.
info: Aspire.Hosting.DistributedApplication[0]
      Application host directory is: ..\AspireApp\AspireApp.AppHost
info: Program[0]
      2. AfterEndpointsAllocatedEvent
info: Aspire.Hosting.DistributedApplication[0]
      Now listening on: https://localhost:17178
info: Aspire.Hosting.DistributedApplication[0]
      Login to the dashboard at https://localhost:17178/login?t=<YOUR_TOKEN>
info: Program[0]
      3. AfterResourcesCreatedEvent
info: Aspire.Hosting.DistributedApplication[0]
      Distributed application started. Press Ctrl+C to shut down.

ログ出力は、イベントハンドラーがアプリホストのライフサイクルイベントの順序で実行されることを確認します。サブスクリプションの順序は、実行順序には影響しません。 BeforeStartEvent が最初にトリガーされ、次に AfterEndpointsAllocatedEventがトリガーされ、最後に AfterResourcesCreatedEventがトリガーされます。

リソースイベント管理

アプリホストイベントに加えて、リソースイベントをサブスクライブすることもできます。リソースイベントは、個々のリソースに固有に発生します。リソースイベントは、IDistributedApplicationResourceEvent インターフェイスの実装として定義されます。次のリソースイベントは、一覧に示されている順序で使用できます。

ConnectionStringAvailableEvent: 接続文字列がリソースで使用可能になったときに発生します。
BeforeResourceStartedEvent: オーケストレーターが新しいリソースを開始する前にトリガーされます。
ResourceReadyEvent: リソースが最初に準備完了状態に遷移したときに発生します。

リソースイベントをサブスクライブするには、イベント API を使用します。分散アプリケーションビルダーインスタンスを作成したら、IDistributedApplicationBuilder.Eventing プロパティにアクセスし、Subscribe<T>(IResource, Func<T,CancellationToken,Task>) API を呼び出します。次のサンプルアプリホスト Program.cs ファイルについて考えてみましょう。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

builder.Eventing.Subscribe<ResourceReadyEvent>(
    cache.Resource,
    static (@event, cancellationToken) =>
    {
        var logger = @event.Services.GetRequiredService<ILogger<Program>>();

        logger.LogInformation("3. ResourceReadyEvent");

        return Task.CompletedTask;
    });

builder.Eventing.Subscribe<BeforeResourceStartedEvent>(
    cache.Resource,
    static (@event, cancellationToken) =>
    {
        var logger = @event.Services.GetRequiredService<ILogger<Program>>();

        logger.LogInformation("2. BeforeResourceStartedEvent");

        return Task.CompletedTask;
    });

builder.Eventing.Subscribe<ConnectionStringAvailableEvent>(
    cache.Resource,
    static (@event, cancellationToken) =>
    {
        var logger = @event.Services.GetRequiredService<ILogger<Program>>();

        logger.LogInformation("1. ConnectionStringAvailableEvent");

        return Task.CompletedTask;
    });

var apiService = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(cache)
    .WaitFor(cache)
    .WithReference(apiService)
    .WaitFor(apiService);

builder.Build().Run();

上記のコードは、cache リソースの ResourceReadyEvent、ConnectionStringAvailableEvent、および BeforeResourceStartedEvent イベントをサブスクライブします。 AddRedis が呼び出されると、T が RedisResourceである IResourceBuilder<T> が返されます。リソースビルダーは、リソースを IResourceBuilder<T>.Resource プロパティとして公開します。その後、対象のリソースが Subscribe API に渡され、リソース上のイベントをサブスクライブします。

アプリホストを実行すると、.NET.NET Aspire ダッシュボードが表示される時点までに、コンソールに次のログ出力が表示されます。

info: Aspire.Hosting.DistributedApplication[0]
      Aspire version: 9.0.0
info: Aspire.Hosting.DistributedApplication[0]
      Distributed application starting.
info: Aspire.Hosting.DistributedApplication[0]
      Application host directory is: ..\AspireApp\AspireApp.AppHost
info: Program[0]
      1. ConnectionStringAvailableEvent
info: Program[0]
      2. BeforeResourceStartedEvent
info: Program[0]
      3. ResourceReadyEvent
info: Aspire.Hosting.DistributedApplication[0]
      Now listening on: https://localhost:17222
info: Aspire.Hosting.DistributedApplication[0]
      Login to the dashboard at https://localhost:17222/login?t=<YOUR_TOKEN>
info: Aspire.Hosting.DistributedApplication[0]
      Distributed application started. Press Ctrl+C to shut down.

手記

一部のイベントがブロックされています。たとえば、BeforeResourceStartEvent が発行されると、特定のリソースのそのイベントのすべてのサブスクリプションの実行が完了するまで、リソースの起動はブロックされます。イベントがブロックされているかどうかは、イベントの発行方法によって異なります (次のセクションを参照)。

イベントを発行する

いずれかの組み込みイベントをサブスクライブする場合、アプリホストオーケストレーターがユーザーに代わって組み込みイベントを発行するために管理するため、イベントを自分で発行する必要はありません。ただし、イベント API を使用してカスタムイベントを発行できます。イベントを発行するには、まず、IDistributedApplicationEvent インターフェイスまたは IDistributedApplicationResourceEvent インターフェイスの実装としてイベントを定義する必要があります。イベントがグローバルアプリホストイベントかリソース固有のイベントかに基づいて、実装するインターフェイスを決定する必要があります。

その後、次のいずれかの API を呼び出して、イベントをサブスクライブして発行できます。

PublishAsync<T>(T, CancellationToken): 特定のイベントの種類のすべての購読者にイベントを公開します。
PublishAsync<T>(T, EventDispatchBehavior, CancellationToken): 指定したディスパッチ動作を使用して、特定のイベントタイプのすべての購読者にイベントを発行します。

`EventDispatchBehavior` を指定する

イベントがディスパッチされるときに、イベントをサブスクライバーにディスパッチする方法を制御できます。イベントディスパッチ動作は、EventDispatchBehavior 列挙型で指定されます。次の動作を使用できます。

EventDispatchBehavior.BlockingSequential: イベントを順番に発生させ、すべてが処理されるまでブロックします。
EventDispatchBehavior.BlockingConcurrent: イベントを同時に発生させ、すべてが処理されるまでブロックします。
EventDispatchBehavior.NonBlockingSequential: イベントを順番に発生させますが、ブロックしません。
EventDispatchBehavior.NonBlockingConcurrent: イベントを同時に発生させますが、ブロックしません。

既定の動作は EventDispatchBehavior.BlockingSequentialです。この動作をオーバーライドするには、PublishAsyncなどの発行 API を呼び出すときに、必要な動作を引数として指定します。

次の方法で共有

.NET .NET Aspire でのイベント

アプリホストのイベント管理

リソースイベント管理

イベントを発行する

`EventDispatchBehavior` を指定する

その他のリソース

次の方法で共有

.NET .NET Aspire でのイベント

アプリホストのイベント管理

アプリホストイベントに登録する

リソースイベント管理

リソース イベントをサブスクライブする

イベントを発行する

EventDispatchBehavior を指定する

その他のリソース

リソースイベントをサブスクライブする

`EventDispatchBehavior` を指定する