Aspire Resource Model: Concepts, Design, and Authoring Guidance

ResourceModel.md

MOVED to https://github.com/dotnet/aspire/blob/main/docs/specs/appmodel.md

WithAnnotation(): maybe mention behavior to append (default) or replace an existing one

Good call out.

Retrieving annotations can also be done from the resource.Annotations property, like resource.Annotations.OfType() when there can be many of a given annotation type

👍

Custom resources implementing IResourceWithWaitSupport may depend on other resources, so call notificationService.WaitForDependenciesAsync(resource, ct) before doing any custom orchestration

👍

IDistributedApplicationLifecycleHook is only shown in an example. I built many features on top of this primitive - maybe it deserves its own section.

We want people to switch to eventing, I think we need a couple more version then we'll recommend people use the other API as that will drive the custom resource lifecycle (and will solve lots of the problems we have manually building resources today).

When a resource implements the IResourceWithParent interface, it declares true containment — meaning its lifecycle is controlled by its parent:

Startup: The child resource will only start after its parent starts (though readiness is independent).
Shutdown: If the parent is stopped or removed, the child is also stopped automatically.

I find this really confusing as a resource author. It implies that IResourceWithParent imparts direct and automatic control of child resources, when the reality is very different. Resource authors decide which methods comprise startup calls, and also they choose lifecycle hooks and wire up eventing to call these things. How exactly does Aspire enforce these semantics?

There could be an analyzer that validates this -- example, if we say that "start" methods should be annotated with [EntryPoint] or [Startup], then a basic analyzer could ensure that these methods are not being called inside inappropriate eventing callbacks. Even then, this won't cover all scenarios. Something feels "off."

I think we will change this assumption. This really only applies to specific resources...