Aspire Resource Model: Concepts, Design, and Authoring Guidance

ResourceModel.md

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

Yes, I will update this code.

When creating new resources, I added normal properties to the derived class. Had it been better if I used annotations, instead? 🤔

When creating new resources, I added normal properties to the derived class. Had it been better if I used annotations, instead? 🤔

I didn't mention it but the reason we want to use this pattern is because of dotnet/aspire#8984. You can still have properties but they should be backed by annotations (we have to do this work too). Resources are effectively a discriminated union and we want to be able to switch types on the fly without doing nasty hacks like what we have to do currently 😄

Read up to Values and References so far - some quick thoughts, some of these are very nit picky so feel free to ignore.

• Is it worth somewhere mentioning that this doc focuses on the hosting side, not client integrations.
• Quick Start - Would be pretty cool if the diagram was as screenshot of the resource graph from the dashboard.
• Annotations - is it worth having a sidenote mentioning these are similar to k8s annotations (+ how they differ).
• Fluent Extension Methods - is it worth mentioning that these are often in separate packages.
• Built-In Resources & Lifecycle - is it worth some discussion eventing vs lifecycle hooks? My take is that eventing is generally preferable, but lifecycle hooks do provide a nice way to get a single atomic event registration via TryAddLifecycleHook.
• Known Resource States - Is it worth mentioning the constants file Aspire.Hosting.ApplicationModel.KnownResourceStates
• Known Resource States - is it worth discussing Exited vs Finished, and recommend one over the other in light of dotnet/aspire#7373 .
• Resource Logging. Is it worth mentioning where those logs go, and why it is better to use them over a normal ILogger<T> from the host? (Possibly with screenshots)
• Manual Relationships - what are these used for? (e.g. resource graph on dashboard)

Important: Developers should not manually publish the ResourceReadyEvent. Aspire manages the transition to the ready state based on the presence and outcome of health checks.

Interesting, I'm sure I've had to publish this event myself for several custom resources to make waiting work. Let me check again - maybe this is just a hangover from playing around in early 9.0 previews before everything was fully baked.

Thanks @afscrome !

Example: Cross-Context Communication

• Missing grafana and keycloak resource declaration (or was it omitted on purpose?)

Annotations:

• WithAnnotation(): maybe mention behavior to append (default) or replace an existing one
• Retrieving annotations can also be done from the resource.Annotations property, like resource.Annotations.OfType<ResourceSnapshotAnnotation>() when there can be many of a given annotation type

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

• Methods are blocking
• Most of the time I keep background tasks in fields instead of starting non-observed tasks (like _ = DoSomethingAsync(ct)) - mostly for logging and ensuring background tasks work well until the end of the execution (final await in DisposeAsync).
• Custom resources implementing IResourceWithWaitSupport may depend on other resources, so call notificationService.WaitForDependenciesAsync(resource, ct) before doing any custom orchestration

Common interfaces:

• Mention IResourceWithWaitSupport

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...