Consolidate WithEnvironment polyglot exports using AspireUnionAttribute by maddymontaquila · Pull Request #15333 · microsoft/aspire

maddymontaquila · 2026-03-17T20:59:30Z

Summary

Consolidates the separate withEnvironment and withEnvironmentExpression polyglot exports into a single withEnvironment export using [AspireUnion], giving TypeScript AppHost users a cleaner API.

Before (TypeScript)

// Plain string — one method
await api.withEnvironment("KEY", "value");

// Expression — different method name!
const endpoint = await redis.getEndpoint("tcp");
await api.withEnvironmentExpression("REDIS_URL", refExpr`redis://${endpoint}:6379`);

// EndpointReference — not available at all

After (TypeScript)

// All through a single method with union type
await api.withEnvironment("KEY", "value");
await api.withEnvironment("REDIS_URL", refExpr`redis://${endpoint}:6379`);
await api.withEnvironment("SERVICE_URL", endpoint);

Changes

`src/Aspire.Hosting/ResourceBuilderExtensions.cs`

Removed [AspireExport] from the individual WithEnvironment(name, string) and WithEnvironment(name, ReferenceExpression) overloads
Added new consolidated export method using [AspireUnion(typeof(string), typeof(ReferenceExpression), typeof(EndpointReference))] on the value parameter
Also surfaces EndpointReference which was previously not exported to polyglot hosts

`src/Aspire.Hosting.RemoteHost/Ats/AtsMarshaller.cs`

Added object target type handling in ConvertPrimitive — when the target type is object (union parameter), infers the correct .NET type from the JSON value structure (string → string, bool → bool, etc.)
Handles/expressions already resolved correctly before this point in the unmarshalling pipeline

Snapshot updates

HostingContainerResourceCapabilities.verified.txt — withEnvironmentExpression capability removed (folded into withEnvironment)
TwoPassScanningGeneratedAspire.verified.ts — generated TypeScript now shows value: string | ReferenceExpression | EndpointReference union type

Testing

✅ Aspire.Hosting builds clean (0 warnings)
✅ Aspire.Hosting.RemoteHost builds clean
✅ All 56 TypeScript codegen tests pass
✅ All 210 RemoteHost tests pass (marshaller changes)
✅ Hosting tests: 2098/2113 pass (15 failures are pre-existing .NET runtime version issues)

github-actions · 2026-03-17T20:59:40Z

🚀 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/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 15333

Or

Run remotely in PowerShell:

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

Merge the separate withEnvironment (string) and withEnvironmentExpression (ReferenceExpression) polyglot exports into a single withEnvironment export using [AspireUnion] to accept string | ReferenceExpression | EndpointReference. This gives TypeScript AppHost users a single, clean API: await api.withEnvironment('KEY', 'value'); await api.withEnvironment('KEY', refExpr`redis://${endpoint}`); await api.withEnvironment('KEY', endpoint); Instead of requiring separate method names for each value type. Also adds EndpointReference support which was previously unexported, and handles object target type in AtsMarshaller.ConvertPrimitive for correct union parameter deserialization. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…, and IValueProvider fallback - Add IResourceBuilder<ParameterResource> and IResourceBuilder<IResourceWithConnectionString> to the AspireUnion - Add IValueProvider+IManifestExpressionProvider runtime fallback for extensibility (e.g. BicepOutputReference) - Remove withEnvironmentEndpoint separate export (covered by union) - Remove sync withEnvironmentCallback export, rename async to withEnvironmentCallback - Update codegen snapshots Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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

github-actions · 2026-03-18T00:13:56Z

The transient CI rerun workflow requested reruns for the following jobs after analyzing the failed attempt.
GitHub's job rerun API also reruns dependent jobs, so the retry is being tracked in the rerun attempt.
The job links below point to the failed attempt that matched the retry-safe transient failure rules.

Tests / Hosting.MongoDB / Hosting.MongoDB (windows-latest) - Failed step 'Upload logs, and test results | Generate test results summary' will be retried because the job log shows a likely transient infrastructure network failure. Matched pattern: /api.github.com.{0,160}(timed out|failed to connect|failed to respond|could not resolve|ENOTFOUND|ECONNRESET|EPROTO|Bad Gateway|SSL connection could not be established)/i.

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

