Události v .NET.NET Aspire

Článek
12/14/2024

V vám zpracovávání událostí umožňuje publikovat události a přihlásit se k jejich odběru během různých cyklů hostitelského životního prostředí aplikace. Události jsou flexibilnější než události životního cyklu. Obě metody umožňují spouštět libovolný kód během zpětných volání událostí, ale událostní systém nabízí jemnější řízení časování událostí, publikování a podporu pro vlastní události.

Mechanismy událostí v .NET.NET Aspire jsou součástí balíčku NuGet 📦Aspire.Hosting. Tento balíček poskytuje sadu rozhraní a tříd v oboru názvů Aspire.Hosting.Eventing, který používáte k publikování a přihlášení k odběru událostí v hostitelském projektu aplikace .NET.NET Aspire. Vytváření událostí je vymezeno na samotného hostitele aplikace a na prostředky v rámci.

V tomto článku se dozvíte, jak používat funkce událostí v .NET.NET Aspire.

Události hostitele aplikací

V hostiteli aplikace jsou k dispozici následující události a probíhají v následujícím pořadí:

BeforeStartEvent: Tato událost se vyvolá před spuštěním hostitele aplikace.
AfterEndpointsAllocatedEvent: Tato událost se vyvolá poté, co hostitel aplikace přidělil koncové body.
AfterResourcesCreatedEvent: Tato událost se vyvolá po vytvoření prostředků hostitele aplikace.

Všechny předchozí události jsou podobné životním cyklům hostitele aplikace . To znamená, že implementace IDistributedApplicationLifecycleHook by mohla zpracovávat tyto události stejně. Pomocí rozhraní API pro události ale můžete spustit libovolný kód, když se tyto události vyvolají, a definovat vlastní události – všechny události, které implementují rozhraní IDistributedApplicationEvent.

Pokud se chcete přihlásit k odběru předdefinovaných událostí hostitele aplikace, použijte rozhraní API pro vytváření událostí. Až budete mít instanci distribuovaného tvůrce aplikací, přejděte k vlastnosti IDistributedApplicationBuilder.Eventing a zavolejte rozhraní API Subscribe<T>(Func<T,CancellationToken,Task>). Zvažte následující soubor Program.cs pro ukázkové hostování aplikace :

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

Předchozí kód je založený na úvodní šabloně s přidáním volání do rozhraní API Subscribe. Rozhraní API Subscribe<T> vrátí instanci DistributedApplicationEventSubscription, kterou můžete použít k odhlášení odběru události. Vrácená předplatná se běžně zahodí, protože při vypnutí hostitele aplikace se obvykle nemusíte odhlásit od událostí, protože celá aplikace se ruší.

Když je hostitel aplikace spuštěný, po zobrazení řídicího panelu .NET.NET Aspire by se měl v konzole zobrazit následující výstup protokolu:

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.

Výstup protokolu potvrzuje, že obslužné rutiny událostí se spouští v pořadí událostí životního cyklu hostitele aplikace. Objednávka předplatného nemá vliv na pořadí provádění. Nejprve se aktivuje BeforeStartEvent a potom AfterEndpointsAllocatedEventa nakonec AfterResourcesCreatedEvent.

Zpracování událostí prostředků

Kromě událostí hostitele aplikace se můžete také přihlásit k odběru událostí prostředků. Události prostředků jsou vyvolány pro specifické jednotlivé prostředky. Události prostředků jsou definovány implementací rozhraní IDistributedApplicationResourceEvent. V uvedeném pořadí jsou dostupné tyto události prostředků:

ConnectionStringAvailableEvent: Vyvolá se při zpřístupnění připojovacího řetězce pro prostředek.
BeforeResourceStartedEvent: Vyvolá se předtím, než orchestrátor spustí nový prostředek.
ResourceReadyEvent: Vyvolá se při počátečním přechodu prostředku do připraveného stavu.

Pokud se chcete přihlásit k odběru událostí prostředků, použijte událostní API. Až budete mít instanci distribuovaného tvůrce aplikací, přejděte k vlastnosti IDistributedApplicationBuilder.Eventing a zavolejte rozhraní API Subscribe<T>(IResource, Func<T,CancellationToken,Task>). Zvažte následující ukázkový soubor hostitelské aplikace 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();

Předchozí kód odebírá události ResourceReadyEvent, ConnectionStringAvailableEventa BeforeResourceStartedEvent u prostředku cache. Když je zavolána AddRedis, vrátí IResourceBuilder<T>, kde T je RedisResource. Tvůrce prostředků zpřístupňuje prostředek jako vlastnost IResourceBuilder<T>.Resource. Příslušný prostředek se pak odevzdá rozhraní API Subscribe, aby bylo možné přihlásit se k odběru událostí na tomto prostředku.

Když je hostitel aplikace spuštěný, po zobrazení řídicího panelu .NET.NET Aspire by se měl v konzole zobrazit následující výstup protokolu:

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.

Poznámka

Některé události jsou blokující. Například při publikování BeforeResourceStartEvent bude spuštění prostředku blokováno, dokud se nedokončí spuštění všech odběrů pro danou událost daného prostředku. Jestli událost blokuje nebo ne, závisí na tom, jak je publikovaná (viz následující část).

Publikování událostí

Když se přihlašujete k odběru některé z předdefinovaných událostí, nemusíte událost publikovat sami, protože orchestrátor aplikací spravuje publikování předdefinovaných událostí vaším jménem. Vlastní události ale můžete publikovat pomocí rozhraní API pro události. Pokud chcete publikovat událost, musíte nejprve definovat událost jako implementaci rozhraní IDistributedApplicationEvent nebo IDistributedApplicationResourceEvent. Musíte určit, které rozhraní se má implementovat, na základě toho, jestli se jedná o událost globálního hostitele aplikace nebo událost specifickou pro prostředek.

Pak se můžete přihlásit k odběru a publikování události voláním některého z následujících rozhraní API:

PublishAsync<T>(T, CancellationToken): Publikuje událost všem odběratelům konkrétního typu události.
PublishAsync<T>(T, EventDispatchBehavior, CancellationToken): Publikuje událost všem odběratelům konkrétního typu události se zadaným chováním předání.

Vložte `EventDispatchBehavior`

Při odesílání událostí můžete řídit, jak se události odesílají odběratelům. Chování odeslání události je určeno výčtem EventDispatchBehavior. K dispozici jsou následující chování:

EventDispatchBehavior.BlockingSequential: Aktivuje události postupně a zablokuje, dokud nejsou všechny zpracovány.
EventDispatchBehavior.BlockingConcurrent: Spouští události souběžně a čeká, dokud nejsou všechny zpracovány.
EventDispatchBehavior.NonBlockingSequential: Aktivuje události postupně, ale neblokuje.
EventDispatchBehavior.NonBlockingConcurrent: Aktivuje události souběžně, ale neblokuje.

Výchozí chování je EventDispatchBehavior.BlockingSequential. Chcete-li toto chování přepsat, při volání rozhraní API pro publikování, jako je například PublishAsync, zadejte požadované chování jako argument.

Sdílet prostřednictvím

Události v .NET.NET Aspire

Události hostitele aplikací

Zpracování událostí prostředků

Publikování událostí

Vložte `EventDispatchBehavior`

Další materiály

Sdílet prostřednictvím

Události v .NET.NET Aspire

Události hostitele aplikací

Přihlášení k odběru událostí hostitele aplikace

Zpracování událostí prostředků

Přihlášení k odběru událostí zdrojů

Publikování událostí

Vložte EventDispatchBehavior

Další materiály

Vložte `EventDispatchBehavior`