Add ConfigureEnvFile support to polyglot Docker app hosts by sebastienros · Pull Request #15819 · microsoft/aspire

sebastienros · 2026-04-02T22:35:05Z

Description

This adds ConfigureEnvFile parity for Docker Compose polyglot AppHosts so generated TypeScript, Python, and Java SDKs can customize captured .env entries the same way the C# surface already can. The main goal is to unblock the TypeScript issue path without widening scope into broader Docker Compose projection work.

The change exports ConfigureEnvFile to ATS, projects CapturedEnvironmentVariable just enough for mutation, and updates the shared ATS/runtime pieces needed for typed Dict/List handles to flow through callback parameters correctly. On top of that, the Docker polyglot validation AppHosts now exercise the env-file callback in TypeScript, Python, and Java, the Java shared runtime now exposes mutable AspireDict accessors needed for that callback shape, and the focused TypeScript publish validation asserts that the generated artifacts/.env output changes.

Fixes #15704

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
  - If yes, did you have an API Review for it?
    - Yes
    - No
  - Did you add <remarks /> and <code /> elements on your triple slash comments?
    - Yes
    - No
- No
Does the change make any security assumptions or guarantees?
- Yes
  - If yes, have you done a threat model and had a security review?
    - Yes
    - No
- No
Does the change require an update in our Aspire docs?
- Yes
  - Link to aspire.dev issue:
    - New issue
- No

github-actions · 2026-04-02T22:35:20Z

🚀 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 -- 15819

Or

Run remotely in PowerShell:

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

Copilot

Pull request overview

Adds ConfigureEnvFile support to Docker Compose polyglot AppHosts (TypeScript/Python/Java) by exporting the C# API to ATS, projecting CapturedEnvironmentVariable for mutation, and extending ATS collection plumbing so typed Dict/List handles work correctly through callback parameters.

Changes:

Export DockerComposeEnvironmentExtensions.ConfigureEnvFile to ATS and project CapturedEnvironmentVariable as a mutable exported handle type (with limited ignored members).
Update ATS collection exports + capability scanning/analyzers/tests to support non-generic IDictionary/IList and typed mutable Dict/List handles.
Extend polyglot validation fixtures and add an E2E publish test asserting .env output is modified by the callback.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/PolyglotAppHosts/Aspire.Hosting.Docker/TypeScript/apphost.ts	Exercises `configureEnvFile` in the TypeScript Docker Compose validation AppHost.
tests/PolyglotAppHosts/Aspire.Hosting.Docker/Python/apphost.py	Exercises `configure_env_file` in the Python Docker Compose validation AppHost.
tests/PolyglotAppHosts/Aspire.Hosting.Docker/Java/AppHost.java	Exercises `configureEnvFile` in the Java Docker Compose validation AppHost.
tests/Aspire.Hosting.RemoteHost.Tests/CapabilityDispatcherTests.cs	Adds coverage ensuring `List.get` / `Dict.get` work for typed mutable collections returned as handles.
tests/Aspire.Hosting.RemoteHost.Tests/AtsCapabilityScannerTests.cs	Validates ATS type mapping for non-generic `IDictionary`/`IList`.
tests/Aspire.Hosting.CodeGeneration.Java.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.java	Updates expected generated Java snapshot for new dict helpers.
tests/Aspire.Hosting.CodeGeneration.Java.Tests/Snapshots/AtsGeneratedAspire.verified.java	Updates expected generated Java snapshot for new dict helpers.
tests/Aspire.Hosting.Analyzers.Tests/AspireExportAnalyzerTests.cs	Ensures analyzer allows non-generic `IDictionary`/`IList` in exported signatures.
tests/Aspire.Cli.EndToEnd.Tests/TypeScriptPublishTests.cs	Adds E2E test asserting `configureEnvFile` mutates published `artifacts/.env`.
src/Aspire.Hosting/Ats/CollectionExports.cs	Switches intrinsic Dict/List capability exports to non-generic collection interfaces to support typed mutable collections.
src/Aspire.Hosting.RemoteHost/AtsCapabilityScanner.cs	Maps non-generic `IDictionary`/`IList` to ATS Dict/List and emits full `AtsTypeRef` metadata.
src/Aspire.Hosting.Integration.Analyzers/AspireExportAnalyzer.cs	Allows non-generic `IDictionary`/`IList` as ATS-compatible collection types.
src/Aspire.Hosting.Docker/DockerComposeEnvironmentExtensions.cs	Exports `configureEnvFile` to ATS for Docker Compose environments.
src/Aspire.Hosting.Docker/CapturedEnvironmentVariable.cs	Exposes env var metadata as an exported handle type with mutable properties for polyglot callbacks.
src/Aspire.Hosting.CodeGeneration.TypeScript/AtsTypeScriptCodeGenerator.cs	Ensures callback parameters that are mutable dictionaries are converted to `AspireDict` wrappers.
src/Aspire.Hosting.CodeGeneration.Java/Resources/Base.java	Adds mutable `AspireDict` accessors needed by the callback shape (get/put/remove/keys/etc.).