Copilot

Pull request overview

This PR updates Aspire’s polyglot (ATS) surface for setting environment variables by consolidating multiple exported capabilities into a single withEnvironment overload that accepts a union-typed value, and updates the ATS marshalling logic and generated SDK snapshots accordingly.

Changes:

Replaces per-type withEnvironment* exports (e.g., withEnvironmentExpression, withEnvironmentCallbackAsync) with a unified exported withEnvironment union overload plus a single exported async callback capability.
Updates ATS marshalling to better handle object (union) primitive conversion.
Refreshes multi-language codegen snapshots and updates the TypeScript validation playground to use the new API.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/Aspire.Hosting/ResourceBuilderExtensions.cs	Introduces exported union `withEnvironment` overload; adjusts callback export; removes some prior exports.
src/Aspire.Hosting.RemoteHost/Ats/AtsMarshaller.cs	Adds `object`-target primitive inference for union parameters.
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.ts	Snapshot updates reflecting consolidated `withEnvironment` and callback export changes.
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/HostingContainerResourceCapabilities.verified.txt	Removes capabilities that are no longer exported (`withEnvironmentCallbackAsync`, `withEnvironmentExpression`).
tests/Aspire.Hosting.CodeGeneration.Rust.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.rs	Snapshot updates aligning Rust bindings with consolidated `with_environment`.
tests/Aspire.Hosting.CodeGeneration.Python.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.py	Snapshot updates aligning Python bindings with consolidated `with_environment`.
tests/Aspire.Hosting.CodeGeneration.Java.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.java	Snapshot updates aligning Java bindings with consolidated `withEnvironment`.
tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.go	Snapshot updates aligning Go bindings with consolidated `WithEnvironment`.
playground/polyglot/TypeScript/Aspire.Hosting/ValidationAppHost/apphost.ts	Updates sample usage to call the unified `withEnvironment` overload.
playground/polyglot/TypeScript/Aspire.Hosting.SqlServer/aspire.config.json	Adds config for the TypeScript SqlServer polyglot playground.

src/Aspire.Hosting/ResourceBuilderExtensions.cs

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

src/Aspire.Hosting/ResourceBuilderExtensions.cs

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

src/Aspire.Hosting/ResourceBuilderExtensions.cs

sebastienros · 2026-03-18T14:43:35Z

Verified locally

const container1 = await builder.addContainer("mycontainer1", "nginx");

const container2 = await builder.addContainer("mycontainer2", "nginx");

const configParam = await builder.addParameterFromConfiguration("myconfig", "MyConfig:Key");

await container2.withHttpEndpoint({ name: "http", targetPort: 80 });
const endpoint = await container2.getEndpoint("http");
const expr = refExpr`Host=${endpoint}`;
const envConnectionString = await builder.addConnectionString("envcs");

// withEnvironment — with EndpointReference
await container1.withEnvironment("MY_ENDPOINT", endpoint);

// withEnvironment — with ReferenceExpression
await container1.withEnvironment("MY_EXPR", expr);

// withEnvironment — with ParameterResource
await container1.withEnvironment("MY_PARAM", configParam);

// withEnvironment — with connection string resource
await container1.withEnvironment("MY_CONN", envConnectionString);

src/Aspire.Hosting/ResourceBuilderExtensions.cs

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

github-actions · 2026-03-18T17:20:46Z

🎬 CLI E2E Test Recordings — 52 recordings uploaded (commit fdc3343)

View recordings

