Événements dans .NET.NET Aspire

Article
12/12/2024

Dans .NET.NET Aspire, la gestion des événements vous permet de publier et de vous abonner à des événements pendant les différents cycles de vie de l'hôte de l'application . La gestion des événements est plus flexible que les événements du cycle de vie. Les deux vous permettent d’exécuter du code arbitraire pendant les rappels d’événements, mais la gestion des événements offre un contrôle plus précis du timing des événements, de leur publication, et propose la prise en charge d'événements personnalisés.

Les mécanismes d’événement dans .NET.NET Aspire font partie du package NuGet 📦Aspire.Hosting. Ce package fournit un ensemble d’interfaces et de classes dans l’espace de noms Aspire.Hosting.Eventing que vous utilisez pour publier et s’abonner à des événements dans votre projet hôte d’application .NET.NET Aspire. L’événement est limité à l’hôte de l’application lui-même et aux ressources dans lesquelles elle se trouve.

Dans cet article, vous allez découvrir comment utiliser les fonctionnalités d’événement dans .NET.NET Aspire.

Gestion événementielle de l'hôte d'application

Les événements suivants sont disponibles dans l’hôte de l’application et se produisent dans l’ordre suivant :

BeforeStartEvent: cet événement est déclenché avant le démarrage de l’hôte de l’application.
AfterEndpointsAllocatedEvent: cet événement est déclenché après que l’hôte d’application a alloué des points d'accès.
AfterResourcesCreatedEvent: cet événement est déclenché après que l’hôte d’application a créé des ressources.

Tous les événements précédents sont analogues aux cycles de vie d'hôte de l'application . Autrement dit, une implémentation du IDistributedApplicationLifecycleHook pourrait gérer ces événements de la même façon. Toutefois, avec l'API d'événements, vous pouvez exécuter du code arbitraire lorsque ces événements sont déclenchés et définir des événements personnalisés, c'est-à-dire tout événement qui implémente l'interface IDistributedApplicationEvent.

Pour vous abonner aux événements hôtes d’application intégrés, utilisez l’API d’événement. Une fois que vous avez une instance de générateur d’applications distribuée, accédez à la propriété IDistributedApplicationBuilder.Eventing et appelez l’API Subscribe<T>(Func<T,CancellationToken,Task>). Considérez l’exemple d’hôte d’application suivant Program.cs fichier :

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

Le code précédent est basé sur le modèle de démarrage avec l’ajout des appels à l’API Subscribe. L’API Subscribe<T> retourne une instance DistributedApplicationEventSubscription que vous pouvez utiliser pour vous désabonner de l’événement. Il est courant d’ignorer les abonnements retournés, car vous n’avez généralement pas besoin de vous désabonner des événements, car l’application entière est détruite lorsque l’hôte de l’application est arrêté.

Lorsque l’hôte de l’application est exécuté, au moment où le tableau de bord .NET.NET Aspire s’affiche, vous devez voir le journal de bord suivant dans la console.

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 sortie du journal confirme que les gestionnaires d’événements sont exécutés dans l’ordre des événements du cycle de vie de l’hôte de l’application. L’ordre d’abonnement n’affecte pas l’ordre d’exécution. Le BeforeStartEvent est déclenché en premier, suivi de AfterEndpointsAllocatedEvent, et enfin AfterResourcesCreatedEvent.

Événements de ressources

En plus des événements organisés par l'application, vous pouvez également vous abonner aux événements liés aux ressources. Les événements de ressource sont déclenchés spécifiques à une ressource individuelle. Les événements de ressource sont définis en tant qu’implémentations de l’interface IDistributedApplicationResourceEvent. Les événements de ressource suivants sont disponibles dans l’ordre indiqué :

ConnectionStringAvailableEvent: déclenché lorsqu’une chaîne de connexion devient disponible pour une ressource.
BeforeResourceStartedEvent: Activé avant que l'orchestrateur ne démarre une nouvelle ressource.
ResourceReadyEvent: déclenché lorsqu’une ressource passe initialement à un état prêt.

