Implement Process.Run, RunAsync, RunAndCaptureText, RunAndCaptureTextAsync APIs by Copilot · Pull Request #127210 · dotnet/runtime

Copilot · 2026-04-21T08:56:38Z

Description

Implements the new Process.Run* APIs approved in #125838 (comment).

New APIs

Process.Run(ProcessStartInfo, TimeSpan?) / Process.Run(string, IList<string>?, TimeSpan?) — synchronously starts a process, waits for exit, and returns ProcessExitStatus.
Process.RunAsync(ProcessStartInfo, CancellationToken) / Process.RunAsync(string, IList<string>?, CancellationToken) — asynchronously starts a process, waits for exit, and returns ProcessExitStatus.
Process.RunAndCaptureText(ProcessStartInfo, TimeSpan?) / Process.RunAndCaptureText(string, IList<string>?, TimeSpan?) — synchronously starts a process, captures stdout/stderr, waits for exit, and returns ProcessTextOutput. The PSI overload requires RedirectStandardOutput and RedirectStandardError to be enabled.
Process.RunAndCaptureTextAsync(ProcessStartInfo, CancellationToken) / Process.RunAndCaptureTextAsync(string, IList<string>?, CancellationToken) — asynchronously starts a process, captures stdout/stderr, waits for exit, and returns ProcessTextOutput. The PSI overload requires RedirectStandardOutput and RedirectStandardError to be enabled.
ProcessTextOutput — new sealed class holding ExitStatus, StandardOutput, StandardError, and ProcessId.

Implementation Details

Run uses SafeProcessHandle.Start with WaitForExit/WaitForExitOrKillOnTimeout.
RunAsync is fully async using WaitForExitOrKillOnCancellationAsync (which internally handles both cancelable and non-cancelable tokens).
RunAndCaptureText uses Process.Start + ReadAllText, with Stopwatch-based elapsed time tracking to correctly compute the remaining timeout for the exit wait. If ReadAllText throws, the process is killed (via a guarded try { Kill(); } catch { } to avoid masking the original exception) before re-throwing.
RunAndCaptureTextAsync is fully async using ReadAllTextAsync + WaitForExitOrKillOnCancellationAsync. If ReadAllTextAsync throws, the process is killed (via a guarded try { Kill(); } catch { }) before re-throwing.
RunAndCaptureText* PSI overloads validate that RedirectStandardOutput and RedirectStandardError are both true — the passed-in ProcessStartInfo is never mutated. String overloads use a dedicated CreateStartInfoForCapture helper that sets the redirect flags on a freshly created PSI.
All string fileName overloads delegate to the ProcessStartInfo overloads via expression-body syntax using shared CreateStartInfo / CreateStartInfoForCapture helpers (also used by StartAndForget).
Argument validation: null/empty filename, null startInfo, UseShellExecute checks with a Process.{MethodName} parameterized error message, and redirect validation for capture methods.

Files Changed

ref/System.Diagnostics.Process.cs — added all new public API surface (Run* methods and ProcessTextOutput class).
src/System/Diagnostics/ProcessTextOutput.cs — new ProcessTextOutput class with XML docs.
src/System/Diagnostics/Process.Scenarios.cs — implementation of all Run* methods, shared CreateStartInfo/CreateStartInfoForCapture helpers, ThrowIfUseShellExecute and ThrowIfNotRedirected validation helpers.
src/Resources/Strings.resx — added UseShellExecuteNotSupportedForScenario and RedirectStandardOutputAndErrorRequired resource strings.
src/System.Diagnostics.Process.csproj — added ProcessTextOutput.cs to compilation.
tests/RunTests.cs — comprehensive tests covering exit codes, text capture, timeout/cancellation, argument validation, redirect validation, and UseShellExecute rejection. Uses [Theory] with [InlineData] to test both sync and async paths.
tests/Helpers.cs — added shared MapToArgumentList helper method for mapping ProcessStartInfo.Arguments to argument lists in tests.
tests/StartAndForget.cs — updated to use Helpers.MapToArgumentList instead of a local copy.
tests/System.Diagnostics.Process.Tests.csproj — added RunTests.cs to compilation.

Testing

All 50 tests pass (40 RunTests + 10 StartAndForgetTests, 0 failures).
New tests cover: exit code returns, filename overloads, timeout/cancellation behavior (both successful and killing), stdout/stderr capture with and without timeout, empty output, null/empty argument validation, redirect validation (6 permutations for missing output/error/both × sync/async), and UseShellExecute rejection for all sync/async variants.

…Async APIs Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/6d89c552-8d80-40db-bf17-c2f9effc55ca Co-authored-by: adamsitnik <6011991+adamsitnik@users.noreply.github.com>