src/Aspire.Hosting/Ats/CollectionExports.cs

src/Aspire.Hosting.CodeGeneration.Java/Resources/Base.java

src/Aspire.Hosting.Docker/CapturedEnvironmentVariable.cs

JamesNK

Two minor observations (1 empty catch block concern, 1 unintentional BOM in snapshots). Overall the changes look solid — the NormalizeDictionaryKey approach, the analyzer + scanner extensions for non-generic collections, and the TS code generator refactoring are all clean.

src/Aspire.Hosting/Ats/CollectionExports.cs

tests/Aspire.Hosting.CodeGeneration.Java.Tests/Snapshots/AtsGeneratedAspire.verified.java

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-04-13T16:39:15Z

🎬 CLI E2E Test Recordings — 69 recordings uploaded (commit fbcd76a)

View recordings

Test	Recording
AddPackageInteractiveWhileAppHostRunningDetached	▶️ View Recording
AddPackageWhileAppHostRunningDetached	▶️ View Recording
AgentCommands_AllHelpOutputs_AreCorrect	▶️ View Recording
AgentInitCommand_DefaultSelection_InstallsSkillOnly	▶️ View Recording
AgentInitCommand_MigratesDeprecatedConfig	▶️ View Recording
AllPublishMethodsBuildDockerImages	▶️ View Recording
AspireAddPackageVersionToDirectoryPackagesProps	▶️ View Recording
AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	▶️ View Recording
Banner_DisplayedOnFirstRun	▶️ View Recording
Banner_DisplayedWithExplicitFlag	▶️ View Recording
Banner_NotDisplayedWithNoLogoFlag	▶️ View Recording
CertificatesClean_RemovesCertificates	▶️ View Recording
CertificatesTrust_WithNoCert_CreatesAndTrustsCertificate	▶️ View Recording
CertificatesTrust_WithUntrustedCert_TrustsCertificate	▶️ View Recording
ConfigSetGet_CreatesNestedJsonFormat	▶️ View Recording
CreateAndRunAspireStarterProject	▶️ View Recording
CreateAndRunAspireStarterProjectWithBundle	▶️ View Recording
CreateAndRunEmptyAppHostProject	▶️ View Recording
CreateAndRunJavaEmptyAppHostProject	▶️ View Recording
CreateAndRunJsReactProject	▶️ View Recording
CreateAndRunPythonReactProject	▶️ View Recording
CreateAndRunTypeScriptEmptyAppHostProject	▶️ View Recording
CreateAndRunTypeScriptStarterProject	▶️ View Recording
CreateJavaAppHostWithViteApp	▶️ View Recording
CreateStartAndStopAspireProject	▶️ View Recording
CreateTypeScriptAppHostWithViteApp	▶️ View Recording
DashboardRunWithOtelTracesReturnsNoTraces	▶️ View Recording
DeployK8sBasicApiService	▶️ View Recording
DeployK8sWithGarnet	▶️ View Recording
DeployK8sWithMongoDB	▶️ View Recording
DeployK8sWithMySql	▶️ View Recording
DeployK8sWithPostgres	▶️ View Recording
DeployK8sWithRabbitMQ	▶️ View Recording
DeployK8sWithRedis	▶️ View Recording
DeployK8sWithSqlServer	▶️ View Recording
DeployK8sWithValkey	▶️ View Recording
DeployTypeScriptAppToKubernetes	▶️ View Recording
DescribeCommandResolvesReplicaNames	▶️ View Recording
DescribeCommandShowsRunningResources	▶️ View Recording
DetachFormatJsonProducesValidJson	▶️ View Recording
DoctorCommand_DetectsDeprecatedAgentConfig	▶️ View Recording
DoctorCommand_WithSslCertDir_ShowsTrusted	▶️ View Recording
DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	▶️ View Recording
GlobalMigration_HandlesCommentsAndTrailingCommas	▶️ View Recording
GlobalMigration_HandlesMalformedLegacyJson	▶️ View Recording
GlobalMigration_PreservesAllValueTypes	▶️ View Recording
GlobalMigration_SkipsWhenNewConfigExists	▶️ View Recording
GlobalSettings_MigratedFromLegacyFormat	▶️ View Recording
InitTypeScriptAppHost_AugmentsExistingViteRepoAtRoot	▶️ View Recording
InvalidAppHostPathWithComments_IsHealedOnRun	▶️ View Recording
LegacySettingsMigration_AdjustsRelativeAppHostPath	▶️ View Recording
LogsCommandShowsResourceLogs	▶️ View Recording
PsCommandListsRunningAppHost	▶️ View Recording
PsFormatJsonOutputsOnlyJsonToStdout	▶️ View Recording
PublishWithConfigureEnvFileUpdatesEnvOutput	▶️ View Recording
PublishWithDockerComposeServiceCallbackSucceeds	▶️ View Recording
RestoreGeneratesSdkFiles	▶️ View Recording
RestoreSupportsConfigOnlyHelperPackageAndCrossPackageTypes	▶️ View Recording
RunFromParentDirectory_UsesExistingConfigNearAppHost	▶️ View Recording
SecretCrudOnDotNetAppHost	▶️ View Recording
SecretCrudOnTypeScriptAppHost	▶️ View Recording
StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	▶️ View Recording
StartAndWaitForTypeScriptSqlServerAppHostWithNativeAssets	▶️ View Recording
StopAllAppHostsFromAppHostDirectory	▶️ View Recording
StopAllAppHostsFromUnrelatedDirectory	▶️ View Recording
StopNonInteractiveMultipleAppHostsShowsError	▶️ View Recording
StopNonInteractiveSingleAppHost	▶️ View Recording
StopWithNoRunningAppHostExitsSuccessfully	▶️ View Recording
UnAwaitedChainsCompileWithAutoResolvePromises	▶️ View Recording

