Compartir a través de

Eventos en .NET.NET Aspire

  • Artículo

En .NET.NET Aspire, el sistema de eventos permite publicar y suscribirse a eventos durante varios ciclos de vida del anfitrión de la aplicación . El evento es más flexible que los eventos del ciclo de vida. Ambos permiten ejecutar código arbitrario durante las devoluciones de llamada de eventos, pero la gestión de eventos ofrece un control más detallado del tiempo de los eventos, de la publicación y proporciona soporte para eventos personalizados.

Los mecanismos de eventos de .NET.NET Aspire forman parte del 📦AspireHosting paquete NuGet. Este paquete proporciona un conjunto de interfaces y clases en el espacio de nombres Aspire.Hosting.Eventing que se usan para publicar y suscribirse a eventos en el proyecto de host de aplicaciones .NET.NET Aspire. El ámbito de los eventos se limita al propio host de la aplicación y a los recursos dentro de ella.

En este artículo, aprenderá a utilizar las funciones de eventos en .NET.NET Aspire.

Organización de eventos de host de aplicaciones

Los siguientes eventos están disponibles en el host de la aplicación y se producen en el orden siguiente:

  1. BeforeStartEvent: este evento se genera antes de que se inicie el host de la aplicación.
  2. AfterEndpointsAllocatedEvent: este evento se genera después de que el host de la aplicación asigne puntos de conexión.
  3. AfterResourcesCreatedEvent: este evento se genera después de que el host de la aplicación haya creado recursos.

Todos los eventos anteriores son análogos a los ciclos de vida del host de la aplicación . Es decir, una implementación del IDistributedApplicationLifecycleHook podría manejar estos eventos de la misma manera. Sin embargo, con la API de eventos, puede ejecutar código arbitrario cuando estos eventos son generados e incluso definir eventos personalizados—cualquier evento que implemente la interfaz IDistributedApplicationEvent.

Suscribirse a eventos del anfitrión de aplicaciones

Para suscribirse a los eventos de host de la aplicación integrada, use la API de eventos. Una vez que tenga una instancia de generador de aplicaciones distribuidas, diríjase a la propiedad IDistributedApplicationBuilder.Eventing y utilice la API Subscribe<T>(Func<T,CancellationToken,Task>). Tenga en cuenta el siguiente ejemplo de host de aplicación archivo 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();

El código anterior se basa en la plantilla de inicio con la adición de las llamadas a la API de Subscribe. La API de Subscribe<T> devuelve una instancia de DistributedApplicationEventSubscription que puede usar para cancelar la suscripción del evento. Es común descartar las suscripciones devueltas, ya que generalmente no es necesario cancelar la suscripción de eventos, puesto que toda la aplicación se cierra cuando se apaga el host de la aplicación.

Cuando se ejecuta el host de la aplicación, en el momento en que se muestra el panel de .NET.NET Aspire, debería ver la siguiente salida de registro en la consola:

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.

La salida del registro confirma que los controladores de eventos se ejecutan en el orden de los eventos del ciclo de vida del host de la aplicación. El orden de suscripción no afecta al orden de ejecución. El BeforeStartEvent se desencadena primero, seguido de AfterEndpointsAllocatedEventy, por último, AfterResourcesCreatedEvent.

Eventos de recursos

Además de los eventos de host de la aplicación, también puede suscribirse a eventos de recursos. Los eventos de recursos se producen específicamente para un recurso individual. Los eventos de recursos se definen como implementaciones de la interfaz IDistributedApplicationResourceEvent. Los siguientes eventos de recursos están disponibles en el orden indicado:

  1. ConnectionStringAvailableEvent: se genera cuando una cadena de conexión está disponible para un recurso.
  2. BeforeResourceStartedEvent: Se genera antes de que el orquestador inicie un nuevo recurso.
  3. ResourceReadyEvent: Se activa cuando un recurso inicialmente cambia a un estado de disponibilidad.

Suscribirse a eventos de recursos

Para suscribirse a eventos de recursos, use la API de eventos. Una vez que tengas una instancia de un generador de aplicaciones distribuidas, dirígete a la propiedad IDistributedApplicationBuilder.Eventing y llama a la API Subscribe<T>(IResource, Func<T,CancellationToken,Task>). Tenga en cuenta el siguiente archivo Program.cs host de aplicación de ejemplo:

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

El código anterior se suscribe a los eventos ResourceReadyEvent, ConnectionStringAvailableEventy BeforeResourceStartedEvent en el recurso cache. Cuando se llama a AddRedis, devuelve un IResourceBuilder<T> donde T es un RedisResource. El generador de recursos expone el recurso como la propiedad IResourceBuilder<T>.Resource. A continuación, el recurso en cuestión se pasa a la API de Subscribe para suscribirse a los eventos del recurso.

Cuando se ejecuta el host de la aplicación, en el momento en que se muestra el panel de .NET.NET Aspire, debería ver la siguiente salida de registro en la consola:

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

Algunos eventos son bloqueantes. Por ejemplo, cuando se publica el BeforeResourceStartEvent, el inicio del recurso se bloqueará hasta que se hayan completado la ejecución de todas las suscripciones para ese evento en un recurso determinado. Si un evento es bloqueante o no depende de la forma en que se publique (consulte la sección siguiente).

Publicar eventos

Al suscribirse a cualquiera de los eventos integrados, no es necesario publicar el evento usted mismo, ya que el orquestador del host de la aplicación se encarga de publicar eventos integrados en su nombre. Sin embargo, puede publicar eventos personalizados con la API de eventos. Para publicar un evento, primero debe definir un evento como una implementación de la interfaz IDistributedApplicationEvent o IDistributedApplicationResourceEvent. Debe determinar qué interfaz implementar en función de si el evento es un evento de host de aplicación global o un evento específico del recurso.

A continuación, puede suscribirse y publicar el evento llamando a cualquiera de las siguientes API:

Proporcione un EventDispatchBehavior

Cuando se envían eventos, puede controlar cómo se envían los eventos a los suscriptores. El comportamiento de distribución de eventos se especifica con la enumeración EventDispatchBehavior. Los comportamientos siguientes están disponibles:

El comportamiento predeterminado es EventDispatchBehavior.BlockingSequential. Para invalidar este comportamiento, al llamar a una API de publicación como PublishAsync, proporcione el comportamiento deseado como argumento.