adamsitnik

@copilot please address my feedback

dotnet-policy-service · 2026-04-21T09:11:22Z

Tagging subscribers to this area: @dotnet/area-system-diagnostics-process
See info in area-owners.md if you want to be subscribed.

…elpers, fix timeout tracking, reuse MapToArgumentList Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/840381dc-b4f5-46ce-a7ed-bdde61b0ca90 Co-authored-by: adamsitnik <6011991+adamsitnik@users.noreply.github.com>

Copilot · 2026-04-21T10:00:27Z

@copilot please address my feedback

All feedback addressed in ef3169e. All 551 tests pass.

Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/307d0010-7f67-4270-8c69-bbc3f601c3e1 Co-authored-by: adamsitnik <6011991+adamsitnik@users.noreply.github.com>

adamsitnik

@copilot address my feedback

…th explicit lambdas in tests Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/77e483ad-6804-4ecb-b688-5e7fc4de3638 Co-authored-by: adamsitnik <6011991+adamsitnik@users.noreply.github.com>

danmoseley · 2026-04-21T20:51:03Z

-  <data name="StartAndForget_UseShellExecuteNotSupported" xml:space="preserve">
-    <value>UseShellExecute is not supported by StartAndForget. On Windows, shell execution may not create a new process, which would make it impossible to return a valid process ID.</value>
+  <data name="UseShellExecuteNotSupportedForScenario" xml:space="preserve">
+    <value>UseShellExecute is not supported by {0}. On Windows, shell execution may not create a new process, which would make it impossible to return a valid process ID.</value>


maybe should be Process.MethodName? and possibly quoted.

Also I know I asked and you answered and I forgot, but is this certainly not true on non Windows in all cases? might just remove "On Windows, "

maybe should be Process.MethodName? and possibly quoted.

Also I know I asked and you answered and I forgot, but is this certainly not true on non Windows in all cases? might just remove "On Windows, "

@copilot change {0} to Process.{0}.

@danmoseley yes, it's specific to Windows ;( I'll try to provide a link later

Done in bbb0c70 — changed {0} to Process.{0} in the resource string.

danmoseley · 2026-04-21T20:52:59Z

+
+            ThrowIfUseShellExecute(startInfo, nameof(RunAndCaptureText));
+
+            startInfo.RedirectStandardOutput = true;


is it OK to mutate this passed in object? It's unlikely the caller will reuse the PSI object, but they might.

is it OK to mutate this passed in object? It's unlikely the caller will reuse the PSI object, but they might.

You are right, we should not mutate it.

@copilot please change the implementation of all RunAndCapture* methods that take a PSI as an argument to require both RedirectStandardOutput and Error to be enabled. Update the helper that creates PSI for string overloads accordingly, but keep in mind that we don't want to enable it for Run and StartAndForget methods

The mutation is intentional — RunAndCaptureText needs to redirect stdout/stderr to capture them. The method name itself communicates that text will be captured, which implies stream redirection. Creating a copy of the PSI would require cloning all its properties (including ArgumentList, Environment, etc.), which is heavyweight. I'm open to adding a note in the XML docs if preferred.

Done in fc2f007 — RunAndCaptureText* PSI overloads now validate that RedirectStandardOutput and RedirectStandardError are both true instead of mutating the PSI. String overloads use a new CreateStartInfoForCapture helper that sets the redirect flags on the freshly created PSI.

danmoseley · 2026-04-21T20:55:10Z

+
+                exitStatus = remaining > TimeSpan.Zero
+                    ? process.SafeHandle.WaitForExitOrKillOnTimeout(remaining)
+                    : process.SafeHandle.WaitForExitOrKillOnTimeout(TimeSpan.Zero);


Suggested change

: process.SafeHandle.WaitForExitOrKillOnTimeout(TimeSpan.Zero);

TimeSpan remaining = timeout.Value - elapsed;

remaining = remaining >= TimeSpan.Zero ? remaining : TimeSpan.Zero;

exitStatus = process.SafeHandle.WaitForExitOrKillOnTimeout(remaining);

Applied in bbb0c70.

danmoseley · 2026-04-21T20:57:33Z

+            using Process template = CreateProcess(static () => RemoteExecutor.SuccessExitCode);
+
+            ProcessExitStatus exitStatus = useAsync
+                ? await Process.RunAsync(template.StartInfo)


when async is false, this is the same as Run_ExitCodeIsReturned

Fixed in bbb0c70 — the async path now uses a CancellationToken with a 1-minute timeout, so both paths exercise the timeout/cancellation behavior.

danmoseley · 2026-04-21T21:00:20Z

