Exec 2.22.0

A .NET library for executing subprocess commands

Installation

Install from NuGet:

dotnet add package Exec

This library supports .NET 5 and later versions.

Usage

Basic usage

The simplest way to execute a command:

var result = await Exec.RunAsync("echo hello");
Assert.Contains("hello", result.Output);

That's it! The library provides static methods on the Exec class with the following APIs:

Task<ExecResult> RunAsync(string command, CancellationToken cancellationToken = default)

Task<ExecResult> RunAsync(string command, ExecOption option, CancellationToken cancellationToken = default)

Configuration

Use ExecOption to customize behavior beyond the defaults:

Result

ExecResult provides the following information:

Cancellation behavior

The library handles cancellation differently based on the source:

• Timeout (via ExecOption.Timeout): Returns ExecResult with WasCancelled = true
• CancellationToken: Throws OperationCanceledException (or TaskCanceledException)

This allows timeout scenarios to be handled gracefully while external cancellations propagate as exceptions.

Advanced usage

Execute PowerShell commands

var option = new ExecOption
{
    Shell = "pwsh",
    ShellParameter = "",
    ShellExtension = ".ps1"
};

var command = @"function Test-Add {
    [CmdletBinding()]
    param (
        [int]$Val1,
        [int]$Val2
    )

    Write-Output $($Val1 + $Val2)
}

Test-Add 10 12";

var result = await Exec.RunAsync(command, option);
Assert.Equal(0, result.ExitCode);
Assert.Contains("22", result.Output);

Execute commands with timeout

When using a timeout, the command returns a result with WasCancelled = true:

var option = new ExecOption
{
    Timeout = TimeSpan.FromSeconds(3)
};

// Note: On Windows, use 'ping' instead of 'timeout' because timeout.exe doesn't work with redirected stdin
var result = await Exec.RunAsync("ping 127.0.0.1 -n 60", option);

// Process was terminated due to timeout
Assert.True(result.WasCancelled);
Assert.NotEqual(0, result.ExitCode);

Stream stdout and stderr asynchronously

var output = new StringBuilder();
var option = new ExecOption
{
    IsStreamed = true,
    OutputDataReceivedHandler = async (line) =>
    {
        output.AppendLine(line);
        await Task.CompletedTask;
    }
};

var result = await Exec.RunAsync(@"echo hello
echo hello2
echo hello3", option);

Assert.Equal(0, result.ExitCode);
Assert.Empty(result.Output); // Output is empty in streaming mode

var capturedOutput = output.ToString();
Assert.Contains("hello", capturedOutput);
Assert.Contains("hello2", capturedOutput);
Assert.Contains("hello3", capturedOutput);

Use cancellation tokens

When using a cancellation token, the operation throws OperationCanceledException:

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

try
{
    var result = await Exec.RunAsync("long-running-command", cts.Token);
}
catch (OperationCanceledException)
{
    // Command was cancelled via the cancellation token
}

Known limitations

• Windows timeout command: The Windows timeout.exe command doesn't work because it requires interactive input and fails with redirected stdin. Use ping 127.0.0.1 -n <seconds> as an alternative for delays.

Versioning

This project uses automated semantic versioning. The major version is defined in the VERSION file, and the minor version is automatically incremented on each release. See VERSIONING.md for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT