Obsolete the IDistributedApplicationLifecycleHook interface and extension methods and add a new eventing based replacement

[danegsta]

Description

Deprecates IDistributedApplicationLifecycleHook and the LifecycleHookServiceCollectionExtensions extension methods and adds a new IDistributedApplicationEventingSubscriber and EventingSubscriberServiceCollectionExtensions methods to allow services to use the equivalent IDistributedApplicationEventing events (including BeforeStartEvent).

This change is necessary to complete the removal of the old AfterEndpointsAllocated event and callback in a future release which will allow us to properly support new features that require asynchronous discovery of allocated endpoints (such as proxyless persistent containers with random port allocation). These obsolete types will be removed in a future release, but the replacement has been designed to be relatively painless.

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No
• Does the change require an update in our Aspire docs?
  • Yes
    • Link to aspire-docs issue (consider using one of the following templates):
      • New (or update) doc-idea template
      • New breaking-change template
      • New diagnostic template
  • No

[github-actions]

🚀 Dogfood this PR with:

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 11266

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 11266"

[Copilot]

Pull Request Overview

This PR deprecates the IDistributedApplicationLifecycleHook interface and its extension methods, replacing them with a new event-driven approach using IDistributedApplicationEventingSubscriber. This change is necessary to properly support asynchronous endpoint discovery for new features like proxyless persistent containers with random port allocation.

• Marks the existing lifecycle hook interface and extension methods as obsolete
• Introduces new IDistributedApplicationEventingSubscriber interface and corresponding extension methods
• Migrates all internal usage from lifecycle hooks to the new eventing system

Reviewed Changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/Aspire.Hosting/Lifecycle/IDistributedApplicationLifecycleHook.cs	Marked interface as obsolete
src/Aspire.Hosting/Lifecycle/LifecycleHookServiceCollectionExtensions.cs	Marked extension methods as obsolete
src/Aspire.Hosting/Lifecycle/IDistributedApplicationEventingSubscriber.cs	New eventing subscriber interface
src/Aspire.Hosting/Lifecycle/EventingSubscriberServiceCollectionExtensions.cs	New extension methods for eventing subscribers
src/Aspire.Hosting/Dashboard/DashboardEventHandlers.cs	Migrated from lifecycle hook to eventing subscriber pattern
src/Aspire.Hosting/Devcontainers/DevcontainerPortForwardingLifecycleHook.cs	Migrated to eventing subscriber while keeping class name
src/Aspire.Hosting/DistributedApplication.cs	Updated to initialize eventing subscribers before publishing events
Multiple Azure infrastructure files	Migrated Azure provisioning and infrastructure classes to use eventing
Multiple test files	Added pragma warnings to suppress obsolete API usage in tests
Multiple playground files	Updated example projects to use new eventing pattern

[davidfowl]

I think we need to stage this. The eventing has a bunch of issues that prevent it from being a full replacement at the moment:

• Add replayable events on eventing. #9043
• Add TrySubscribeOnce API in IDistributedApplicationEventing #9042

[captainsafia]

Is the expected pattern for conditional subscription to do the check within SubscribeAsync? I assume so, but this will be a bit different from how we currently do conditional subscription. Maybe we can add a test to validate/document this?

[danegsta]

That was the pattern that seemed to make the most sense. With the callback based model there wasn't a way to selectively subscribe to a given hook so we did the checks in the actual callback, but with events it seemed better to only subscribe to the event if we actually wanted to receive it.

[danegsta]

I think we need to stage this. The eventing has a bunch of issues that prevent it from being a full replacement at the moment:

• Add replayable events on eventing. #9043
• Add TrySubscribeOnce API in IDistributedApplicationEventing #9042

Ah, I hadn't seen those issues, but ended up adding a new IDistributedApplicationEventingSubscriber interface to work around the same issues that were described in them (ensuring we can subscribe to events such as BeforeStartEvent early enough and ensuring we only subscribe once).