Improve detach mode: fix pipe handle inheritance and unify log naming by davidfowl · Pull Request #14424 · dotnet/aspire

davidfowl · 2026-02-10T08:01:57Z

Description

When running aspire run --detach, the child CLI process inherited pipe handles from stdout/stderr redirection. This kept pipes open until the AppHost grandchild died, preventing callers using synchronous process APIs (e.g. Node.js execSync) from detecting that the CLI had exited. This is primarily a Windows issue due to how handle inheritance works.

Changes

Stop redirecting child stdout/stderr — removes pipe handle inheritance. The child writes to its own log file instead.
New --log-file hidden option — parent passes an explicit log file path to the child so the parent knows where to point on failure.
Unified log filename generation — new FileLoggerProvider.GenerateLogFilePath static helper used by both the normal logger and the detach child path. Format: cli_20260210T074038_12345.log (with optional suffix).
Better error messages — maps FailedToBuildArtifacts exit code to a friendly message. Points to the child's log file on failure.
Cache cleanup fix — updated log file suffix pattern to match the new naming format.

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
Does the change require an update in our Aspire docs?
- Yes
- No

github-actions · 2026-02-10T08:02:07Z

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

Or

Run remotely in PowerShell:

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

Copilot

Pull request overview

This PR improves aspire run --detach behavior by preventing pipe/handle inheritance issues (notably on Windows) and standardizing how CLI log files are named and discovered, so detached failures can reliably point users to the right diagnostics.

Changes:

Adds a hidden --log-file option and passes it from the detach parent process to the detach child process.
Introduces FileLoggerProvider.GenerateLogFilePath(...) and updates log file naming to cli_yyyyMMddTHHmmss_{pid}[_{suffix}].log.
Improves detached-mode failure UX by mapping FailedToBuildArtifacts to a friendlier localized message and pointing to the child’s log file.

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/Aspire.Cli/Program.cs	Parses `--log-file` early and uses it to initialize file logging before host build.
src/Aspire.Cli/Diagnostics/FileLoggerProvider.cs	Adds centralized log filename generation and updates default naming format.
src/Aspire.Cli/Commands/RunCommand.cs	Adds hidden `--log-file`, stops redirecting detached child stdout/stderr, passes explicit child log path, and improves failure messaging.
src/Aspire.Cli/Commands/CacheCommand.cs	Updates log filename suffix matching to align with new `cli_{timestamp}_{pid}.log` format.
src/Aspire.Cli/Resources/RunCommandStrings.resx	Adds new `AppHostFailedToBuild` resource string.
src/Aspire.Cli/Resources/RunCommandStrings.Designer.cs	Regenerates strongly-typed accessor for `AppHostFailedToBuild`.
src/Aspire.Cli/Resources/xlf/RunCommandStrings.cs.xlf	Adds `AppHostFailedToBuild` localization entry (new).
src/Aspire.Cli/Resources/xlf/RunCommandStrings.de.xlf	Adds `AppHostFailedToBuild` localization entry (new).
src/Aspire.Cli/Resources/xlf/RunCommandStrings.es.xlf	Adds `AppHostFailedToBuild` localization entry (new).
src/Aspire.Cli/Resources/xlf/RunCommandStrings.fr.xlf	Adds `AppHostFailedToBuild` localization entry (new).
src/Aspire.Cli/Resources/xlf/RunCommandStrings.it.xlf	Adds `AppHostFailedToBuild` localization entry (new).
src/Aspire.Cli/Resources/xlf/RunCommandStrings.ja.xlf	Adds `AppHostFailedToBuild` localization entry (new).
src/Aspire.Cli/Resources/xlf/RunCommandStrings.ko.xlf	Adds `AppHostFailedToBuild` localization entry (new).
src/Aspire.Cli/Resources/xlf/RunCommandStrings.pl.xlf	Adds `AppHostFailedToBuild` localization entry (new).
src/Aspire.Cli/Resources/xlf/RunCommandStrings.pt-BR.xlf	Adds `AppHostFailedToBuild` localization entry (new).
src/Aspire.Cli/Resources/xlf/RunCommandStrings.ru.xlf	Adds `AppHostFailedToBuild` localization entry (new).
src/Aspire.Cli/Resources/xlf/RunCommandStrings.tr.xlf	Adds `AppHostFailedToBuild` localization entry (new).
src/Aspire.Cli/Resources/xlf/RunCommandStrings.zh-Hans.xlf	Adds `AppHostFailedToBuild` localization entry (new).
src/Aspire.Cli/Resources/xlf/RunCommandStrings.zh-Hant.xlf	Adds `AppHostFailedToBuild` localization entry (new).