Test	Recording
AddPackageInteractiveWhileAppHostRunningDetached	▶️ View Recording
AddPackageWhileAppHostRunningDetached	▶️ View Recording
AgentCommands_AllHelpOutputs_AreCorrect	▶️ View Recording
AgentInitCommand_DefaultSelection_InstallsSkillOnly	▶️ View Recording
AgentInitCommand_MigratesDeprecatedConfig	▶️ View Recording
AspireAddPackageVersionToDirectoryPackagesProps	▶️ View Recording
AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	▶️ View Recording
Banner_DisplayedOnFirstRun	▶️ View Recording
Banner_DisplayedWithExplicitFlag	▶️ View Recording
CertificatesClean_RemovesCertificates	▶️ View Recording
CertificatesTrust_WithNoCert_CreatesAndTrustsCertificate	▶️ View Recording
CertificatesTrust_WithUntrustedCert_TrustsCertificate	▶️ View Recording
ConfigSetGet_CreatesNestedJsonFormat	▶️ View Recording
CreateAndDeployToDockerCompose	▶️ View Recording
CreateAndDeployToDockerComposeInteractive	▶️ View Recording
CreateAndPublishToKubernetes	▶️ View Recording
CreateAndRunAspireStarterProject	▶️ View Recording
CreateAndRunAspireStarterProjectWithBundle	▶️ View Recording
CreateAndRunEmptyAppHostProject	▶️ View Recording
CreateAndRunJsReactProject	▶️ View Recording
CreateAndRunPythonReactProject	▶️ View Recording
CreateAndRunTypeScriptEmptyAppHostProject	▶️ View Recording
CreateAndRunTypeScriptStarterProject	▶️ View Recording
CreateStartAndStopAspireProject	▶️ View Recording
CreateTypeScriptAppHostWithViteApp	▶️ 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
InvalidAppHostPathWithComments_IsHealedOnRun	▶️ View Recording
LogsCommandShowsResourceLogs	▶️ View Recording
PsCommandListsRunningAppHost	▶️ View Recording
PsFormatJsonOutputsOnlyJsonToStdout	▶️ View Recording
PublishWithDockerComposeServiceCallbackSucceeds	▶️ View Recording
RestoreGeneratesSdkFiles	▶️ View Recording
RunWithMissingAwaitShowsHelpfulError	▶️ View Recording
SecretCrudOnDotNetAppHost	▶️ View Recording
SecretCrudOnTypeScriptAppHost	▶️ View Recording
StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	▶️ View Recording
StopAllAppHostsFromAppHostDirectory	▶️ View Recording
StopAllAppHostsFromUnrelatedDirectory	▶️ View Recording
StopNonInteractiveMultipleAppHostsShowsError	▶️ View Recording
StopNonInteractiveSingleAppHost	▶️ View Recording
StopWithNoRunningAppHostExitsSuccessfully	▶️ View Recording
TypeScriptAppHostWithProjectReferenceIntegration	▶️ View Recording

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

joperezr · 2026-03-18T18:21:35Z

src/Aspire.Hosting.RemoteHost/Ats/AtsMarshaller.cs

+            {
+                return d;
+            }
+            return value.ToJsonString();


hmm not sure I follow here. Should this be throw new ArgumentException() or something like that?

