Support arbitrary IValueProvider sources in Docker Compose .env file generation

[sliekens]

Description

When generating the .env file adjacent to the Docker Compose file, DockerComposeEnvironmentResource.PrepareAsync resolved values for two specific source types: ParameterResource and ContainerImageReference. Any other type that implements IValueProvider — including custom resource types defined in external repos — was silently ignored, leaving the env var with whatever static default was set (or blank).

This change collapses the ContainerImageReference-specific branch into a generic IValueProvider branch, and adds a comment explaining the asymmetric treatment of ParameterResource.

-            if (defaultValue is null && envVar.Source is ParameterResource parameter)
+            // Only resolve from the parameter if no static default is already set;
+            // a caller that provides an explicit default intends to skip parameter resolution.
+            if (envVar.Source is ParameterResource parameter)
             {
-                defaultValue = await parameter.GetValueAsync(context.CancellationToken).ConfigureAwait(false);
+                defaultValue ??= await parameter.GetValueAsync(context.CancellationToken).ConfigureAwait(false);
             }
-
-            if (envVar.Source is ContainerImageReference cir)
+            else if (envVar.Source is IValueProvider vp)
             {
-                defaultValue = await ((IValueProvider)cir).GetValueAsync(context.CancellationToken).ConfigureAwait(false);
+                // IValueProvider sources are always resolved dynamically — a static default is never used.
+                defaultValue = await vp.GetValueAsync(context.CancellationToken).ConfigureAwait(false);
             }

ContainerImageReference already implements IValueProvider, so it is handled by the new branch without any change in behavior. ParameterResource is kept as a separate leading branch because it skips resolution when a static default is already set — the else ensures it cannot fall through to the IValueProvider branch.

Alternatives considered

Keep ContainerImageReference explicit and add an IValueProvider fallback as a third branch
The natural first approach is to leave the two existing branches untouched and append a catch-all:

             if (envVar.Source is ContainerImageReference cir)
             {
                 defaultValue = await ((IValueProvider)cir).GetValueAsync(context.CancellationToken).ConfigureAwait(false);
             }
+            else if (envVar.Source is IValueProvider vp)
+            {
+                defaultValue = await vp.GetValueAsync(context.CancellationToken).ConfigureAwait(false);
+            }

This works, but the ContainerImageReference branch becomes dead weight — it does the same thing the fallback would do, and requires a comment explaining why the else is there to prevent double-resolution. Collapsing it into the fallback is strictly simpler.

Collapse both branches into a single IValueProvider check
Removing the ParameterResource branch entirely would produce the shortest code, but it loses the ??= guard: the parameter would always be resolved even when a static default is already set. That is a behavioral regression for existing callers.

-            if (envVar.Source is ParameterResource parameter)
-            {
-                defaultValue ??= await parameter.GetValueAsync(context.CancellationToken).ConfigureAwait(false);
-            }
-            else if (envVar.Source is IValueProvider vp)
+            if (envVar.Source is IValueProvider vp)
             {
                 defaultValue = await vp.GetValueAsync(context.CancellationToken).ConfigureAwait(false);
             }

Change Source from object? to IValueProvider?
A type-safe property would eliminate the runtime pattern-matching entirely, but ContainerMountAnnotation and ContainerPortReference are also valid Source values and do not implement IValueProvider. Moving them to a separate property would be a public API break with no benefit over the current fix.

-    [AspireUnion(typeof(ParameterResource), typeof(ContainerMountAnnotation), typeof(ContainerImageReference), typeof(ContainerPortReference))]
-    public object? Source { get; set; }
+    [AspireUnion(typeof(ParameterResource), typeof(ContainerImageReference))]
+    public IValueProvider? Source { get; set; }

Make ConfigureEnvFile async
The ConfigureEnvFile callback is synchronous, so callers cannot await their own value resolution. Changing its type would let any caller handle arbitrary sources asynchronously — but this pushes resolution responsibility out of the framework and onto every caller, and is a breaking change to the internal API.

-internal Action<IDictionary<string, CapturedEnvironmentVariable>>? ConfigureEnvFile { get; set; }
+internal Func<IDictionary<string, CapturedEnvironmentVariable>, CancellationToken, Task>? ConfigureEnvFile { get; set; }

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
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
  • No

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

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

Or

• Run remotely in PowerShell:

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

[davidfowl]

PR Testing Report

Result: Passed - PR #17471 verified successfully.

Version Verified

• PR head: a1bea22dc551f67a5b05107faf2f8a541f481e71
• Tested CLI: 13.4.0-pr.17471.ga1bea22d
• Execution target: Local isolated PR CLI install

Scenarios Tested

Scenario	Status	Notes
Arbitrary IValueProvider source in Docker Compose env file generation	Passed	.env.Production used the provider-resolved value instead of a static fallback.
ParameterResource with explicit static default	Passed	Static default was preserved and the parameter was not resolved.
Existing container image reference behavior	Passed	Docker Compose image placeholder still resolved through the generic IValueProvider path.
Throwing custom value provider	Passed	Publish failed non-zero and surfaced the provider exception.

Overall Result

PR VERIFIED - no issues found in the targeted Docker Compose .env generation scenarios.