Files not reviewed (1)

src/Aspire.Cli/Resources/RunCommandStrings.Designer.cs: Language not supported

Comments suppressed due to low confidence (2)

src/Aspire.Cli/Commands/CacheCommand.cs:121

cache clear skips deleting the current log file by checking a filename suffix based on Environment.ProcessId, but the CLI can now run with an explicit --log-file path (and detached child logs also include an extra suffix). This can cause the current session’s log file to be deleted while still in use. Consider skipping deletion by comparing against ExecutionContext.LogFilePath (full path) instead of relying on the filename pattern.

                // Also clear the logs directory (skip current process's log file)
                var logsDirectory = ExecutionContext.LogsDirectory;
                // Log files are named cli_{timestamp}_{pid}.log, so we need to check the suffix
                var currentLogFileSuffix = $"_{Environment.ProcessId}.log";
                if (logsDirectory.Exists)
                {
                    foreach (var file in logsDirectory.GetFiles("*", SearchOption.AllDirectories))
                    {
                        // Skip the current process's log file to avoid deleting it while in use
                        if (file.Name.EndsWith(currentLogFileSuffix, StringComparison.OrdinalIgnoreCase))
                        {

src/Aspire.Cli/Commands/RunCommand.cs:665

Detached mode now generates/passes a childLogFile and (on failure) points users to that file, but the success paths still report _fileLoggerProvider.LogFilePath (parent session log) in JSON output and the rendered summary. Since the child process is the one that continues running and writing logs, consider returning/displaying the child log file path consistently to avoid sending users/tools to a log that won’t contain the relevant AppHost build/runtime output.

        // Build the arguments for the child CLI process
        // Tell the child where to write its log so we can find it on failure.
        var childLogFile = GenerateChildLogFilePath();

        var args = new List<string>
        {
            "run",
            "--non-interactive",
            "--project",
            effectiveAppHostFile.FullName,
            "--log-file",
            childLogFile
        };

Copilot · 2026-02-10T08:12:26Z

src/Aspire.Cli/Commands/RunCommand.cs

+        return Diagnostics.FileLoggerProvider.GenerateLogFilePath(
+            ExecutionContext.LogsDirectory.FullName,
+            _timeProvider,
+            suffix: "detach-child");


GenerateChildLogFilePath() calls FileLoggerProvider.GenerateLogFilePath(), which embeds Environment.ProcessId. Since this method runs in the parent process, the child log file name ends up containing the parent PID, which is misleading and breaks the “pid in filename == process writing the log” convention used elsewhere. Consider adjusting the helper to accept an explicit PID (or use a different uniqueness token for precomputed paths) so detached child log files can reflect the child process ID.

This issue also appears on line 653 of the same file.

Suggested change

return Diagnostics.FileLoggerProvider.GenerateLogFilePath(

ExecutionContext.LogsDirectory.FullName,

_timeProvider,

suffix: "detach-child");

var logsDirectory = ExecutionContext.LogsDirectory.FullName;

var now = _timeProvider.GetUtcNow();

var timestamp = now.ToString("yyyyMMddHHmmssfff", CultureInfo.InvariantCulture);

var uniqueId = Guid.NewGuid().ToString("N", CultureInfo.InvariantCulture);

var fileName = $"aspire-detach-child-{timestamp}-{uniqueId}.log";

return Path.Combine(logsDirectory, fileName);

Copilot · 2026-02-10T08:12:26Z

src/Aspire.Cli/Commands/RunCommand.cs

+                // Show a friendly message based on well-known exit codes from the child
+                var errorMessage = childExitCode switch
+                {
+                    ExitCodeConstants.FailedToBuildArtifacts => RunCommandStrings.AppHostFailedToBuild,
+                    _ => string.Format(CultureInfo.CurrentCulture, RunCommandStrings.AppHostExitedWithCode, childExitCode)
+                };
+                _interactionService.DisplayError(errorMessage);


Changes to detached execution introduced new behaviors that are currently untested (e.g., --log-file propagation, exit-code-to-message mapping for FailedToBuildArtifacts, and ensuring the correct log file path is surfaced on failure). There are existing RunCommandTests, but none cover --detach; adding focused unit/integration tests for these paths would help prevent regressions on Windows and in programmatic consumers.

github-actions · 2026-02-10T08:20:57Z

🎬 CLI E2E Test Recordings

The following terminal recordings are available for commit 6e14e8a:

Test	Recording
AgentCommands_AllHelpOutputs_AreCorrect	▶️ View Recording
AgentInitCommand_MigratesDeprecatedConfig	▶️ View Recording
Banner_DisplayedOnFirstRun	▶️ View Recording
Banner_DisplayedWithExplicitFlag	▶️ View Recording
CreateAndDeployToDockerCompose	▶️ View Recording
CreateAndDeployToDockerComposeInteractive	▶️ View Recording
CreateAndPublishToKubernetes	▶️ View Recording
CreateAndRunAspireStarterProject	▶️ View Recording
CreateAndRunAspireStarterProjectWithBundle	▶️ View Recording
CreateAndRunJsReactProject	▶️ View Recording
CreateAndRunPythonReactProject	▶️ View Recording
CreateEmptyAppHostProject	▶️ View Recording
CreateStartAndStopAspireProject	▶️ View Recording
CreateStartWaitAndStopAspireProject	▶️ View Recording
CreateTypeScriptAppHostWithViteApp	▶️ View Recording
DoctorCommand_DetectsDeprecatedAgentConfig	▶️ View Recording
DoctorCommand_WithSslCertDir_ShowsTrusted	▶️ View Recording
DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	▶️ View Recording
LogsCommandShowsResourceLogs	▶️ View Recording
PsCommandListsRunningAppHost	▶️ View Recording
ResourcesCommandShowsRunningResources	▶️ View Recording

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

The previous approach (RedirectStandardOutput=true + close streams) still created inheritable pipe handles. Instead, keep Redirect=false to avoid pipe inheritance and have the child process suppress its own console output when --log-file is specified (the signal that it's a detach child).

Replace Process.Start with platform-specific launcher that suppresses child output and prevents handle/fd inheritance to grandchildren: - Windows: P/Invoke CreateProcess with STARTUPINFOEX and PROC_THREAD_ATTRIBUTE_HANDLE_LIST (same approach as Docker/hcsshim). Child stdout/stderr go to NUL, only NUL handle is inheritable. - Linux/macOS: Process.Start with RedirectStdout=true + close streams. Pipes are O_CLOEXEC so grandchild never inherits them. Removes the Console.SetOut(TextWriter.Null) workaround from Program.cs.

dup2 onto fd 0/1/2 clears O_CLOEXEC, so grandchildren DO inherit the pipe as their stdio. With the parent's read-end closed, writes produce harmless EPIPE. Updated comments to accurately describe the Unix fd inheritance model based on dotnet/runtime pal_process.c source.

sebastienros · 2026-02-12T17:28:34Z

src/Aspire.Cli/Processes/DetachedProcessLauncher.Windows.cs

+                    }
+
+                    // Close the process and thread handles — we only need the PID
+                    CloseHandle(pi.hProcess);


Should this be done after calling Process.GetProcessById(pi.dwProcessId);?

davidfowl · 2026-02-12T17:53:48Z

Found one behavioral regression to fix before merge:

ParseLogFileOption() in Program.cs scans raw args for --log-file without honoring the -- delimiter. That means app arguments can accidentally override the CLI's internal log target (for example: aspire run -- --log-file app.log).

This can silently redirect CLI logging to an unintended path and violate normal option-boundary semantics.

Suggested fix: stop scanning once -- is encountered, or source this option from ParseResult in run instead of raw pre-parse args.

Copilot AI review requested due to automatic review settings February 10, 2026 08:01

Copilot started reviewing on behalf of davidfowl February 10, 2026 08:02 View session

Copilot AI reviewed Feb 10, 2026

View reviewed changes

github-actions bot mentioned this pull request Feb 10, 2026

[pull requests] Review required #13834

Open

davidfowl force-pushed the davidfowl/detach-more branch 2 times, most recently from f98890f to ba11a15 Compare February 10, 2026 09:21

davidfowl closed this Feb 11, 2026

davidfowl reopened this Feb 11, 2026

dotnet-policy-service bot added this to the 13.2 milestone Feb 11, 2026

Improve detach mode: fix pipe handle inheritance and unify log naming

08c1c4a

davidfowl force-pushed the davidfowl/detach-more branch from ba11a15 to 08c1c4a Compare February 12, 2026 02:19

davidfowl changed the base branch from main to release/13.2 February 12, 2026 02:19

davidfowl added 6 commits February 11, 2026 20:55

Show child log file path on detach success

b673bda

Fix detach: redirect child output to suppress console bleed

89af2b6

Fix command-line quoting for Windows backslash escaping

40486d4

davidfowl force-pushed the davidfowl/detach-more branch from 09fbf4c to 40486d4 Compare February 12, 2026 08:30

sebastienros reviewed Feb 12, 2026

View reviewed changes

sebastienros approved these changes Feb 12, 2026

View reviewed changes

Fix detach log parsing and child log path handling

6e14e8a

davidfowl merged commit 7fcc0cb into release/13.2 Feb 13, 2026
342 checks passed

davidfowl deleted the davidfowl/detach-more branch February 13, 2026 06:00

dotnet-policy-service bot modified the milestone: 13.2 Feb 13, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve detach mode: fix pipe handle inheritance and unify log naming#14424

Improve detach mode: fix pipe handle inheritance and unify log naming#14424
davidfowl merged 8 commits intorelease/13.2from
davidfowl/detach-more

davidfowl commented Feb 10, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 10, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 10, 2026

Uh oh!

Copilot AI Feb 10, 2026

Uh oh!

github-actions bot commented Feb 10, 2026 •

edited

Loading

Uh oh!

sebastienros Feb 12, 2026

Uh oh!

davidfowl commented Feb 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

-        return Diagnostics.FileLoggerProvider.GenerateLogFilePath(
-            ExecutionContext.LogsDirectory.FullName,
-            _timeProvider,
-            suffix: "detach-child");
+        var logsDirectory = ExecutionContext.LogsDirectory.FullName;
+        var now = _timeProvider.GetUtcNow();
+        var timestamp = now.ToString("yyyyMMddHHmmssfff", CultureInfo.InvariantCulture);
+        var uniqueId = Guid.NewGuid().ToString("N", CultureInfo.InvariantCulture);
+        var fileName = $"aspire-detach-child-{timestamp}-{uniqueId}.log";
+        return Path.Combine(logsDirectory, fileName);

Conversation

davidfowl commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Checklist

Uh oh!

github-actions bot commented Feb 10, 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!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

🎬 CLI E2E Test Recordings

Uh oh!

sebastienros Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

davidfowl commented Feb 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

davidfowl commented Feb 10, 2026 •

edited

Loading

github-actions bot commented Feb 10, 2026 •

edited

Loading

github-actions bot commented Feb 10, 2026 •

edited

Loading