ProcessKit API Reference
ProcessRunnerExtensions Type
The full run-verb vocabulary on *any* `IProcessRunner`, layered over the three-method seam (`CaptureStringAsync`/`CaptureBytesAsync`/`SpawnAsync`). So a chosen or injected runner — a shared `ProcessGroup`, a `ScriptedRunner`, a `JobRunner` — gets `run`/`exitCode`/`probe`/`parse`/… uniformly (`group.RunAsync command`, `scripted.ProbeAsync command`), callable from F# and C#. The verb *logic* lives once in the `Runner` module; these are thin sugar over it. Retry contract: every capture verb here applies the command's `Retry` policy (it routes through the `Runner` module). The `cancellationToken` is optional and defaults to `CancellationToken.None`, so `runner.RunAsync command` and `runner.RunAsync(command, ct)` are the same method and retry identically. (Because the seam primitives are named `Capture*`/`Spawn`, the verb names never collide with them, so adding a token can't silently bypass retry.) For a raw, single, no-retry capture call the seam primitive directly: `runner.CaptureStringAsync(command, ct)`. Streaming verbs (`StartAsync`/`FirstLineAsync`) never retry.
Static members
| Static member |
Description
|
Full Usage:
ProcessRunnerExtensions.ExitCodeAsync(runner, command, ?cancellationToken)
Parameters:
IProcessRunner
command : Command
?cancellationToken : CancellationToken
Returns: Task<Result<int, ProcessError>>
|
The exit code; a signal kill or timeout errors instead of inventing a sentinel.
|
Full Usage:
ProcessRunnerExtensions.FirstLineAsync(runner, command, predicate, ?cancellationToken)
Parameters:
IProcessRunner
command : Command
predicate : Func<string, bool>
?cancellationToken : CancellationToken
Returns: Task<Result<string option, ProcessError>>
|
The first stdout line satisfying `predicate`, or `None` if stdout closes without a match.
|
Full Usage:
ProcessRunnerExtensions.OutputBytesAsync(runner, command, ?cancellationToken)
Parameters:
IProcessRunner
command : Command
?cancellationToken : CancellationToken
Returns: Task<Result<ProcessResult<byte[]>, ProcessError>>
|
Run to completion, capturing stdout as raw bytes (a non-zero exit is data). Applies the command's `Retry` policy; the raw seam `runner.CaptureBytesAsync(command, ct)` is the no-retry path.
|
Full Usage:
ProcessRunnerExtensions.OutputJsonAsync(runner, command, ?options, ?cancellationToken)
Parameters:
IProcessRunner
command : Command
?options : JsonSerializerOptions
?cancellationToken : CancellationToken
Returns: Task<Result<'T, ProcessError>>
Type parameters: 'T |
Require a zero/accepted exit and deserialize the trimmed stdout as JSON into a `'T` via `System.Text.Json` (`options` omitted uses the BCL defaults); invalid JSON becomes `ProcessError.Parse`, just like `ParseAsync`. Give an explicit type argument — there is no parser argument to infer `'T` from. **Trimming / AOT:** deserializes via reflection-based `System.Text.Json` (`JsonSerializer.Deserialize(string, Type, JsonSerializerOptions)`), so it is not trim-/AOT-safe — pass `options` with a source-generated `JsonSerializerContext`/`JsonTypeInfo<'T>` resolver, or avoid this verb, in a trimmed/NativeAOT app.
|
Full Usage:
ProcessRunnerExtensions.OutputStringAsync(runner, command, ?cancellationToken)
Parameters:
IProcessRunner
command : Command
?cancellationToken : CancellationToken
Returns: Task<Result<ProcessResult<string>, ProcessError>>
|
Run to completion, capturing stdout as decoded text (a non-zero exit is data). Applies the command's `Retry` policy; for a single raw capture with no retry, call the seam primitive directly: `runner.CaptureStringAsync(command, ct)`.
|
Full Usage:
ProcessRunnerExtensions.ParseAsync(runner, command, parser, ?cancellationToken)
Parameters:
IProcessRunner
command : Command
parser : Func<string, 'T>
?cancellationToken : CancellationToken
Returns: Task<Result<'T, ProcessError>>
Type parameters: 'T |
Require a zero/accepted exit and parse the trimmed stdout into a `'T`; a thrown parser error becomes `ProcessError.Parse`.
|
Full Usage:
ProcessRunnerExtensions.ProbeAsync(runner, command, ?cancellationToken)
Parameters:
IProcessRunner
command : Command
?cancellationToken : CancellationToken
Returns: Task<Result<bool, ProcessError>>
|
Read the exit code as a yes/no answer: 0 -> true, 1 -> false, anything else errors.
|
Full Usage:
ProcessRunnerExtensions.RunAsync(runner, command, ?cancellationToken)
Parameters:
IProcessRunner
command : Command
?cancellationToken : CancellationToken
Returns: Task<Result<string, ProcessError>>
|
Require a zero/accepted exit and return stdout, trailing whitespace trimmed.
|
Full Usage:
ProcessRunnerExtensions.RunUnitAsync(runner, command, ?cancellationToken)
Parameters:
IProcessRunner
command : Command
?cancellationToken : CancellationToken
Returns: Task<Result<unit, ProcessError>>
|
Require a zero/accepted exit, discarding the captured output.
|
Full Usage:
ProcessRunnerExtensions.StartAsync(runner, command, ?cancellationToken)
Parameters:
IProcessRunner
command : Command
?cancellationToken : CancellationToken
Returns: Task<Result<RunningProcess, ProcessError>>
|
Start the command and return a live `RunningProcess`. Forwards to the runner's `SpawnAsync` seam. `cancellationToken` is checked once, before the spawn (an already-cancelled token reports `ProcessError.Cancelled` and starts nothing); after the child is running neither it nor the command's `CancelOn` token is tracked — drive and cancel the live handle yourself (dispose it or call its `Kill`). The completion verbs, by contrast, watch the token for the whole run.
|
Full Usage:
ProcessRunnerExtensions.TryParseAsync(runner, command, parser, ?cancellationToken)
Parameters:
IProcessRunner
command : Command
parser : TryParser<'T>
?cancellationToken : CancellationToken
Returns: Task<Result<'T, ProcessError>>
Type parameters: 'T |
Like `ParseAsync`, but with the standard .NET try-parse shape: pass a BCL parser like `int.TryParse` with an explicit type argument (`TryParseAsync<int>(int.TryParse)` — needed because BCL `TryParse` is overloaded). A `false` return becomes `ProcessError.Parse`. (F# can use the `Result`-returning `Runner.tryParse`.)
|