Interface IProcessRunner

Namespace

Invex.Process

Assembly

Invex.Process.dll

Defines a service for executing external processes with comprehensive logging, output capture, and error handling.

public interface IProcessRunner

Examples

Running a tool and inspecting its captured output:

var result = await processRunner.RunAsync(
    new ProcessRunOptions("git", "rev-parse HEAD")
    {
        WorkingDirectory = repoRoot,
    },
    cancellationToken);

var commitSha = result.Output.Trim();

Remarks

Both stdout and stderr are captured in real time via async read loops so that long-running processes stream their output to the logger rather than buffering it until exit.

This interface is registered as a singleton by ProcessHostExtensions. Inject it into build targets and helpers instead of using System.Diagnostics.Process directly, to benefit from consistent logging and uniform error handling across all process invocations.

Methods

Run(ProcessRunOptions)

Executes an external process synchronously, blocking until it exits, and returns its result.

ProcessRunResult Run(ProcessRunOptions options)

Parameters

options ProcessRunOptions

The configuration for the process execution.

Returns

ProcessRunResult

A ProcessRunResult containing the exit code and captured output. Only returned when the exit code is zero, or when AllowFailedResult is true.

Exceptions

ProcessException

Thrown when the process exits with a non-zero code and AllowFailedResult is false. The message includes the command line, exit code, working directory (when set), and any captured stderr; Result carries the full captured result.

Win32Exception

Thrown when the executable named by Name cannot be found or started.

RunAsync(ProcessRunOptions, CancellationToken)

Executes an external process asynchronously and returns its result when it exits.

Task<ProcessRunResult> RunAsync(ProcessRunOptions options, CancellationToken cancellationToken = default)

Parameters

options ProcessRunOptions

The configuration for the process execution.

cancellationToken CancellationToken

A token that cancels the wait for the process to exit. Note: cancelling the token aborts the wait but does not kill the underlying OS process, which continues to run; any output captured so far is discarded.

Returns

Task<ProcessRunResult>

A task that resolves to a ProcessRunResult when the process exits. Only completes successfully when the exit code is zero, or when AllowFailedResult is true.

Exceptions

ProcessException

Thrown (on the returned task) when the process exits with a non-zero code and AllowFailedResult is false. The message includes the command line, exit code, working directory (when set), and any captured stderr; Result carries the full captured result.

Win32Exception

Thrown when the executable named by Name cannot be found or started.

OperationCanceledException

Thrown (on the returned task) when cancellationToken is cancelled before the process exits.