Add ResourceStoppedEvent with ResourceEvent state for enhanced lifecycle management (#11103)

* Initial plan

* Implement ResourceStoppedEvent and OnResourceStopped extension method

Co-authored-by: davidfowl <[email protected]>

* Add ResourceStoppedEvent test and fix implementation

Co-authored-by: davidfowl <[email protected]>

* Refactor ResourceStoppedEvent tests for improved clarity and structure

* Apply suggestions from code review

Co-authored-by: Copilot <[email protected]>

* Refactor resource event publishing to include hierarchy support and improve clarity

* Fix incorrect comment in PublishEventToHierarchy method

Co-authored-by: karolz-ms <[email protected]>

* Add ResourceEvent parameter to ResourceStoppedEvent and update ApplicationOrchestrator to get current state

Co-authored-by: davidfowl <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: davidfowl <[email protected]>
Co-authored-by: David Fowler <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: karolz-ms <[email protected]>

Author: 4 people

src/Aspire.Hosting/ApplicationModel/ResourceStoppedEvent.cs

@@ -0,0 +1,31 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Aspire.Hosting.Eventing;
+
+namespace Aspire.Hosting.ApplicationModel;
+
+/// <summary>
+/// This event is raised after a resource has stopped.
+/// </summary>
+/// <param name="resource">The resource that has stopped.</param>
+/// <param name="services">The <see cref="IServiceProvider"/> for the app host.</param>
+/// <param name="resourceEvent">The <see cref="ResourceEvent"/> containing the current state information.</param>
+/// <remarks>
+/// This event allows for cleanup or unregistration logic when a resource is stopped by an orchestrator.
+/// </remarks>
+public class ResourceStoppedEvent(IResource resource, IServiceProvider services, ResourceEvent resourceEvent) : IDistributedApplicationResourceEvent
+{
+    /// <inheritdoc />
+    public IResource Resource { get; } = resource;
+
+    /// <summary>
+    /// The <see cref="IServiceProvider"/> for the app host.
+    /// </summary>
+    public IServiceProvider Services { get; } = services;
+
+    /// <summary>
+    /// The <see cref="ResourceEvent"/> containing the current state information.
+    /// </summary>
+    public ResourceEvent ResourceEvent { get; } = resourceEvent;
+}

src/Aspire.Hosting/DistributedApplicationEventingExtensions.cs

@@ -22,6 +22,17 @@ public static IResourceBuilder<T> OnBeforeResourceStarted<T>(this IResourceBuild
         where T : IResource
         => builder.OnEvent(callback);
 
+    /// <summary>
+    /// Subscribes a callback to the <see cref="ResourceStoppedEvent"/> event within the AppHost.
+    /// </summary>
+    /// <typeparam name="T">The resource type.</typeparam>
+    /// <param name="builder">The resource builder.</param>
+    /// <param name="callback">A callback to handle the event.</param>
+    /// <returns>The <see cref="IResourceBuilder{T}"/>.</returns>
+    public static IResourceBuilder<T> OnResourceStopped<T>(this IResourceBuilder<T> builder, Func<T, ResourceStoppedEvent, CancellationToken, Task> callback)
+        where T : IResource
+        => builder.OnEvent(callback);
+
     /// <summary>
     /// Subscribes a callback to the <see cref="ConnectionStringAvailableEvent"/> event within the AppHost.
     /// </summary>

src/Aspire.Hosting/Orchestrator/ApplicationOrchestrator.cs

@@ -221,11 +221,11 @@ private async Task ProcessResourceUrlCallbacks(IResource resource, CancellationT
                     urls.Add(url);
 
                     // In the case that a service is bound to multiple addresses or a *.localhost address, we generate
-                        // additional URLs to indicate to the user other ways their service can be reached. If the service
-                        // is bound to all interfaces (0.0.0.0, ::, etc.) we use the machine name as the additional
-                        // address. If bound to a *.localhost address, we add the originally declared *.localhost address
-                        // as an additional URL.
-                        var additionalUrl = allocatedEndpoint.BindingMode switch
+                    // additional URLs to indicate to the user other ways their service can be reached. If the service
+                    // is bound to all interfaces (0.0.0.0, ::, etc.) we use the machine name as the additional
+                    // address. If bound to a *.localhost address, we add the originally declared *.localhost address
+                    // as an additional URL.
+                    var additionalUrl = allocatedEndpoint.BindingMode switch
                     {
                         // The allocated address doesn't match the original target host, so include the target host as
                         // an additional URL.
@@ -306,12 +306,35 @@ private async Task OnResourceEndpointsAllocated(ResourceEndpointsAllocatedEvent
 
     private async Task OnResourceChanged(OnResourceChangedContext context)
     {
+        // Get the previous state before updating to detect transitions to stopped states
+        string? previousState = null;
+        if (_notificationService.TryGetCurrentState(context.DcpResourceName, out var previousResourceEvent))
+        {
+            previousState = previousResourceEvent.Snapshot.State?.Text;
+        }
+
         await _notificationService.PublishUpdateAsync(context.Resource, context.DcpResourceName, context.UpdateSnapshot).ConfigureAwait(false);
 
         if (context.ResourceType == KnownResourceTypes.Container)
         {
             await SetChildResourceAsync(context.Resource, context.Status.State, context.Status.StartupTimestamp, context.Status.FinishedTimestamp).ConfigureAwait(false);
         }
+
+        // Check if the resource has transitioned to a terminal/stopped state
+        var currentState = context.Status.State;
+        if (currentState is not null &&
+            KnownResourceStates.TerminalStates.Contains(currentState) &&
+            previousState != currentState &&
+            (previousState is null ||
+            !KnownResourceStates.TerminalStates.Contains(previousState)))
+        {
+            // Get the current state from notification service after the update
+            if (_notificationService.TryGetCurrentState(context.DcpResourceName, out var currentResourceEvent))
+            {
+                // Resource has transitioned from a non-terminal state to a terminal state - fire ResourceStoppedEvent
+                await PublishEventToHierarchy(r => new ResourceStoppedEvent(r, _serviceProvider, currentResourceEvent), context.Resource, context.CancellationToken).ConfigureAwait(false);
+            }
+        }
     }
 
     private async Task OnResourceFailedToStart(OnResourceFailedToStartContext context)
@@ -466,4 +489,20 @@ private async Task PublishConnectionStringAvailableEvent(IResource resource, Can
             }
         }
     }
+
+    private async Task PublishEventToHierarchy<TEvent>(Func<IResource, TEvent> createEvent, IResource resource, CancellationToken cancellationToken)
+        where TEvent : IDistributedApplicationResourceEvent
+    {
+        // Publish the event to the resource itself.
+        await _eventing.PublishAsync(createEvent(resource), cancellationToken).ConfigureAwait(false);
+
+        // Publish the event to all child resources.
+        if (_parentChildLookup[resource] is { } children)
+        {
+            foreach (var child in children.Where(c => c is IResourceWithParent))
+            {
+                await PublishEventToHierarchy(createEvent, child, cancellationToken).ConfigureAwait(false);
+            }
+        }
+    }
 }

tests/Aspire.Hosting.Tests/Eventing/DistributedApplicationBuilderEventingTests.cs

@@ -6,6 +6,7 @@
 using Aspire.Hosting.Utils;
 using Microsoft.AspNetCore.InternalTesting;
 using Microsoft.Extensions.DependencyInjection;
+using Aspire.Hosting.Dashboard;
 
 namespace Aspire.Hosting.Tests.Eventing;
 
@@ -177,7 +178,7 @@ public async Task ResourceEventsForContainersFireForSpecificResources()
 
         using var builder = TestDistributedApplicationBuilder.Create();
         var redis = builder.AddRedis("redis")
-            .OnBeforeResourceStarted((_, e, _) =>    
+            .OnBeforeResourceStarted((_, e, _) =>
             {
                 Assert.NotNull(e.Services);
                 Assert.NotNull(e.Resource);
@@ -265,7 +266,83 @@ public async Task LifeycleHookAnalogousEventsFire()
         await app.StopAsync();
     }
 
+    [Fact]
+    public async Task ResourceStoppedEventCanBeSubscribedTo()
+    {
+        var eventFired = false;
+        var resourceStopped = default(IResource);
+
+        using var builder = TestDistributedApplicationBuilder.Create();
+        var resource = builder.AddResource(new TestResource("test-resource"))
+            .OnResourceStopped((res, evt, ct) =>
+            {
+                eventFired = true;
+                resourceStopped = res;
+                Assert.NotNull(evt.Services);
+                Assert.Equal(res, evt.Resource);
+                Assert.NotNull(evt.ResourceEvent);
+                Assert.Equal(res, evt.ResourceEvent.Resource);
+                return Task.CompletedTask;
+            });
+
+        // Verify the subscription was registered (the event handler is stored in the eventing service)
+        Assert.NotNull(resource);
+
+        // This test focuses on verifying subscription registration and callback structure.
+        // The following integration test handles actual event firing with complex setup.
+        using var app = builder.Build();
+        var eventing = app.Services.GetRequiredService<IDistributedApplicationEventing>();
+
+        // Manually fire the event to test the subscription
+        var testSnapshot = new CustomResourceSnapshot
+        {
+            ResourceType = "TestResource",
+            Properties = []
+        };
+        var testResourceEvent = new ResourceEvent(resource.Resource, "test-resource", testSnapshot);
+        var testEvent = new ResourceStoppedEvent(resource.Resource, app.Services, testResourceEvent);
+        await eventing.PublishAsync(testEvent, CancellationToken.None);
+
+        Assert.True(eventFired);
+        Assert.Equal(resource.Resource, resourceStopped);
+    }
+
+    [Fact]
+    [RequiresDocker]
+    public async Task ResourceStoppedEventFiresWhenResourceStops()
+    {
+        var resourceStoppedTcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
+
+        using var builder = TestDistributedApplicationBuilder.Create();
+        var redis = builder.AddRedis("redis")
+            .OnResourceStopped((resource, e, _) =>
+            {
+                Assert.NotNull(e.Services);
+                Assert.NotNull(e.Resource);
+                Assert.Equal(resource, e.Resource);
+                resourceStoppedTcs.TrySetResult();
+                return Task.CompletedTask;
+            });
+
+        using var app = builder.Build();
+        await app.StartAsync().DefaultTimeout(TestConstants.DefaultOrchestratorTestTimeout);
+
+        // Get the resource notification service to wait for the resource to start
+        await app.ResourceNotifications.WaitForResourceAsync("redis", KnownResourceStates.Running).DefaultTimeout();
+
+        await app.ResourceCommands.ExecuteCommandAsync("redis", KnownResourceCommands.StopCommand);
+
+        // Verify that ResourceStoppedEvent was fired
+        await resourceStoppedTcs.Task.DefaultTimeout();
+    }
+
     public class DummyEvent : IDistributedApplicationEvent
     {
     }
+
+    private sealed class TestResource(string name) : IResource
+    {
+        public string Name { get; } = name;
+        public ResourceAnnotationCollection Annotations { get; } = new();
+    }
 }