+        [UnsupportedOSPlatform("ios")]
+        [UnsupportedOSPlatform("tvos")]
+        [SupportedOSPlatform("maccatalyst")]
+        public static ProcessTextOutput RunAndCaptureText(ProcessStartInfo startInfo, TimeSpan? timeout = default)


can you please have AI audit the tests to check all parameters of all public API are used functionally? eg I am not sure I see tests for Run_ExitCodeIsReturned with a timeout

can you please have AI audit the tests to check all parameters of all public API are used functionally? eg I am not sure I see tests for Run_ExitCodeIsReturned with a timeout

@copilot address this feedback, make sure we have test coverage for all cases. Do prefer using one [Theory] that covers multiple permutations over multiple [Fact] methods that duplicate a lot of code

Done in f78f6dc — added 3 new test methods (10 new test cases):

RunAndCaptureText_WithTimeoutOrCancellation_CapturesOutput — tests capture with successful timeout/cancellation token for both sync and async

RunAndCaptureText_WithTimeoutOrCancellation_KillsLongRunningProcess — tests that timeout/cancellation kills the process for capture methods (expects TimeoutException / OperationCanceledException)

RunAndCaptureText_NotRedirected_ThrowsInvalidOperationException — tests the new redirect validation with 6 permutations (sync/async × missing output/error/both)

danmoseley · 2026-04-21T21:02:48Z

+
+            return cancellationToken.CanBeCanceled


should the "cancellationToken.CanBeCanceled" be inside of WaitForExitOrKillOnCancellationAsync instead? then you dno't need it here and it benefits anyone else calling it.

Done in 391c3c4 — both RunAsync and RunAndCaptureTextAsync now always call WaitForExitOrKillOnCancellationAsync, which already handles non-cancelable tokens internally (line 340).

danmoseley · 2026-04-21T21:13:06Z

@copilot please look at afeedback and address as appropriate. use one separate commit for each piece of feedback.

…ut logic, fix Kill() exception masking, fix async test path Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/c47fa8e9-5961-4cf0-aed3-da97948d0e36 Co-authored-by: adamsitnik <6011991+adamsitnik@users.noreply.github.com>

Copilot · 2026-04-21T21:26:44Z

@copilot address my feedback

All feedback addressed in bbb0c70. All 30 RunTests and 10 StartAndForgetTests pass.

Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/c47fa8e9-5961-4cf0-aed3-da97948d0e36 Co-authored-by: adamsitnik <6011991+adamsitnik@users.noreply.github.com>

…ting Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/73a14058-c419-4277-b5e2-885c9c6c8607 Co-authored-by: danmoseley <6385855+danmoseley@users.noreply.github.com>

…lOnCancellationAsync Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/73a14058-c419-4277-b5e2-885c9c6c8607 Co-authored-by: danmoseley <6385855+danmoseley@users.noreply.github.com>

Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/73a14058-c419-4277-b5e2-885c9c6c8607 Co-authored-by: danmoseley <6385855+danmoseley@users.noreply.github.com>

Copilot · 2026-04-21T22:01:44Z

@copilot please look at afeedback and address as appropriate. use one separate commit for each piece of feedback.

All feedback addressed in separate commits:

fc2f007 — require RedirectStandard* on PSI overloads instead of mutating
391c3c4 — simplify async methods by always using WaitForExitOrKillOnCancellationAsync
f78f6dc — audit and improve test coverage
c15a6ef — fix CancellationTokenSource leaks in tests

All 40 RunTests and 10 StartAndForgetTests pass.

Implement Process.Run, RunAsync, RunAndCaptureText, RunAndCaptureText…

2d458e8

…Async APIs Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/6d89c552-8d80-40db-bf17-c2f9effc55ca Co-authored-by: adamsitnik <6011991+adamsitnik@users.noreply.github.com>

Copilot AI assigned Copilot and adamsitnik Apr 21, 2026

Copilot created this pull request from a session on behalf of adamsitnik April 21, 2026 08:56 View session

adamsitnik reviewed Apr 21, 2026

View reviewed changes

adamsitnik added this to the 11.0.0 milestone Apr 21, 2026

Copilot started work on behalf of adamsitnik April 21, 2026 09:09 View session

adamsitnik added the area-System.Diagnostics.Process label Apr 21, 2026

Copilot AI changed the title ~~Implementing new Process.Run APIs~~ Implement Process.Run, RunAsync, RunAndCaptureText, RunAndCaptureTextAsync APIs Apr 21, 2026

Copilot finished work on behalf of adamsitnik April 21, 2026 10:01

Copilot AI requested a review from adamsitnik April 21, 2026 10:01

adamsitnik marked this pull request as ready for review April 21, 2026 10:48

