Lifecycle: Build vs Configure
ResourceKit executes resources in a predictable sequence so dependency flow stays explicit and easy to reason about.
Runtime order
Section titled “Runtime order”When the generated extension method is invoked, ResourceKit performs:
- Instantiate root resource kits from options, then each child with its parent instance.
- Validate the complete ownership graph and compute a stable parent-before-child order.
- Resolve the composition gates (host mode, groups and ancestors).
Buildeach enabled resource, parents before children.Configureeach enabled resource in the same order.
This happens before DistributedApplication.Build() completes. Graph validation runs before any Aspire
resource is created, so an invalid manual composition fails fast.
The two lifecycle pairs
Section titled “The two lifecycle pairs”Build/BuildResource(...): construct this resource (AddProject,AddRedis,AddAzureStorage, and so on).Configure/ConfigureResource(): attach resources to each other after construction (references, bindings, cross-resource wiring).
The separation keeps creation and cross-resource wiring explicit and deterministic.
How the generated host kit drives the lifecycle
Section titled “How the generated host kit drives the lifecycle”The generated host kit overrides Build and Configure:
Buildcreates each discovered resource kit from its options, registers all of them with the base class viaAddResource, invokes an optionalonBuiltcallback, and then callsbase.Build(builder), which runsBuildResource(...)for each resource.Configurecallsbase.Configure()first (running each resource’sConfigureResource()), then invokes an optionalonConfiguredcallback.
The extension method signature gives you hooks for extra wiring:
builder.AddAspireResourceKit( onBuilt: (hostKit, builder) => { /* after resources are created, before Configure */ }, onConfigured: hostKit => { /* after all resources are configured */ }, configureOptions: optionsBuilder => { /* additional options configuration */ });HostKitBase<THostKit> (the runtime base of the generated host kit) enforces that resources cannot be
added after Build seals the resource list, keeping the lifecycle single-run and deterministic.
Build vs Configure per resource
Section titled “Build vs Configure per resource”Each resource kit implements IResourceKit<THostKit>:
Build(IDistributedApplicationBuilder builder)calls yourBuildResource(...)override to construct the resource and store the resultingIResourceBuilder<TResource>inResourceBuilder.Configure()calls yourConfigureResource()override to attach resources to each other after construction.
A common Configure example that connects an API to its dependencies:
protected override void ConfigureResource(){ ResourceBuilder.WithReference(HostKit.Postgres.Database).WaitFor(HostKit.Postgres.Database); ResourceBuilder.WithReference(HostKit.AzureStorage.Blobs).WaitFor(HostKit.AzureStorage.Blobs);
if (HostKit.Redis.IsEnabled) ResourceBuilder.WithReference(HostKit.Redis).WaitFor(HostKit.Redis);}Because ConfigureResource() runs after every resource is built, you can safely reach other resources
through the host kit’s generated properties.
A child can use Parent directly inside its own BuildResource (Parent.ResourceBuilder also works but is
redundant; SG0040), because the parent has completed its build first. The relationship is fixed at
construction; a child never triggers its parent’s or its own Build recursively.
Failure policy
Section titled “Failure policy”- Exceptions from
BuildResourceandConfigureResourcepropagate unchanged. - A failed parent aborts the build; descendants are not built.
Configureskips a kit whose parent failed.- A host builds and configures at most once; repeated calls are no-ops.
See Parent and child resource kits.
Enablement gates both phases
Section titled “Enablement gates both phases”Before BuildResource(...) runs, ResourceKit checks whether the resource should participate:
- The configured
Mode(All,LocalDevelopment,Run,Publish) must participate in the current AppHost execution. - If
IsEnabledisfalse, bothBuildResource(...)andConfigureResource()are skipped. - During
Build,IsResourceEnabled(builder)is evaluated (only whenIsEnabledis alreadytrue) and its result is assigned back toIsEnabled.
See Enablement for the full model.