Fix guest AppHost Ctrl+C shutdown

[danegsta]

Description

aspire run could race graceful shutdown for guest AppHosts: cancellation stopped the CLI wait immediately and the guest launcher could force-kill the guest process tree before the process handled Ctrl+C/Ctrl+Break. On Windows, the AppHost server also needs different fallback behavior from the guest because DCP is in the server process tree and should not be killed by server fallback cleanup.

This change launches guest AppHost processes and AppHost servers in Windows process groups, adds a ProcessShutdownService process-group shutdown path that sends CTRL_BREAK_EVENT, and routes guest/server cancellation through the shared graceful-then-force shutdown flow. Guest fallback still kills the whole process tree. Server fallback kills the whole tree on Unix, but only the target server process on Windows so in-tree DCP can keep handling cleanup.

User-facing behavior

Pressing Ctrl+C during aspire run for guest AppHosts now gives the guest and AppHost server a graceful shutdown window before force termination, aligning the run path with the existing shutdown coordinator behavior.

Validation:

• dotnet test --project tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.ProcessGuestLauncherTests" --filter-class "*.ProcessShutdownServiceTests" --filter-class "*.AppHostServerSessionTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"

Fixes # (issue)

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

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

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

This PR fixes a Ctrl+C shutdown race for guest AppHosts in aspire run by ensuring cancellation follows a graceful-then-force termination flow (instead of immediately force-killing), and by adding a Windows process-group shutdown path that uses CTRL_BREAK_EVENT. It also adjusts Windows fallback behavior for AppHost servers to avoid tearing down in-tree DCP during server cleanup.

Changes:

• Launch guest AppHosts and AppHost server processes in Windows process groups, enabling targeted CTRL_BREAK_EVENT shutdown.
• Add process-group graceful shutdown support to ProcessShutdownService/ProcessSignaler, and route guest/server cancellation through the coordinated graceful-then-force flow.
• Add/adjust tests to validate Unix SIGTERM graceful behavior and Windows CTRL_BREAK_EVENT behavior.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/Aspire.Cli.Tests/Projects/ProcessGuestLauncherTests.cs	Adds coverage for cancellation-driven graceful shutdown on Unix and Windows (process-group Ctrl+Break).
tests/Aspire.Cli.Tests/Projects/GuestAppHostProjectTests.cs	Wires a ProcessShutdownService into test project construction to match updated runtime requirements.
src/Shared/ProcessSignaler.cs	Adds a process-group graceful shutdown API and Windows GenerateConsoleCtrlEvent(CTRL_BREAK_EVENT) support.
src/Aspire.Cli/Projects/ProcessGuestLauncher.cs	Starts guest processes in a Windows process group and uses coordinated graceful-then-force shutdown on cancellation.
src/Aspire.Cli/Projects/PrebuiltAppHostServer.cs	Starts the AppHost server process in a Windows process group.
src/Aspire.Cli/Projects/GuestRuntime.cs	Plumbs an optional ProcessShutdownService through to the default guest launcher.
src/Aspire.Cli/Projects/GuestAppHostProject.cs	Requires and threads ProcessShutdownService through guest runtime and server session startup paths.
src/Aspire.Cli/Projects/DotNetBasedAppHostServerProject.cs	Starts the dotnet-based AppHost server in a Windows process group.
src/Aspire.Cli/Projects/AppHostServerSession.cs	Adds optional coordinated shutdown for the server process; adjusts Windows fallback kill semantics.
src/Aspire.Cli/Processes/ProcessShutdownService.cs	Introduces process-group shutdown flow and makes force-kill scope (tree vs single process) configurable per call.

[danegsta]

PR Testing Report

PR Information

• PR Number: Fix guest AppHost Ctrl+C shutdown #17642
• Title: Fix guest AppHost Ctrl+C shutdown
• Head Commit: 0584470
• Tested At: 2026-05-29T02:14:23Z

CLI Version Verification

• Expected Commit: 0584470
• Installed Version: 13.5.0-pr.17642.g05844707
• Status: Verified - installed version includes short SHA g05844707

Changes Analyzed

Files Changed