…te (#15333) * Consolidate WithEnvironment exports using AspireUnionAttribute Merge the separate withEnvironment (string) and withEnvironmentExpression (ReferenceExpression) polyglot exports into a single withEnvironment export using [AspireUnion] to accept string | ReferenceExpression | EndpointReference. This gives TypeScript AppHost users a single, clean API: await api.withEnvironment('KEY', 'value'); await api.withEnvironment('KEY', refExpr`redis://${endpoint}`); await api.withEnvironment('KEY', endpoint); Instead of requiring separate method names for each value type. Also adds EndpointReference support which was previously unexported, and handles object target type in AtsMarshaller.ConvertPrimitive for correct union parameter deserialization. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Expand WithEnvironment union with ParameterResource, ConnectionString, and IValueProvider fallback - Add IResourceBuilder<ParameterResource> and IResourceBuilder<IResourceWithConnectionString> to the AspireUnion - Add IValueProvider+IManifestExpressionProvider runtime fallback for extensibility (e.g. BicepOutputReference) - Remove withEnvironmentEndpoint separate export (covered by union) - Remove sync withEnvironmentCallback export, rename async to withEnvironmentCallback - Update codegen snapshots Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update TypeScript apphost environment usage Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Refresh polyglot codegen snapshots Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add ReferenceExpression apphost coverage Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix TypeScript polyglot validation apphost Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Make WithEnvironment union overload internal Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address WithEnvironment review feedback Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: David Fowler <davidfowl@gmail.com> Co-authored-by: Sebastien Ros <sebastienros@gmail.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

sebastienros changed the base branch from main to release/13.2 March 17, 2026 23:06

sebastienros force-pushed the consolidate-withenvironment-union branch from 8f77857 to 2ea73e3 Compare March 17, 2026 23:08

maddymontaquila and others added 5 commits March 17, 2026 16:37

Update TypeScript apphost environment usage

cf569db

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

Refresh polyglot codegen snapshots

9317213

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

Add ReferenceExpression apphost coverage

389967d

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

sebastienros force-pushed the consolidate-withenvironment-union branch from 8916f49 to 389967d Compare March 17, 2026 23:39

Fix TypeScript polyglot validation apphost

ab9d514

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

sebastienros marked this pull request as ready for review March 18, 2026 00:35

Copilot AI review requested due to automatic review settings March 18, 2026 00:35

Copilot started reviewing on behalf of sebastienros March 18, 2026 00:36 View session

Copilot AI reviewed Mar 18, 2026

View reviewed changes

src/Aspire.Hosting/ResourceBuilderExtensions.cs Show resolved Hide resolved

src/Aspire.Hosting/ResourceBuilderExtensions.cs Outdated Show resolved Hide resolved

src/Aspire.Hosting/ResourceBuilderExtensions.cs Outdated Show resolved Hide resolved

sebastienros and others added 2 commits March 17, 2026 17:57

Potential fix for pull request finding

61ea248

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

d80d30b

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

JamesNK reviewed Mar 18, 2026

View reviewed changes

src/Aspire.Hosting/ResourceBuilderExtensions.cs Outdated Show resolved Hide resolved

Make WithEnvironment union overload internal

a17c905

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

JamesNK approved these changes Mar 18, 2026

View reviewed changes

src/Aspire.Hosting/ResourceBuilderExtensions.cs Show resolved Hide resolved

github-actions bot mentioned this pull request Mar 18, 2026

[13.2-burndown] Daily Burndown Report - March 18, 2026 #15351

Closed

davidfowl approved these changes Mar 18, 2026

View reviewed changes

sebastienros added the Servicing-consider Issue for next servicing release review label Mar 18, 2026

eerhardt reviewed Mar 18, 2026

View reviewed changes

src/Aspire.Hosting/ResourceBuilderExtensions.cs Show resolved Hide resolved

eerhardt reviewed Mar 18, 2026

View reviewed changes

src/Aspire.Hosting/ResourceBuilderExtensions.cs Outdated Show resolved Hide resolved

Address WithEnvironment review feedback

fdc3343

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

joperezr removed the Servicing-consider Issue for next servicing release review label Mar 18, 2026

joperezr reviewed Mar 18, 2026

View reviewed changes

joperezr approved these changes Mar 18, 2026

View reviewed changes

joperezr added the Servicing-approved Approved for servicing release label Mar 18, 2026

joperezr merged commit c25c645 into release/13.2 Mar 18, 2026
504 of 507 checks passed

joperezr deleted the consolidate-withenvironment-union branch March 18, 2026 19:59

dotnet-policy-service bot added this to the 13.2 milestone Mar 18, 2026

github-actions bot mentioned this pull request Mar 19, 2026

[13.2-burndown] Daily Burndown Report - March 19, 2026 #15384

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Consolidate WithEnvironment polyglot exports using AspireUnionAttribute#15333

Consolidate WithEnvironment polyglot exports using AspireUnionAttribute#15333
joperezr merged 10 commits intorelease/13.2from
consolidate-withenvironment-union

maddymontaquila commented Mar 17, 2026

Uh oh!

github-actions bot commented Mar 17, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 18, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sebastienros commented Mar 18, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Mar 18, 2026

Uh oh!

joperezr Mar 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Conversation

maddymontaquila commented Mar 17, 2026

Summary

Before (TypeScript)

After (TypeScript)

Changes

src/Aspire.Hosting/ResourceBuilderExtensions.cs

src/Aspire.Hosting.RemoteHost/Ats/AtsMarshaller.cs

Snapshot updates

Testing

Uh oh!

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

Uh oh!

Uh oh!

github-actions bot commented Mar 18, 2026

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!

sebastienros commented Mar 18, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Mar 18, 2026

Uh oh!

joperezr Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

`src/Aspire.Hosting/ResourceBuilderExtensions.cs`

`src/Aspire.Hosting.RemoteHost/Ats/AtsMarshaller.cs`

github-actions bot commented Mar 17, 2026 •

edited

Loading