Adopt an ATS-first API design for Aspire.Hosting exported capabilities

[sebastienros]

Summary

• adopt an ATS-first exported capability surface for Aspire.Hosting without breaking the public C# API
• consolidate ATS-facing shapes around addProject, addConnectionString, withUrl, and ATS-only internal editors/facades
• align TypeScript getter-only members with Java-style method calls and refresh snapshots/polyglot validation apphosts

Fixes #16243

[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 -- 16403

Or

• Run remotely in PowerShell:

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

[github-actions]

Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
GitHub was asked to rerun all failed jobs for that attempt, and the rerun is being tracked in the rerun attempt.
The job links below point to the failed attempt jobs that matched the retry-safe transient failure rules.

• Tests / Hosting-1 / Hosting-1 (windows-latest) - Job-level runner or infrastructure failure matched the transient allowlist.

[Copilot]

Pull request overview

This PR reshapes the Aspire.Hosting exported capability surface to be ATS-first (designed from the polyglot API outward) while keeping the public C# API intact. It consolidates several overload families into unified exports (addProject, addConnectionString, withUrl) and introduces ATS-focused editors/facades for callback contexts (env/args/urls/pipeline/logging), then updates polyglot validation apphosts and codegen snapshots accordingly.

Changes:

• Unify exported capabilities around addProject (optional launch profile), addConnectionString (options-style), and withUrl (string | ReferenceExpression).
• Replace projected “property-bag” callback surfaces with explicit ATS editor/facade types (e.g., EnvironmentEditor, CommandLineArgsEditor, ResourceUrlsEditor, PipelineEditor, LogFacade).
• Update TypeScript generator to emit getter-only members as zero-argument async methods (and refresh snapshots + polyglot validation apphosts across languages).

Reviewed changes

Copilot reviewed 66 out of 69 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/PolyglotAppHosts/Aspire.Hosting/TypeScript/apphost.ts	Updates TS validation apphost to use unified/ATS-first shapes (methods vs .get(), editors, unified APIs).
tests/PolyglotAppHosts/Aspire.Hosting/Python/apphost.py	Updates Python validation apphost to match unified add_project, add_connection_string, and callback editors.
tests/PolyglotAppHosts/Aspire.Hosting/Java/AppHost.java	Updates Java validation apphost for new pipeline/log/url/env callback shapes.
tests/PolyglotAppHosts/Aspire.Hosting.Yarp/TypeScript/apphost.ts	Moves YARP TS apphost to addProject(..., { launchProfileName }).
tests/PolyglotAppHosts/Aspire.Hosting.Yarp/Python/apphost.py	Moves YARP Python apphost to launch_profile_name= usage.
tests/PolyglotAppHosts/Aspire.Hosting.Valkey/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.SqlServer/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Seq/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Redis/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.RabbitMQ/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Qdrant/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.PostgreSQL/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Orleans/Python/apphost.py	Updates add_connection_string call to env-var-name options form.
tests/PolyglotAppHosts/Aspire.Hosting.Orleans/Java/AppHost.java	Updates addConnectionString call to options-object form.
tests/PolyglotAppHosts/Aspire.Hosting.Oracle/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Nats/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.MySql/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.MongoDB/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Milvus/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Kubernetes/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Keycloak/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Kafka/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Garnet/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Foundry/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Foundry/Python/apphost.py	Moves Foundry add_project usage to launch_profile_name= form.
tests/PolyglotAppHosts/Aspire.Hosting.Docker/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Azure/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Azure/Python/apphost.py	Updates connection string creation to options/env-var-name form.
tests/PolyglotAppHosts/Aspire.Hosting.Azure/Java/AppHost.java	Updates addConnectionString call to options-object form.
tests/PolyglotAppHosts/Aspire.Hosting.Azure.Sql/TypeScript/apphost.ts	Updates exposed property access and collection retrieval patterns.
tests/PolyglotAppHosts/Aspire.Hosting.Azure.ServiceBus/TypeScript/apphost.ts	Updates projected list access to method-based retrieval for rules.
tests/PolyglotAppHosts/Aspire.Hosting.Azure.Redis/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Azure.OperationalInsights/Java/AppHost.java	Updates withUrl call shape to include displayText arg.
tests/PolyglotAppHosts/Aspire.Hosting.Azure.Kusto/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Azure.EventHubs/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Azure.CognitiveServices/TypeScript/apphost.ts	Switches exposed property access from .get() to zero-arg async methods.
tests/PolyglotAppHosts/Aspire.Hosting.Azure.AppService/TypeScript/apphost.ts	Moves addProject usage to options-object launch profile form.
tests/PolyglotAppHosts/Aspire.Hosting.Azure.AppService/Python/apphost.py	Moves add_project usage to launch_profile_name= form.
tests/Aspire.Hosting.RemoteHost.Tests/CapabilityDispatcherTests.cs	Updates capability registration expectations for ATS-facing members.
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/TestTypes/TestTypes.cs	Adds a mutable-collection exported test type to validate codegen behavior.
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/HostingContainerResourceCapabilities.verified.txt	Updates capability snapshot (e.g., removal of withUrlExpression).
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/AtsGeneratedAspire.verified.ts	Updates TS snapshot for getter-only-method generation and new test types.
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/AtsTypeScriptCodeGeneratorTests.cs	Updates/extends tests to validate getter-only methods vs mutable property accessors.
tests/Aspire.Hosting.CodeGeneration.Rust.Tests/Snapshots/AtsGeneratedAspire.verified.rs	Updates Rust snapshot for new exported types / mutable collection behavior.
tests/Aspire.Hosting.CodeGeneration.Python.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.py	Updates Python snapshot for unified add_connection_string, editors/facades, and with_url union.
tests/Aspire.Hosting.CodeGeneration.Python.Tests/Snapshots/AtsGeneratedAspire.verified.py	Updates Python snapshot for new exported types and dict/list handle wrappers.
tests/Aspire.Hosting.CodeGeneration.Java.Tests/Snapshots/AtsGeneratedAspire.verified.java	Updates Java snapshot for new exported types and handle registrations.
tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/AtsGeneratedAspire.verified.go	Updates Go snapshot for new exported types and handle registrations.
src/Aspire.Hosting/ResourceBuilderExtensions.cs	Removes/ignores obsolete exports and adds internal unified withUrl dispatcher export.
src/Aspire.Hosting/ProjectResourceBuilderExtensions.cs	Makes launchProfileName optional for AddProject and ignores polyglot-specific overload export.
src/Aspire.Hosting/Pipelines/PipelineStep.cs	Moves away from ExposeProperties, exports explicit pipeline step members, adds AddTag.
src/Aspire.Hosting/Pipelines/PipelineEditor.cs	Introduces ATS-first pipeline editor for step enumeration and tag filtering.
src/Aspire.Hosting/Pipelines/PipelineConfigurationContext.cs	Replaces property-bag export with pipeline() and log() ATS-first facades.
src/Aspire.Hosting/Pipelines/DistributedApplicationPipeline.cs	Wires logger into configuration context for polyglot logging facade.
src/Aspire.Hosting/ParameterResourceBuilderExtensions.cs	Stops exporting the older AddConnectionString projection entrypoint.
src/Aspire.Hosting/ConnectionStringBuilderExtensions.cs	Introduces exported addConnectionString ATS-first dispatcher (env var / expression / build).
src/Aspire.Hosting/ApplicationModel/ResourceUrlsEditor.cs	Adds ATS-first URL editor with unified add(url) surface.
src/Aspire.Hosting/ApplicationModel/ResourceUrlsCallbackContext.cs	Exports urls() editor + log() facade and adds ATS-friendly member exports.
src/Aspire.Hosting/ApplicationModel/LogFacade.cs	Adds narrow polyglot logging facade (info/warning/error/debug).
src/Aspire.Hosting/ApplicationModel/EnvironmentEditor.cs	Adds ATS-first environment variable editor with set(name, value) union.
src/Aspire.Hosting/ApplicationModel/EnvironmentCallbackContext.cs	Exports environment() editor + log() facade; drops ExposeProperties export.
src/Aspire.Hosting/ApplicationModel/CommandLineArgsEditor.cs	Adds ATS-first command-line args editor with add(value) union.
src/Aspire.Hosting/ApplicationModel/CommandLineArgsCallbackAnnotation.cs	Exports args() editor + log() facade; reshapes exported execution context member.
src/Aspire.Hosting.RemoteHost/AtsCapabilityScanner.cs	Adds MethodName overrides and changes property getter/setter capability generation.
src/Aspire.Hosting.CodeGeneration.TypeScript/AtsTypeScriptCodeGenerator.cs	Emits getter-only properties as async zero-arg methods and updates thenable/promise wrappers accordingly.

[github-actions]

Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
GitHub was asked to rerun all failed jobs for that attempt, and the rerun is being tracked in the rerun attempt.
The job links below point to the failed attempt jobs that matched the retry-safe transient failure rules.

• Tests / Hosting-1 / Hosting-1 (windows-latest) - Job-level runner or infrastructure failure matched the transient allowlist.

[github-actions]

🎬 CLI E2E Test Recordings — 75 recordings uploaded (commit baaa86c)

View all recordings

Status	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
❔	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
❔	CreateTypeScriptAppHostWithViteApp_UsesConfiguredToolchain	▶️ 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
❔	DetachFormatJsonProducesValidJsonWhenRestartingExistingInstance	▶️ View Recording
❔	DoListStepsShowsPipelineSteps	▶️ View Recording
❔	DocsCommand_RendersInteractiveMarkdownFromLocalSource	▶️ View Recording
❔	DoctorCommand_DetectsDeprecatedAgentConfig	▶️ View Recording
❔	DoctorCommand_TypeScriptAppHostReportsMissingConfiguredToolchain	▶️ 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
❔	OtelLogsReturnsStructuredLogsFromStarterAppCore	▶️ View Recording
❔	PsCommandListsRunningAppHost	▶️ View Recording
❔	PsFormatJsonOutputsOnlyJsonToStdout	▶️ View Recording
❔	PublishWithConfigureEnvFileUpdatesEnvOutput	▶️ View Recording
❔	PublishWithDockerComposeServiceCallbackSucceeds	▶️ View Recording
❔	PublishWithoutOutputPathUsesAppHostDirectoryDefault	▶️ View Recording
❔	RestoreGeneratesSdkFiles	▶️ View Recording
❔	RestoreGeneratesSdkFiles_WithConfiguredToolchain	▶️ View Recording
❔	RestoreRefreshesGeneratedSdkAfterAddingIntegration	▶️ 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 #24918366055}