• src/Aspire.Cli/Processes/ProcessShutdownService.cs - process-group shutdown and force-kill fallback coordination
• src/Aspire.Cli/Projects/AppHostServerSession.cs - graceful server disposal path and Windows target-only fallback
• src/Aspire.Cli/Projects/DotNetBasedAppHostServerProject.cs - Windows process-group launch for SDK-mode server
• src/Aspire.Cli/Projects/GuestAppHostProject.cs - passes shutdown coordinator to server and guest runtime
• src/Aspire.Cli/Projects/GuestRuntime.cs - passes shutdown coordinator to process guest launcher
• src/Aspire.Cli/Projects/PrebuiltAppHostServer.cs - Windows process-group launch for prebuilt server
• src/Aspire.Cli/Projects/ProcessGuestLauncher.cs - guest process-group launch and graceful shutdown before force-kill fallback
• src/Shared/ProcessSignaler.cs - CTRL_BREAK_EVENT process-group signaling on Windows
• tests/Aspire.Cli.Tests/Projects/GuestAppHostProjectTests.cs - updated test construction
• tests/Aspire.Cli.Tests/Projects/ProcessGuestLauncherTests.cs - Unix and Windows process-shutdown behavior coverage

Change Categories

• CLI changes detected
• Hosting integration changes
• Dashboard changes
• Template changes
• Client/Component changes
• Test changes

Test Scenarios Executed

Scenario 1: PR CLI install and version verification

Objective: Install the PR dogfood CLI and verify it matches the PR head commit.
Coverage Type: Happy path
Status: Passed

Steps:

1. Installed PR Fix guest AppHost Ctrl+C shutdown #17642 CLI using the dogfood shell command with isolated --install-path, --skip-path, and --skip-extension.
2. Ran the installed binary directly with --version.
3. Compared the version output with the PR head commit.

Evidence:

• Install log: /var/folders/97/44fp_02d4kd90s9p6sy_jwgh0000gn/T/aspire-pr-test.liF9xI1WNv/install.log
• Install info: /var/folders/97/44fp_02d4kd90s9p6sy_jwgh0000gn/T/aspire-pr-test.liF9xI1WNv/install-info.txt

Observations:

• Installed CLI version: 13.5.0-pr.17642.g05844707
• Version includes the expected short SHA g05844707.

---

Scenario 2: Template smoke test

Objective: Verify the PR CLI can acquire templates from the PR hive and create a fresh project non-interactively.
Coverage Type: Happy path
Status: Passed

Steps:

1. Created a fresh aspire-starter app using --source pointed at the PR hive and --version set to the installed CLI version.
2. Used non-interactive prompt-suppression flags including --test-framework None, --use-redis-cache false, --localhost-tld false, and --suppress-agent-init.
3. Captured generated file list.

Evidence:

• Output: /var/folders/97/44fp_02d4kd90s9p6sy_jwgh0000gn/T/aspire-pr-test.liF9xI1WNv/scenario-template-smoke/new-output.txt
• Generated files: /var/folders/97/44fp_02d4kd90s9p6sy_jwgh0000gn/T/aspire-pr-test.liF9xI1WNv/scenario-template-smoke/generated-files.txt

Observations:

• Project creation completed successfully.
• Generated AppHost, ApiService, ServiceDefaults, Web, solution, and Aspire config files.

---

Scenario 3: TypeScript guest AppHost shutdown on macOS

Objective: Exercise the changed guest AppHost run/shutdown path with a fresh TypeScript AppHost and verify SIGINT-triggered shutdown exits cleanly.
Coverage Type: Happy path / platform shutdown behavior
Status: Passed

Steps:

1. Created a fresh aspire-ts-empty project using the PR hive and installed version.
2. Ran aspire run --apphost <apphost.mts> --non-interactive --nologo with the PR CLI.
3. Waited until startup reached a detectable AppHost state.
4. Sent SIGINT to the running PR CLI process.
5. Verified aspire run exited with code 0.

Evidence:

• Project creation output: /var/folders/97/44fp_02d4kd90s9p6sy_jwgh0000gn/T/aspire-pr-test.liF9xI1WNv/scenario-ts-guest-shutdown/new-output.txt
• Run output: /var/folders/97/44fp_02d4kd90s9p6sy_jwgh0000gn/T/aspire-pr-test.liF9xI1WNv/scenario-ts-guest-shutdown/run-output.txt
• Exit code: /var/folders/97/44fp_02d4kd90s9p6sy_jwgh0000gn/T/aspire-pr-test.liF9xI1WNv/scenario-ts-guest-shutdown/run-exit-code.txt

Observations:

• Startup reached the AppHost connection phase.
• Shutdown output included Stopping Aspire..
• Process exited successfully with code 0 after SIGINT.
• Windows CTRL_BREAK_EVENT behavior is covered by the Windows-only test in the PR and was not executed on this macOS host.

---

Scenario 4: Missing AppHost path

Objective: Verify a bad --apphost path fails safely without prompting or hanging.
Coverage Type: Unhappy path
Status: Passed

Steps:

1. Ran aspire describe --apphost <missing path> --non-interactive with the PR CLI.
2. Captured output and exit code.

Evidence:

• Output: /var/folders/97/44fp_02d4kd90s9p6sy_jwgh0000gn/T/aspire-pr-test.liF9xI1WNv/scenario-negative-apphost/describe-output.txt
• Exit code: /var/folders/97/44fp_02d4kd90s9p6sy_jwgh0000gn/T/aspire-pr-test.liF9xI1WNv/scenario-negative-apphost/exit-code.txt

Expected Unhappy-Path Outcome: A non-zero exit code with a clear error that the AppHost project does not exist.

Observations:

• Command exited with code 7.
• Output included: The --apphost option specified a project that does not exist.

Summary

Scenario	Status	Notes
PR CLI install and version verification	Passed	Version matched PR head short SHA
Template smoke test	Passed	Fresh starter project created from PR hive
TypeScript guest AppHost shutdown on macOS	Passed	SIGINT shutdown exited with code 0
Missing AppHost path	Passed	Failed safely with clear error and exit code 7

Overall Result

PR VERIFIED

Recommendations

• For full platform confidence, also run the Windows-only test or an equivalent Windows manual scenario because the CTRL_BREAK_EVENT path cannot be exercised from this macOS host.

[JamesNK]

I think StopProcessGroupAsync, and this, plus WaitForDrainAsync needs a timeout.

Basically, after the CT is raised, there should be 3 seconds to do clean up before an OCE is thrown out of the method.

[mitchdenny]

One inline comment on the Windows CTRL_BREAK test.

[github-actions]

❓ CLI E2E Tests unknown — 107 passed, 0 failed, 2 unknown (commit 2d94bd6)

View all recordings