_{📹 Recordings uploaded automatically from CI run #24352817074}

* Add ConfigureEnvFile polyglot parity Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix polyglot dict key handling Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Remove redundant AspireExport IDs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Clarify CapturedEnvironmentVariable export scope Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Export env file source union Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix polyglot union codegen Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Restore TypeScript generator handle helper Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address follow-up review comments Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

sebastienros requested review from danegsta and mitchdenny as code owners April 2, 2026 22:35

Copilot AI review requested due to automatic review settings April 2, 2026 22:35

Copilot started reviewing on behalf of sebastienros April 2, 2026 22:36 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

github-actions bot mentioned this pull request Apr 3, 2026

[pull requests] Review required #13834

Open

sebastienros force-pushed the sebros/ts-configureenvfile-parity branch from 3b9a3bd to f34819b Compare April 3, 2026 00:40

davidfowl reviewed Apr 3, 2026

View reviewed changes

src/Aspire.Hosting.Docker/CapturedEnvironmentVariable.cs Outdated Show resolved Hide resolved

davidfowl reviewed Apr 3, 2026

View reviewed changes

src/Aspire.Hosting.Docker/CapturedEnvironmentVariable.cs Show resolved Hide resolved

davidfowl reviewed Apr 3, 2026

View reviewed changes

src/Aspire.Hosting.Docker/CapturedEnvironmentVariable.cs Outdated Show resolved Hide resolved

sebastienros requested review from JamesNK and karolz-ms as code owners April 3, 2026 03:43

sebastienros force-pushed the sebros/ts-configureenvfile-parity branch from d6d7790 to 83a6d12 Compare April 4, 2026 01:35

sebastienros requested a review from eerhardt as a code owner April 4, 2026 01:41

JamesNK approved these changes Apr 5, 2026

View reviewed changes

src/Aspire.Hosting/Ats/CollectionExports.cs Show resolved Hide resolved

tests/Aspire.Hosting.CodeGeneration.Java.Tests/Snapshots/AtsGeneratedAspire.verified.java Outdated Show resolved Hide resolved

sebastienros and others added 8 commits April 13, 2026 08:45

Add ConfigureEnvFile polyglot parity

3aa4c4d

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fix polyglot dict key handling

4531340

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove redundant AspireExport IDs

a2d0b9b

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Clarify CapturedEnvironmentVariable export scope

63b86c4

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Export env file source union

a31cab3

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fix polyglot union codegen

a9c46ae

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Restore TypeScript generator handle helper

f759700

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Address follow-up review comments

fbcd76a

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

sebastienros force-pushed the sebros/ts-configureenvfile-parity branch from b8a1480 to fbcd76a Compare April 13, 2026 15:49

sebastienros enabled auto-merge (squash) April 13, 2026 15:58

sebastienros merged commit 434dcc9 into main Apr 13, 2026
279 checks passed

sebastienros deleted the sebros/ts-configureenvfile-parity branch April 14, 2026 17:31

joperezr added this to the 13.3 milestone Apr 14, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add ConfigureEnvFile support to polyglot Docker app hosts#15819

Add ConfigureEnvFile support to polyglot Docker app hosts#15819
sebastienros merged 8 commits intomainfrom
sebros/ts-configureenvfile-parity

sebastienros commented Apr 2, 2026

Uh oh!

github-actions bot commented Apr 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JamesNK left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Apr 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

sebastienros commented Apr 2, 2026

Description

Checklist

Uh oh!

github-actions bot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JamesNK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Apr 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions bot commented Apr 2, 2026 •

edited

Loading