Bagikan melalui

Peristiwa di .NET.NET Aspire

  • Artikel

Dalam .NET.NET Aspire, pemeventan memungkinkan Anda untuk menerbitkan dan berlangganan kejadian selama berbagai siklus hidup host aplikasi . Sistem Eventing lebih fleksibel daripada peristiwa dalam siklus hidup. Keduanya memungkinkan Anda menjalankan kode sewenang-wenang selama panggilan balik kejadian, tetapi sistem kejadian menawarkan kontrol yang lebih halus atas penjadwalan dan penerbitan kejadian, serta menyediakan dukungan untuk kejadian kustom.

Mekanisme peristiwa di .NET.NET Aspire adalah bagian dari 📦Aspire. Hosting paket NuGet. Paket ini menyediakan sekumpulan antarmuka dan kelas di namespace Aspire.Hosting.Eventing yang Anda gunakan untuk menerbitkan dan berlangganan peristiwa di proyek host aplikasi .NET.NET Aspire Anda. Penanganan kejadian dibatasi pada host aplikasi itu sendiri dan sumber daya di dalamnya.

Dalam artikel ini, Anda belajar cara menggunakan fitur event di .NET.NET Aspire.

Pengelolaan Peristiwa Host Aplikasi

Peristiwa berikut tersedia di host aplikasi dan terjadi dalam urutan berikut:

  1. BeforeStartEvent: Peristiwa ini dinaikkan sebelum host aplikasi dimulai.
  2. AfterEndpointsAllocatedEvent: Peristiwa ini dimunculkan setelah host aplikasi mengalokasikan titik akhir.
  3. AfterResourcesCreatedEvent: Peristiwa ini dipicu setelah host aplikasi membuat sumber daya.

Semua peristiwa sebelumnya dianalogikan dengan siklus hidup host aplikasi . Artinya, implementasi IDistributedApplicationLifecycleHook dapat menangani peristiwa ini sama saja. Namun, dengan API event, Anda dapat menjalankan kode sewenang-wenang saat kejadian ini dipicu dan bahkan mendefinisikan kejadian kustom—kejadian apa pun yang mengimplementasikan antarmuka IDistributedApplicationEvent.

Berlangganan acara yang diadakan oleh aplikasi

Untuk berlangganan peristiwa host aplikasi bawaan, gunakan API peristiwa. Setelah Anda memiliki instans penyusun aplikasi terdistribusi, lihat properti IDistributedApplicationBuilder.Eventing dan panggil API Subscribe<T>(Func<T,CancellationToken,Task>). Pertimbangkan contoh file host aplikasi Program.cs berikut:

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();

Kode sebelumnya berdasarkan pada templat awal dengan penambahan panggilan ke API Subscribe. API Subscribe<T> mengembalikan instans DistributedApplicationEventSubscription yang dapat Anda gunakan untuk berhenti berlangganan dari peristiwa. Hal ini wajar untuk membuang langganan yang dikembalikan, karena Anda biasanya tidak perlu berhenti menerima notifikasi dari acara saat seluruh aplikasi ditutup ketika host aplikasi dimatikan.

Saat host aplikasi dijalankan, pada saat dasbor .NET.NET Aspire ditampilkan, Anda akan melihat output log berikut di konsol:

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.

Output log mengonfirmasi bahwa penanganan aktivitas dijalankan dalam urutan peristiwa siklus hidup host aplikasi. Pesanan langganan tidak memengaruhi urutan eksekusi. BeforeStartEvent dipicu terlebih dahulu, diikuti oleh AfterEndpointsAllocatedEvent, dan akhirnya AfterResourcesCreatedEvent.

Pengelolaan peristiwa sumber daya

Selain peristiwa host aplikasi, Anda juga dapat berlangganan peristiwa sumber daya. Kejadian sumber daya dipicu khusus untuk sumber daya individu. Peristiwa sumber daya didefinisikan sebagai implementasi antarmuka IDistributedApplicationResourceEvent. Peristiwa sumber daya berikut ini tersedia dalam urutan yang tercantum:

  1. ConnectionStringAvailableEvent: Diluncurkan ketika string koneksi tersedia untuk sumber daya.
  2. BeforeResourceStartedEvent: Dimunculkan sebelum orkestrator memulai sumber daya baru.
  3. ResourceReadyEvent: Dinaikkan saat sumber daya awalnya beralih ke status siap.

Berlangganan ke peristiwa sumber daya

Untuk berlangganan peristiwa sumber daya, gunakan API peristiwa. Setelah Anda memiliki instans penyusun aplikasi terdistribusi, lihat properti IDistributedApplicationBuilder.Eventing dan panggil API Subscribe<T>(IResource, Func<T,CancellationToken,Task>). Contoh berkas program host aplikasi berikut: 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();

Kode sebelumnya mendaftarkan peristiwa ResourceReadyEvent, ConnectionStringAvailableEvent, dan BeforeResourceStartedEvent pada sumber daya cache. Ketika AddRedis dipanggil, ia mengembalikan sebuah IResourceBuilder<T> di mana T adalah RedisResource. Pembuat sumber daya mengekspos sumber daya sebagai properti IResourceBuilder<T>.Resource. Sumber daya yang dimaksud kemudian diteruskan ke API Subscribe untuk berlangganan peristiwa pada sumber daya.

Saat host aplikasi dijalankan, pada saat dasbor .NET.NET Aspire ditampilkan, Anda akan melihat output log berikut di konsol:

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.

Nota

Beberapa peristiwa menyebabkan pemblokiran. Misalnya, ketika BeforeResourceStartEvent diterbitkan, startup sumber daya akan diblokir hingga semua langganan untuk peristiwa tersebut pada sumber daya tertentu telah selesai dieksekusi. Apakah peristiwa diblokir atau tidak tergantung pada cara menerbitkannya (lihat bagian berikut).

Menerbitkan peristiwa

Saat berlangganan salah satu peristiwa bawaan, Anda tidak perlu menerbitkan peristiwa sendiri karena orkestrator host aplikasi berhasil menerbitkan peristiwa bawaan atas nama Anda. Namun, Anda dapat menerbitkan peristiwa kustom dengan API peristiwa. Untuk menerbitkan peristiwa, Anda harus terlebih dahulu menentukan peristiwa sebagai implementasi antarmuka IDistributedApplicationEvent atau IDistributedApplicationResourceEvent. Anda perlu menentukan antarmuka mana yang akan diterapkan berdasarkan apakah peristiwa tersebut adalah peristiwa host aplikasi global atau peristiwa khusus sumber daya.

Kemudian, Anda dapat berlangganan dan menerbitkan peristiwa dengan memanggil salah satu API berikut:

Menyediakan EventDispatchBehavior

Ketika peristiwa dikirim, Anda dapat mengontrol bagaimana peristiwa dikirim ke pelanggan. Perilaku pengiriman peristiwa ditentukan dengan enum EventDispatchBehavior. Perilaku berikut tersedia:

Perilaku default adalah EventDispatchBehavior.BlockingSequential. Untuk mengambil alih perilaku ini, saat memanggil API penerbitan seperti PublishAsync, berikan perilaku yang diinginkan sebagai argumen.