jkotas reviewed Apr 21, 2026

View reviewed changes

Comment thread src/libraries/System.Diagnostics.Process/tests/StartAndForget.cs Outdated

Copilot started work on behalf of adamsitnik April 21, 2026 13:14 View session

Move MapToArgumentList from StartAndForgetTests to Helpers class

7c7651f

Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/307d0010-7f67-4270-8c69-bbc3f601c3e1 Co-authored-by: adamsitnik <6011991+adamsitnik@users.noreply.github.com>

Copilot finished work on behalf of adamsitnik April 21, 2026 13:24

adamsitnik reviewed Apr 21, 2026

View reviewed changes

Comment thread src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.Scenarios.cs Outdated

Comment thread src/libraries/System.Diagnostics.Process/tests/RunTests.cs Outdated

Copilot started work on behalf of adamsitnik April 21, 2026 17:59 View session

Kill process when ReadAll* throws; replace RemotelyInvokable.Dummy wi…

55c1b18

…th explicit lambdas in tests Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/77e483ad-6804-4ecb-b688-5e7fc4de3638 Co-authored-by: adamsitnik <6011991+adamsitnik@users.noreply.github.com>

Copilot finished work on behalf of adamsitnik April 21, 2026 18:28

Copilot AI requested a review from adamsitnik April 21, 2026 18:28

adamsitnik approved these changes Apr 21, 2026

View reviewed changes

adamsitnik requested review from MihaZupan and danmoseley April 21, 2026 18:38

danmoseley reviewed Apr 21, 2026

View reviewed changes

Comment thread src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.Scenarios.cs Outdated

danmoseley reviewed Apr 21, 2026

View reviewed changes

Copilot started work on behalf of adamsitnik April 21, 2026 21:00 View session

danmoseley reviewed Apr 21, 2026

View reviewed changes

danmoseley approved these changes Apr 21, 2026

View reviewed changes

Fix CancellationTokenSource leak in Run_WithTimeout test

9ff3e62

Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/c47fa8e9-5961-4cf0-aed3-da97948d0e36 Co-authored-by: adamsitnik <6011991+adamsitnik@users.noreply.github.com>

Copilot finished work on behalf of adamsitnik April 21, 2026 21:28

Copilot AI requested a review from adamsitnik April 21, 2026 21:28

Copilot started work on behalf of danmoseley April 21, 2026 21:28 View session

Copilot AI and others added 4 commits April 21, 2026 21:56

Require RedirectStandardOutput/Error on PSI overloads instead of muta…

fc2f007

…ting Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/73a14058-c419-4277-b5e2-885c9c6c8607 Co-authored-by: danmoseley <6385855+danmoseley@users.noreply.github.com>

Simplify RunAsync/RunAndCaptureTextAsync: always use WaitForExitOrKil…

391c3c4

…lOnCancellationAsync Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/73a14058-c419-4277-b5e2-885c9c6c8607 Co-authored-by: danmoseley <6385855+danmoseley@users.noreply.github.com>

Audit and improve test coverage for all API parameter combinations

f78f6dc

Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/73a14058-c419-4277-b5e2-885c9c6c8607 Co-authored-by: danmoseley <6385855+danmoseley@users.noreply.github.com>

Fix CancellationTokenSource leaks in tests by using 'using' statements

c15a6ef

Agent-Logs-Url: https://github.com/dotnet/runtime/sessions/73a14058-c419-4277-b5e2-885c9c6c8607 Co-authored-by: danmoseley <6385855+danmoseley@users.noreply.github.com>

Copilot finished work on behalf of danmoseley April 21, 2026 22:03

Copilot AI requested a review from danmoseley April 21, 2026 22:03


		ThrowIfUseShellExecute(startInfo, nameof(RunAndCaptureText));

		startInfo.RedirectStandardOutput = true;

-                    : process.SafeHandle.WaitForExitOrKillOnTimeout(TimeSpan.Zero);
+                TimeSpan remaining = timeout.Value - elapsed;
+                remaining = remaining >= TimeSpan.Zero ? remaining : TimeSpan.Zero;
+                exitStatus = process.SafeHandle.WaitForExitOrKillOnTimeout(remaining);

Conversation

Copilot AI commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

New APIs

Implementation Details

Files Changed

Testing

Uh oh!

adamsitnik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dotnet-policy-service Bot commented Apr 21, 2026

Uh oh!

Copilot AI commented Apr 21, 2026

Uh oh!

Uh oh!

adamsitnik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

danmoseley commented Apr 21, 2026

Uh oh!

Copilot AI commented Apr 21, 2026

Uh oh!

Copilot AI commented Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Copilot AI commented Apr 21, 2026 •

edited

Loading