Delen via

Gebeurtenis in .NET.NET Aspire

  • Artikel

In .NET.NET Aspirekunt u met eventing gebeurtenissen publiceren en abonneren op gebeurtenissen tijdens verschillende app-hostlevenscycli. Eventing is flexibeler dan gebeurtenissen in de levenscyclus. Met beide kunt u willekeurige code uitvoeren tijdens callbacks voor gebeurtenissen, maar eventing biedt een nauwkeurigere controle over de timing van gebeurtenissen, publiceren en biedt ondersteuning voor aangepaste gebeurtenissen.

De gebeurtenismechanismen in .NET.NET Aspire maken deel uit van het 📦Aspire.Hosting NuGetpakket. Dit pakket biedt een set interfaces en klassen in de Aspire.Hosting.Eventing naamruimte die u gebruikt voor het publiceren en abonneren op gebeurtenissen in uw .NET.NET Aspire app-hostproject. Gebeurtenissen zijn gericht op de app-host zelf en de interne resources.

In dit artikel leert u hoe u de eventing-functies in .NET.NET Aspirekunt gebruiken.

Evenementbeheer door de app-host

De volgende gebeurtenissen zijn beschikbaar in de app-host en vinden plaats in de volgende volgorde:

  1. BeforeStartEvent: Deze gebeurtenis wordt gegenereerd voordat de apphost wordt gestart.
  2. AfterEndpointsAllocatedEvent: Deze gebeurtenis wordt gegenereerd nadat eindpunten aan de app-host zijn toegewezen.
  3. AfterResourcesCreatedEvent: deze gebeurtenis wordt gegenereerd nadat de app-host resources heeft gemaakt.

Alle voorgaande gebeurtenissen zijn vergelijkbaar met de app-hostlevenscycli. Dat wil gezegd dat een implementatie van de IDistributedApplicationLifecycleHook deze gebeurtenissen op dezelfde manier kan verwerken. Met de eventing-API kunt u echter willekeurige code uitvoeren wanneer deze gebeurtenissen worden gegenereerd en aangepaste gebeurtenissen definiëren, elke gebeurtenis die de IDistributedApplicationEvent-interface implementeert.

Abonneren op app-hostevenementen

Om u te abonneren op de ingebouwde app-hostgebeurtenissen, gebruikt u de gebeurtenis-API. Nadat u een gedistribueerd exemplaar van application builder hebt, gaat u naar de eigenschap IDistributedApplicationBuilder.Eventing en roept u de Subscribe<T>(Func<T,CancellationToken,Task>)-API aan. Bekijk het volgende Program.cs-bestand voor de host van de voorbeeld-app:

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

De voorgaande code is gebaseerd op de starterssjabloon met de toevoeging van de aanroepen naar de Subscribe-API. De Subscribe<T>-API retourneert een DistributedApplicationEventSubscription exemplaar dat u kunt gebruiken om u af te melden voor de gebeurtenis. Het is gebruikelijk om de geretourneerde abonnementen te negeren, omdat u zich meestal niet hoeft te afmelden voor gebeurtenissen omdat de hele app wordt afgebroken wanneer de app-host wordt afgesloten.

Wanneer de app-host wordt uitgevoerd, zou u tegen de tijd dat het .NET.NET Aspire dashboard wordt weergegeven, de volgende logboekuitvoer in de console moeten zien:

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.

De logboekuitvoer bevestigt dat gebeurtenishandlers worden uitgevoerd in de volgorde van de levenscyclusgebeurtenissen van de apphost. De abonnementsvolgorde heeft geen invloed op de uitvoeringsvolgorde. De BeforeStartEvent wordt eerst geactiveerd, gevolgd door AfterEndpointsAllocatedEventen ten slotte AfterResourcesCreatedEvent.

Resource-gebeurtenis

Naast de host-gebeurtenissen van de app kunt u zich ook abonneren op resource-gebeurtenissen. Resource-gebeurtenissen worden specifiek gegenereerd voor een afzonderlijke resource. Resource-gebeurtenissen worden gedefinieerd als implementaties van de IDistributedApplicationResourceEvent-interface. De volgende resource-gebeurtenissen zijn beschikbaar in de vermelde volgorde:

  1. ConnectionStringAvailableEvent: Gegeven wanneer een connectiestring beschikbaar is voor een resource.
  2. BeforeResourceStartedEvent: Uitgevoerd voordat de orchestrator een nieuwe resource start.
  3. ResourceReadyEvent: Gegenereerd wanneer een resource in eerste instantie overgaat naar een gereede status.

Abonneren op resource-gebeurtenissen

Als u zich wilt abonneren op resource-gebeurtenissen, gebruikt u de eventing-API. Nadat u een gedistribueerd exemplaar van application builder hebt, gaat u naar de eigenschap IDistributedApplicationBuilder.Eventing en roept u de Subscribe<T>(IResource, Func<T,CancellationToken,Task>)-API aan. Bekijk het volgende Program.cs-bestand voor de host van de voorbeeld-app:

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

De voorgaande code abonneert zich op de ResourceReadyEvent, ConnectionStringAvailableEventen BeforeResourceStartedEvent gebeurtenissen op de cache resource. Wanneer AddRedis wordt aangeroepen, wordt een IResourceBuilder<T> geretourneerd waarbij T een RedisResourceis. De resourcebouwer maakt de resource beschikbaar als de eigenschap IResourceBuilder<T>.Resource. De betreffende resource wordt vervolgens doorgegeven aan de Subscribe-API om u te abonneren op de gebeurtenissen in de resource.

Wanneer de app-host wordt uitgevoerd, ziet u op het moment dat het .NET.NET Aspire dashboard wordt weergegeven de volgende logboekuitvoer in de 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.

Notitie

Sommige evenementen zijn blokkerend. Wanneer de BeforeResourceStartEvent bijvoorbeeld wordt gepubliceerd, wordt het opstarten van de resource geblokkeerd totdat alle abonnementen voor die gebeurtenis op een bepaalde resource zijn uitgevoerd. Of een gebeurtenis wordt geblokkeerd of niet, is afhankelijk van hoe deze wordt gepubliceerd (zie de volgende sectie).

Gebeurtenissen publiceren

Wanneer u zich abonneert op een van de ingebouwde gebeurtenissen, hoeft u de gebeurtenis niet zelf te publiceren terwijl de orchestrator van de app-host ervoor zorgt dat ingebouwde gebeurtenissen namens u worden gepubliceerd. U kunt echter aangepaste gebeurtenissen publiceren met de eventing-API. Als u een gebeurtenis wilt publiceren, moet u eerst een gebeurtenis definiëren als een implementatie van de IDistributedApplicationEvent of IDistributedApplicationResourceEvent interface. U moet bepalen welke interface moet worden geïmplementeerd op basis van of de gebeurtenis een globale app-hostgebeurtenis of een resourcespecifieke gebeurtenis is.

Vervolgens kunt u zich abonneren en de gebeurtenis publiceren door een van de volgende API's aan te roepen:

Geef een EventDispatchBehavior

Wanneer gebeurtenissen worden verzonden, kunt u bepalen hoe de gebeurtenissen naar abonnees worden verzonden. Het gedrag voor het verzenden van gebeurtenissen wordt opgegeven met de EventDispatchBehavior enum. De volgende gedragingen zijn beschikbaar:

Het standaardgedrag is EventDispatchBehavior.BlockingSequential. Als u dit gedrag wilt overschrijven, geeft u bij het aanroepen van een publicatie-API, zoals PublishAsync, het gewenste gedrag op als argument.