You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Add typed resource projections for run and publish - #19880
Aspire integrations currently use annotation-based conversion to make executable, project, and managed resources behave like containers. That blurs the distinction between the logical resource identity and the effective resource shape, particularly when integrations replace a resource during realization.
This change adds an additive resource projection model for Aspire 13.6, covering both run and publish:
A resource can carry a container projection scoped to a single operation. RunAsContainerImage registers one from an image; PublishAsDockerFile and the Azure RunAsContainer/RunAsEmulator APIs are reimplemented on top of the same primitive.
The owner remains the sole logical model resource and retains canonical identity for references, callbacks, events, notifications, pipeline steps, and manifest evaluation.
Projection annotations share the owner's annotation collection; only container-specific property state is read from the projection facade.
Central runtime and publishing shape resolution treats a selected projection as authoritative. When no projection is registered, those central paths retain their existing annotation-based classification and realization behavior. This fallback does not require an integration migrated to a typed projection—such as a built-in emulator—to support manually reconstructing its former annotation configuration without that projection.
DCP, Docker Compose, Kubernetes, Azure Container Apps, Azure Sandboxes, Radius, and language integration paths realize projected owners consistently.
Existing public interfaces, annotation collection types, and stable API signatures remain binary compatible.
User-facing usage
Integrations can expose container-only configuration without changing the owner builder type:
In both cases the callback receives a container-typed builder, while the owner builder keeps its original type and the owner remains the only member of the application model.
Typed projections
Integrations that need a strongly typed projection resource implement IContainerProjection<TOwner, TSelf>, whose static abstract CreateProjection resolves the projection type at the call site with no factory delegate and no reflection:
Projection interfaces also raise a compatibility question for behavioral resource contracts such as IResourceWithConnectionString. A selected projection may need to provide connection-string behavior that differs from its owner. Framework-controlled paths now consume that capability lazily through GetValueProvider<IResourceWithConnectionString>() and ConnectionStringReference: the owner remains the canonical referenced resource, while the effective projection is selected when the value is evaluated. ConnectionStringReferenceResolution.PreferOwner provides an explicit escape hatch for scenarios that intentionally require owner behavior.
Third-party code can still bypass that resolution by directly reading the instance it already holds:
That CLR property access dispatches directly to the held owner or projection and cannot be transparently redirected by the projection framework. If the held value is the owner, such code may continue producing the owner's connection string even when a projection is the effective acting resource.
ASPIRE013 warns about direct C# access to ConnectionStringExpression and points source consumers toward projection-aware resolution. This is useful migration guidance but is not complete enforcement: analyzers can be disabled or suppressed; the AppHost analyzer only examines source compiled in the AppHost and cannot inspect an already-compiled integration assembly; and the analyzer shipped for integration authors is currently opt-in. The existing interface property therefore remains a compatibility boundary rather than a mechanism the framework can transparently virtualize.
Projection support is intentionally capability- and resource-specific rather than implicitly transitive. A projection registered for a parent does not automatically project its descendants or rewrite concrete parent/child composition such as a database resource calling a server-specific BuildConnectionString method. Integrations with that coupling must intentionally preserve compatible shared configuration, expose a specialized capability, or project the affected child resources. Aspire 13.6 enables projection overrides where integrations opt into them; it does not promise that an arbitrary projection can be applied cleanly to every existing resource graph.
Diagnostics
Projecting a resource that is already a container is always an authoring mistake: the projection shares the owner's annotation collection, so the projected image and endpoints would collide with those already carried by the container. C# cannot express a negative generic constraint, so ASPIRE012 reports statically known container receivers, generated SDKs exclude container target types from RunAsContainerImage, and a runtime check remains as a backstop for reflection, suppressed diagnostics, and other indirect calls.
Scope
This PR establishes the projection model and migrates the existing built-in run and publish conversion paths needed to prove it end to end. It intentionally does not narrow or obsolete existing permissive APIs. Container-specific WithEndpoint specialization and any additional API availability diagnostics require separate API design and compatibility review and can be delivered independently in follow-up PRs; they are not required for the projection implementation to function.
Validation includes focused projection precedence and central no-projection classification and realization tests, owner-only model identity and callback tests, run and publish operation gating tests, DCP and publishing scenarios, Docker Compose/Kubernetes/Azure artifact coverage, language integration publishing tests, analyzer tests for ASPIRE012 and ASPIRE013, polyglot code generation snapshots, and a compatibility fixture compiled against Aspire.Hosting 13.5.3 that directly implements IResource and mutates annotations when loaded against the current build.
Addresses findings from a follow-up review of the projection annotation
layering work:
- RemoveAt no longer consults a per-thread IndexOf cache. Resolving a prior
lookup by identity removed the wrong element whenever an insert shifted
positions between IndexOf and RemoveAt, which was reproducible on the public
ResourceAnnotationCollection surface. The cache also pinned annotation
instances per thread and made IndexOf take the write lock, contradicting the
documented lock-free read contract.
- Indexed insert/set inside a projection configuration callback now throws
instead of collapsing the layered view onto the local-only snapshot, which
silently discarded every inherited owner annotation.
- Layered reads cache the merged snapshot and invalidate on an owner or local
version bump, and visibility filtering no longer allocates LINQ delegates per
element.
- WithAnnotation(Replace) runs the duplicate-annotation diagnostic before
suppression so the long-standing SingleOrDefault check still fires.
- ShowInheritedAnnotations no longer throws from a finally block, where it could
mask an exception raised by the configuration callback.
- Projection registration and effective resolution share one selection helper so
multiple projections for the same operation fail consistently.
- Replaces the 13.5 package-based binary compatibility asset with a cheap shape
assertion; end-to-end validation against a shipped package is a one-time
review exercise rather than a per-build test.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Keep canonical owners as the sole model members while making model reads projection-aware and preserving owner identity at runtime boundaries.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: e4453cca-0f47-43da-94a9-6b0bf8751d66
Keep canonical owners in the model and apply projected container annotations directly to those owners while preserving container-only property state for realization.
Add focused owner identity, precedence, publisher, and Aspire 13.5 binary compatibility coverage.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: e4453cca-0f47-43da-94a9-6b0bf8751d66
Do not let raw container image annotations bypass the unsupported DotnetProjectResource publisher check.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: e4453cca-0f47-43da-94a9-6b0bf8751d66
Use canonical owners and projection markers in integrations, and resolve the typed container view only at the manifest serialization boundary.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: e4453cca-0f47-43da-94a9-6b0bf8751d66
Avoid replacing the validated container manifest callback when configuring Next.js standalone publishing, and cover authored Dockerfiles with an overridden run script.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: e4453cca-0f47-43da-94a9-6b0bf8751d66
Have the owner-side projection annotation read entrypoint and shell execution directly from the typed facade so late direct property updates reach every realizer.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: e4453cca-0f47-43da-94a9-6b0bf8751d66
Enumerating every model read as the effective projection leaks the projection into identity-sensitive publisher callbacks. Docker Compose stores the enumerated value as TargetResource and passes it to environment, argument, Dockerfile, and filesystem callback contexts; Kubernetes and other deployment paths do the same. Those callbacks therefore receive the projection rather than the canonical owner, contrary to this PR's owner-identity invariant. Keep using the projection for container shape, but normalize the resource passed to callback contexts with GetOwnerOrSelf() across these publishers.
Register non-container effective resource views through the shared owner/projection mapping and use it for Azure PostgreSQL database facades. Restore typed PostgreSQL child discovery for lifecycle initialization and PgWeb while retaining Azure database owners as canonical model members.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: e4453cca-0f47-43da-94a9-6b0bf8751d66
Route nested ReferenceExpression providers through the projection-aware expression resolver so connection-string aliases cannot silently fall back to owner values. Cover direct, aliased, and manifest resolution.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: e4453cca-0f47-43da-94a9-6b0bf8751d66
The legacy Parent.IsEmulator condition was removed here too. With only container/image annotations and no projection, the effective provider is the owner, so this path incorrectly chooses account-endpoint configuration for Azure Functions instead of the emulator connection string. Preserve the legacy emulator check alongside projection detection.
Retain Parent.IsEmulator fallback without projection
This replaces the old Parent.IsEmulator check with only projection detection. For a legacy annotation-based emulator with no selected projection, provider is still the owner and this condition is false, so Azure Functions receives the account-endpoint configuration instead of the emulator connection string. Keep the Parent.IsEmulator fallback as well.
This projection check also drops the legacy IsEmulator case. Without a selected capability projection, an existing annotation-based emulator resolves provider to the owner and now receives account-endpoint configuration in Azure Functions instead of the emulator connection string; preserve IsEmulator in this condition.
Diagnostic-ID coordination: #21288 is keeping ASPIRE013 for the required C# CLI-bundle error, restoring ASPIRE010 to its original suppressible warning. Please renumber the connection-string analyzer before this PR merges, including its help link, diagnostic documentation, and tests. #21592 also currently proposes ASPIRE013, and #21545 uses ASPIRE014, so the two pending PRs need distinct unused IDs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
area-app-modelIssues pertaining to the APIs in Aspire.Hosting, e.g. DistributedApplication
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Aspire integrations currently use annotation-based conversion to make executable, project, and managed resources behave like containers. That blurs the distinction between the logical resource identity and the effective resource shape, particularly when integrations replace a resource during realization.
This change adds an additive resource projection model for Aspire 13.6, covering both run and publish:
RunAsContainerImageregisters one from an image;PublishAsDockerFileand the AzureRunAsContainer/RunAsEmulatorAPIs are reimplemented on top of the same primitive.User-facing usage
Integrations can expose container-only configuration without changing the owner builder type:
An image-based projection scoped to
aspire runlooks the same:In both cases the callback receives a container-typed builder, while the owner builder keeps its original type and the owner remains the only member of the application model.
Typed projections
Integrations that need a strongly typed projection resource implement
IContainerProjection<TOwner, TSelf>, whosestatic abstract CreateProjectionresolves the projection type at the call site with no factory delegate and no reflection:Connection string capability compatibility
Projection interfaces also raise a compatibility question for behavioral resource contracts such as
IResourceWithConnectionString. A selected projection may need to provide connection-string behavior that differs from its owner. Framework-controlled paths now consume that capability lazily throughGetValueProvider<IResourceWithConnectionString>()andConnectionStringReference: the owner remains the canonical referenced resource, while the effective projection is selected when the value is evaluated.ConnectionStringReferenceResolution.PreferOwnerprovides an explicit escape hatch for scenarios that intentionally require owner behavior.Third-party code can still bypass that resolution by directly reading the instance it already holds:
That CLR property access dispatches directly to the held owner or projection and cannot be transparently redirected by the projection framework. If the held value is the owner, such code may continue producing the owner's connection string even when a projection is the effective acting resource.
ASPIRE013warns about direct C# access toConnectionStringExpressionand points source consumers toward projection-aware resolution. This is useful migration guidance but is not complete enforcement: analyzers can be disabled or suppressed; the AppHost analyzer only examines source compiled in the AppHost and cannot inspect an already-compiled integration assembly; and the analyzer shipped for integration authors is currently opt-in. The existing interface property therefore remains a compatibility boundary rather than a mechanism the framework can transparently virtualize.Projection support is intentionally capability- and resource-specific rather than implicitly transitive. A projection registered for a parent does not automatically project its descendants or rewrite concrete parent/child composition such as a database resource calling a server-specific
BuildConnectionStringmethod. Integrations with that coupling must intentionally preserve compatible shared configuration, expose a specialized capability, or project the affected child resources. Aspire 13.6 enables projection overrides where integrations opt into them; it does not promise that an arbitrary projection can be applied cleanly to every existing resource graph.Diagnostics
Projecting a resource that is already a container is always an authoring mistake: the projection shares the owner's annotation collection, so the projected image and endpoints would collide with those already carried by the container. C# cannot express a negative generic constraint, so
ASPIRE012reports statically known container receivers, generated SDKs exclude container target types fromRunAsContainerImage, and a runtime check remains as a backstop for reflection, suppressed diagnostics, and other indirect calls.Scope
This PR establishes the projection model and migrates the existing built-in run and publish conversion paths needed to prove it end to end. It intentionally does not narrow or obsolete existing permissive APIs. Container-specific
WithEndpointspecialization and any additional API availability diagnostics require separate API design and compatibility review and can be delivered independently in follow-up PRs; they are not required for the projection implementation to function.Validation includes focused projection precedence and central no-projection classification and realization tests, owner-only model identity and callback tests, run and publish operation gating tests, DCP and publishing scenarios, Docker Compose/Kubernetes/Azure artifact coverage, language integration publishing tests, analyzer tests for
ASPIRE012andASPIRE013, polyglot code generation snapshots, and a compatibility fixture compiled against Aspire.Hosting 13.5.3 that directly implementsIResourceand mutates annotations when loaded against the current build.Fixes #19836
Checklist
<remarks />and<code />elements on your triple slash comments?