Class ProcessRunOptions

Namespace

Invex.Process

Assembly

Invex.Process.dll

Immutable configuration for a single external-process execution through IProcessRunner.

public sealed record ProcessRunOptions

Inheritance

object

ProcessRunOptions

Examples

Running a quiet, failure-tolerant invocation with a custom environment:

var options = new ProcessRunOptions("dotnet", ["build", "--configuration", configuration])
{
    WorkingDirectory = projectDirectory,
    InvocationLogLevel = LogLevel.Debug,
    AllowFailedResult = true,
    EnvironmentVariables = { ["DOTNET_NOLOGO"] = "1" },
};

Remarks

All properties have defaults suited to typical build-automation use: invocation is logged at Microsoft.Extensions.Logging.LogLevel.Information, stdout at Microsoft.Extensions.Logging.LogLevel.Debug, and stderr at Microsoft.Extensions.Logging.LogLevel.Warning. A non-zero exit code throws a ProcessException by default so build steps fail fast without requiring callers to check exit codes manually.

Both stdout and stderr are fully captured into ProcessRunResult regardless of log level, so callers can inspect the full output even when logs are suppressed.

Constructors

ProcessRunOptions(string, string)

Immutable configuration for a single external-process execution through IProcessRunner.

public ProcessRunOptions(string Name, string Args)

Parameters

Name string

The name or path of the executable to run (e.g. "dotnet", "git").

Args string

The command-line arguments to pass to the executable as a pre-joined string.

Examples

Running a quiet, failure-tolerant invocation with a custom environment:

var options = new ProcessRunOptions("dotnet", ["build", "--configuration", configuration])
{
    WorkingDirectory = projectDirectory,
    InvocationLogLevel = LogLevel.Debug,
    AllowFailedResult = true,
    EnvironmentVariables = { ["DOTNET_NOLOGO"] = "1" },
};

Remarks

All properties have defaults suited to typical build-automation use: invocation is logged at Microsoft.Extensions.Logging.LogLevel.Information, stdout at Microsoft.Extensions.Logging.LogLevel.Debug, and stderr at Microsoft.Extensions.Logging.LogLevel.Warning. A non-zero exit code throws a ProcessException by default so build steps fail fast without requiring callers to check exit codes manually.

Both stdout and stderr are fully captured into ProcessRunResult regardless of log level, so callers can inspect the full output even when logs are suppressed.

ProcessRunOptions(string, string[])

Initializes a new instance of ProcessRunOptions from an array of argument tokens, joining them with a single space.

public ProcessRunOptions(string Name, string[] Args)

Parameters

Name string

The name or path of the executable to run.

Args string[]

An array of argument tokens. Empty and whitespace-only entries are removed before joining so that optional arguments can be passed as string.Empty without creating spurious spaces in the final argument string.

Properties

AllowFailedResult

Gets a value indicating whether a non-zero exit code should be tolerated rather than throwing an exception.

public bool AllowFailedResult { get; init; }

Property Value

bool

Remarks

When false (the default), Run(ProcessRunOptions) and RunAsync(ProcessRunOptions, CancellationToken) throw if the exit code is non-zero, which causes the enclosing build target to fail immediately.

Set to true when the caller needs to inspect the result regardless of success — for example, running a linter and deciding separately whether to fail the build. The caller must then check ExitCode explicitly.

Args

The command-line arguments to pass to the executable as a pre-joined string.

public string Args { get; init; }

Property Value

string

EnvironmentVariables

Gets the environment variables to inject into the process's environment.

public Dictionary<string, string?> EnvironmentVariables { get; init; }

Property Value

Dictionary<string, string>

Remarks

Keys are variable names and values are their string values. A null value removes the inherited variable from the child process's environment. Variables not listed here are inherited from the current process unchanged.

Only the variable names appear in the invocation log line (see InvocationLogLevel); their values are never logged.

ErrorLogLevel

Gets the log level used when streaming each line of the process's standard error.

public LogLevel ErrorLogLevel { get; init; }

Property Value

LogLevel

Remarks

Defaults to Microsoft.Extensions.Logging.LogLevel.Warning. Like OutputLogLevel, the full stderr is captured into Error irrespective of this value.

On a non-zero exit, when this level is below Microsoft.Extensions.Logging.LogLevel.Information, the complete captured stderr is additionally re-logged at Microsoft.Extensions.Logging.LogLevel.Warning so failure diagnostics remain visible.

InvocationLogLevel

Gets the log level used when logging the process invocation line (e.g. Run: dotnet build --configuration Release).

public LogLevel InvocationLogLevel { get; init; }

Property Value

LogLevel

Remarks

Defaults to Microsoft.Extensions.Logging.LogLevel.Information. Lower this to Microsoft.Extensions.Logging.LogLevel.Debug for noisy or frequently-called sub-processes.

The invocation line includes the full Args, the WorkingDirectory when set, and the names of any EnvironmentVariables. Environment variable values are never logged, so they are a safer way to pass secrets than command-line arguments. When a secret must be passed as an argument, lower this level (or set it to Microsoft.Extensions.Logging.LogLevel.None) to keep it out of the log.

Name

The name or path of the executable to run (e.g. "dotnet", "git").

public string Name { get; init; }

Property Value

string

OutputLogLevel

Gets the log level used when streaming each line of the process's standard output.

public LogLevel OutputLogLevel { get; init; }

Property Value

LogLevel

Remarks

Defaults to Microsoft.Extensions.Logging.LogLevel.Debug. The full stdout is still captured into Output regardless of this setting, so callers can inspect it even when debug logging is disabled. Set to Microsoft.Extensions.Logging.LogLevel.None to suppress stdout entirely from the log.

On a non-zero exit, when this level is below Microsoft.Extensions.Logging.LogLevel.Information, the complete captured stdout is additionally re-logged at Microsoft.Extensions.Logging.LogLevel.Information so failure diagnostics remain visible.

TransformError

Gets an optional per-line transformation applied to each line of the process's standard error before it is logged and captured.

public Func<string, string?>? TransformError { get; init; }

Property Value

Func<string, string>

Remarks

Behaves identically to TransformOutput but operates on stderr. Returning null suppresses the line from both the log and Error.

TransformOutput

Gets an optional per-line transformation applied to each line of the process's standard output before it is logged and captured.

public Func<string, string?>? TransformOutput { get; init; }

Property Value

Func<string, string>

Remarks

The delegate receives a raw non-null line (null data events are filtered before the delegate is called). Returning null suppresses the line entirely — it is neither logged nor included in Output. This is useful for filtering noisy progress lines or redacting secrets from captured output.

WorkingDirectory

Gets the working directory for the process execution.

public string? WorkingDirectory { get; init; }

Property Value

string

Remarks

When null (the default), the process inherits the current application's working directory. Set this when a tool must be run from a specific project or repository root.