Pour vous abonner aux événements de ressource, utilisez l’API d’événement. Une fois que vous avez une instance de générateur d’applications distribuée, accédez à la propriété IDistributedApplicationBuilder.Eventing et appelez l’API Subscribe<T>(IResource, Func<T,CancellationToken,Task>). Considérez l’exemple d’hôte d’application suivant Program.cs fichier :

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

Le code précédent s’abonne aux événements ResourceReadyEvent, ConnectionStringAvailableEventet BeforeResourceStartedEvent sur la ressource cache. Quand AddRedis est appelée, elle retourne un IResourceBuilder<T> où T est un RedisResource. Le générateur de ressources expose la ressource en tant que propriété IResourceBuilder<T>.Resource. La ressource en question est ensuite transmise à l’API Subscribe pour s’abonner aux événements de la ressource.

Lorsque l’hôte de l’application est lancé, au moment où le tableau de bord .NET.NET Aspire s’affiche, vous devriez voir la sortie de journal suivante dans la console :

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.

Note

Certains événements bloquent. Par exemple, lorsque le BeforeResourceStartEvent est publié, le démarrage de la ressource est bloqué jusqu’à ce que tous les abonnements de cet événement sur une ressource donnée aient terminé leur exécution. Si un événement bloque ou non dépend de la façon dont il est publié (consultez la section suivante).

Publier des événements

Lorsque vous vous abonnez à l’un des événements intégrés, vous n’avez pas besoin de publier l’événement vous-même, car l’orchestrateur hôte d’application gère la publication d’événements intégrés en votre nom. Toutefois, vous pouvez publier des événements personnalisés avec l’API d’événementing. Pour publier un événement, vous devez d’abord définir un événement en tant qu’implémentation de l’interface IDistributedApplicationEvent ou IDistributedApplicationResourceEvent. Vous devez déterminer l’interface à implémenter selon que l’événement est un événement hôte d’application global ou un événement spécifique à une ressource.

Ensuite, vous pouvez vous abonner et publier l’événement en appelant l’une des API suivantes :

PublishAsync<T>(T, CancellationToken): publie un événement à tous les abonnés du type d’événement spécifique.
PublishAsync<T>(T, EventDispatchBehavior, CancellationToken): Publie un événement à tous les abonnés du type d’événement spécifique avec un comportement d'acheminement spécifié.

Veuillez fournir un `EventDispatchBehavior`

Lorsque des événements sont distribués, vous pouvez contrôler la façon dont les événements sont distribués aux abonnés. Le comportement de répartition des événements est spécifié avec l’énumération EventDispatchBehavior. Les comportements suivants sont disponibles :

EventDispatchBehavior.BlockingSequential: déclenche les événements de manière séquentielle et bloque jusqu’à ce qu’ils soient tous traités.
EventDispatchBehavior.BlockingConcurrent: déclenche des événements simultanément et bloque jusqu’à ce qu’ils soient tous traités.
EventDispatchBehavior.NonBlockingSequential: déclenche les événements séquentiellement, mais ne bloque pas.
EventDispatchBehavior.NonBlockingConcurrent: déclenche des événements simultanément, mais ne bloque pas.

Le comportement par défaut est EventDispatchBehavior.BlockingSequential. Pour remplacer ce comportement, lors de l’appel d’une API de publication telle que PublishAsync, fournissez le comportement souhaité en tant qu’argument.

Partager via

Événements dans .NET.NET Aspire

Gestion événementielle de l'hôte d'application

Événements de ressources

Publier des événements

Veuillez fournir un `EventDispatchBehavior`

Ressources supplémentaires

Partager via

Événements dans .NET.NET Aspire

Gestion événementielle de l'hôte d'application

S’abonner aux événements de l’hôte d’application

Événements de ressources

S’abonner aux événements de ressources

Publier des événements

Veuillez fournir un EventDispatchBehavior

Ressources supplémentaires

Veuillez fournir un `EventDispatchBehavior`