Status	Test	Recording	Job	Artifacts
✅	AddPackageInteractiveWhileAppHostRunningDetached	Recording	#78435201470	Logs
✅	AddPackageWhileAppHostRunningDetached	Recording	#78435201470	Logs
✅	AgentCommands_AllHelpOutputs_AreCorrect	Recording	#78435201582	Logs
✅	AgentInitCommand_DefaultSelection_InstallsDefaultSkills	Recording	#78435201582	Logs
✅	AgentInitCommand_MigratesDeprecatedConfig	Recording	#78435201582	Logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp	Recording	#78435201502	Logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp_DevLocalhost	Recording	#78435201502	Logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp_Isolated	Recording	#78435201502	Logs
✅	AllPublishMethodsBuildDockerImages	Recording	#78435201463	Logs
✅	AspireAddAndStartWorkAgainstLegacyAppHostTs	Recording	#78435201686	Logs
✅	AspireAddPackageVersionToDirectoryPackagesProps	Recording	#78435201458	Logs
✅	AspireInitSingleFileAppHostRunsViaDotnetRunAppHost	Recording	#78435201466	Logs
✅	AspireInitWithExistingAppHostDirRecreatesMissingNuGetConfigAndPreservesFiles	Recording	#78435201719	Logs
❔	AspireInitWithSolutionFileGeneratesAppHostThatBuildsAgainstChannelHive	Recording	#78435201719	Logs
✅	AspireStartUpdatesStaleTypeScriptAppHostPath	Recording	#78435201756	Logs
✅	AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	Recording	#78435201458	Logs
✅	AspireUpdateRemovesOrphanAppHostPackageVersionWhenSdkAlreadyCurrent	Recording	#78435201458	Logs
✅	Banner_DisplayedOnFirstRun	Recording	#78435201705	Logs
✅	Banner_DisplayedWithExplicitFlag	Recording	#78435201705	Logs
✅	Banner_NotDisplayedWithNoLogoFlag	Recording	#78435201705	Logs
✅	CertificatesClean_RemovesCertificates	Recording	#78435201399	Logs
✅	CertificatesTrust_WithNoCert_CreatesAndTrustsCertificate	Recording	#78435201399	Logs
✅	CertificatesTrust_WithUntrustedCert_TrustsCertificate	Recording	#78435201399	Logs
✅	ConfigSetGet_CreatesNestedJsonFormat	Recording	#78435201454	Logs
✅	CreateAndRunAspireStarterProject	Recording	#78435201467	Logs
✅	CreateAndRunAspireStarterProjectWithBundle	Recording	#78435201478	Logs
✅	CreateAndRunEmptyAppHostProject	Recording	#78435201473	Logs
✅	CreateAndRunJavaEmptyAppHostProject	Recording	#78435201699	Logs
✅	CreateAndRunJsReactProject	Recording	#78435201762	Logs
✅	CreateAndRunPythonReactProject	Recording	#78435201629	Logs
✅	CreateAndRunTypeScriptEmptyAppHostProject	Recording	#78435201740	Logs
✅	CreateAndRunTypeScriptStarterProject	Recording	#78435201437	Logs
✅	CreateJavaAppHostWithViteApp	Recording	#78435201720	Logs
✅	CreateTypeScriptAppHostWithViteApp_AllowsGuestAppPackageManagerToDiffer	Recording	#78435201493	Logs
✅	CreateTypeScriptAppHostWithViteApp_UsesConfiguredToolchain	Recording	#78435201493	Logs
✅	DashboardRunWithAgentMcpListTracesReturnsNoTraces	Recording	#78435201448	Logs
✅	DashboardRunWithAgentMcpListTracesReturnsNoTraces_DevLocalhost	Recording	#78435201448	Logs
✅	DashboardRunWithOtelTracesReturnsNoTraces	Recording	#78435201448	Logs
✅	DashboardRunWithOtelTracesReturnsNoTraces_DevLocalhost	Recording	#78435201448	Logs
✅	DeployK8sBasicApiService	Recording	#78435201524	Logs
✅	DeployK8sWithExternalHelmChart	Recording	#78435201480	Logs
✅	DeployK8sWithGarnet	Recording	#78435201504	Logs
✅	DeployK8sWithMongoDB	Recording	#78435201722	Logs
✅	DeployK8sWithMySql	Recording	#78435201556	Logs
✅	DeployK8sWithPostgres	Recording	#78435201511	Logs
✅	DeployK8sWithRabbitMQ	Recording	#78435201406	Logs
✅	DeployK8sWithRedis	Recording	#78435201697	Logs
✅	DeployK8sWithSqlServer	Recording	#78435201488	Logs
✅	DeployK8sWithValkey	Recording	#78435201436	Logs
✅	DeployTypeScriptAppToKubernetes	Recording	#78435201410	Logs
✅	DescribeCommandResolvesReplicaNames	Recording	#78435201519	Logs
✅	DescribeCommandShowsRunningResources	Recording	#78435201519	Logs
✅	DetachFormatJsonProducesValidJson	Recording	#78435201474	Logs
✅	DetachFormatJsonProducesValidJsonWhenRestartingExistingInstance	Recording	#78435201474	Logs
✅	DoPublishAndDeployListStepsWork	Recording	#78435201708	Logs
✅	DocsCommand_RendersInteractiveMarkdownFromLocalSource	Recording	#78435201559	Logs
✅	DoctorCommand_DetectsDeprecatedAgentConfig	Recording	#78435201582	Logs
✅	DoctorCommand_TypeScriptAppHostReportsMissingConfiguredToolchain	Recording	#78435201444	Logs
✅	DoctorCommand_WithSslCertDir_ShowsTrusted	Recording	#78435201444	Logs
✅	DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	Recording	#78435201444	Logs
✅	GatewayWithoutExternalEndpoint_FailsPublishWithGuidance	Recording	#78435201442	Logs
✅	GeneratedAspireDevScript_StartsWatchMode_WithConfiguredToolchain	Recording	#78435201493	Logs
✅	GlobalMigration_HandlesCommentsAndTrailingCommas	Recording	#78435201454	Logs
✅	GlobalMigration_HandlesMalformedLegacyJson	Recording	#78435201454	Logs
✅	GlobalMigration_PreservesAllValueTypes	Recording	#78435201454	Logs
✅	GlobalMigration_SkipsWhenNewConfigExists	Recording	#78435201454	Logs
✅	GlobalSettings_MigratedFromLegacyFormat	Recording	#78435201454	Logs
✅	IngressWithoutExternalEndpoint_FailsPublishWithGuidance	Recording	#78435201442	Logs
✅	InitTypeScriptAppHost_AugmentsExistingViteRepoInWorkspaceSubdirectory	Recording	#78435201493	Logs
✅	InteractiveCSharpInitCreatesExpectedFiles	Recording	#78435201683	Logs
✅	InvalidAppHostPathWithComments_IsHealedOnRun	Recording	#78435201605	Logs
✅	JavaScriptHostingApisRunFromTypeScriptAppHost	Recording	#78435201463	Logs
✅	LatestCliCanStartStableChannelAppHost	Recording	#78435201467	Logs
✅	LatestCliCanStartStableChannelTypeScriptAppHost	Recording	#78435201467	Logs
✅	LegacySettingsMigration_AdjustsRelativeAppHostPath	Recording	#78435201756	Logs
✅	LogsCommandShowsResourceLogs	Recording	#78435201728	Logs
✅	OtelLogsReturnsStructuredLogsFromStarterApp	Recording	#78435201459	Logs
✅	OtelLogsReturnsStructuredLogsFromStarterAppIsolated	Recording	#78435201459	Logs
✅	PsCommandListsRunningAppHost	Recording	#78435201498	Logs
✅	PsFormatJsonOutputsOnlyJsonToStdout	Recording	#78435201498	Logs
✅	PublishJavaScriptPatternsGeneratesExpectedDockerComposeArtifacts	Recording	#78435201751	Logs
✅	PublishWithConfigureEnvFileUpdatesEnvOutput	Recording	#78435201751	Logs
✅	PublishWithDockerComposeServiceCallbackSucceeds	Recording	#78435201751	Logs
✅	PublishWithoutOutputPathUsesAppHostDirectoryDefault	Recording	#78435201751	Logs
✅	ResourceCommand_FailedExecution_DisplaysAppHostLogPathAndLogContainsEntries	Recording	#78435201725	Logs
✅	ResourceCommand_SetAndDeleteParameterUpdatesDescribeOutput	Recording	#78435201725	Logs
✅	RestoreGeneratesSdkFiles	Recording	#78435201435	Logs
✅	RestoreGeneratesSdkFiles_WithConfiguredToolchain	Recording	#78435201391	Logs
✅	RestoreRefreshesGeneratedSdkAfterAddingIntegration	Recording	#78435201391	Logs
✅	RestoreSupportsConfigOnlyHelperPackageAndCrossPackageTypes	Recording	#78435201657	Logs
✅	RunFromParentDirectory_UsesExistingConfigNearAppHost	Recording	#78435201481	Logs
✅	RunReportsSyntaxErrorsForDotNetAppHost	Recording	#78435201635	Logs
✅	RunReportsSyntaxErrorsForTypeScriptAppHost	Recording	#78435201635	Logs
✅	SecretCrudOnDotNetAppHost	Recording	#78435201737	Logs
✅	SecretCrudOnTypeScriptAppHost	Recording	#78435201489	Logs
✅	StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	Recording	#78435201682	Logs
✅	StartAndWaitForTypeScriptSqlServerAppHostWithNativeAssets	Recording	#78435201654	Logs
✅	StartReportsSyntaxErrorsForDotNetAppHost	Recording	#78435201635	Logs
✅	StartReportsSyntaxErrorsForTypeScriptAppHost	Recording	#78435201635	Logs
✅	StopAllAppHostsFromAppHostDirectory	Recording	#78435201700	Logs
✅	StopJavaPolyglotAppHostUsingApphostDirectory	Recording	#78435201645	Logs
✅	StopNonInteractiveSingleAppHost	Recording	#78435201700	Logs
✅	StopTypeScriptPolyglotAppHostUsingApphostDirectory	Recording	#78435201475	Logs
✅	StopWithNoRunningAppHostExitsSuccessfully	Recording	#78435201470	Logs
✅	UnAwaitedChainsCompileWithAutoResolvePromises	Recording	#78435201391	Logs
❔	UpdateProjectChannelToStable_CSharpEmptyAppHost_PreservesAspireConfigChannel	Recording	#78435201693	Logs
✅	UpdateProjectChannelToStable_CSharpSingleFileInit_PreservesAspireConfigChannel	Recording	#78435201693	Logs
✅	UpdateProjectChannelToStable_TypeScriptSingleFileInit_PreservesAspireConfigChannel	Recording	#78435201693	Logs
✅	UpdateProjectChannelToStable_TypeScript_PreviewsStablePackagesAndPreservesChannel	Recording	#78435201693	Logs

---

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