CreativeCoders.ProcessUtils 6.8.0

CreativeCoders.ProcessUtils

A small .NET library for running external processes from C# code. It wraps System.Diagnostics.Process behind a testable abstraction and adds a fluent executor with sync/async APIs, argument placeholders, output parsing and opt-in error handling.

Installation

dotnet add package CreativeCoders.ProcessUtils

Features

• Testable process abstraction — IProcess / IProcessFactory wrap System.Diagnostics.Process
• Fluent executor builder — configure file name, arguments, ProcessStartInfo and error behavior in one chain
• Sync and async execution — Execute, ExecuteAsync, ExecuteAndReturnExitCode(Async)
• Typed output parsing — IProcessOutputParser<T> with PassThrough, SplitLines and Json<T> parsers
• Argument placeholders — substitute {{name}} tokens from a dictionary or an object's properties
• Throw-on-error mode — surface non-zero exit codes as ProcessExecutionFailedException
• DI integration — single AddProcessUtils() registration for IServiceCollection

Usage

Register the services

using CreativeCoders.ProcessUtils;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddProcessUtils();

This registers:

• IProcessFactory → DefaultProcessFactory (singleton)
• IProcessExecutorBuilder and IProcessExecutorBuilder<T> (transient)

Start a process directly

For low-level scenarios, inject IProcessFactory:

public class GitCaller(IProcessFactory processFactory)
{
    public void ShowStatus()
    {
        using var process = processFactory.StartProcess("git", ["status"]);
        process.WaitForExit();
    }
}

Execute a process and get the exit code

IProcessExecutorBuilder provides a non-generic, fluent builder for fire-and-forget execution:

public class Pinger(IProcessExecutorBuilder builder)
{
    public int Ping(string host)
    {
        var executor = builder
            .SetFileName("ping")
            .SetArguments(["-c", "1", host])
            .Build();

        return executor.ExecuteAndReturnExitCode();
    }
}

Async variants are available for every execution method:

var exitCode = await executor.ExecuteAndReturnExitCodeAsync();

Capture and parse output

IProcessExecutorBuilder<T> adds typed output parsing. Several parsers are shipped in CreativeCoders.ProcessUtils.Execution.Parsers:

public class DotnetSdks(IProcessExecutorBuilder<string[]> builder)
{
    public string[] List()
    {
        var executor = builder
            .SetFileName("dotnet")
            .SetArguments(["--list-sdks"])
            .SetOutputParser<SplitLinesOutputParser>(p => p.TrimLines = true)
            .Build();

        return executor.Execute() ?? [];
    }
}

Returning a plain string does not require an explicit parser:

var output = builder
    .SetFileName("uname")
    .SetArguments(["-a"])
    .Build()
    .Execute();

For JSON output:

var executor = builder
    .SetFileName("kubectl")
    .SetArguments(["get", "pods", "-o", "json"])
    .SetOutputParser<JsonOutputParser<PodList>>()
    .Build();

var pods = await executor.ExecuteAsync();

Argument placeholders

Arguments can contain {{name}} placeholders that are replaced at execution time. Pass either an IDictionary<string, object?> or any object whose properties match the placeholder names:

var executor = builder
    .SetFileName("git")
    .SetArguments(["clone", "{{url}}", "{{target}}"])
    .Build();

executor.Execute(new Dictionary<string, object?>
{
    ["url"] = "https://github.com/CreativeCodersTeam/Core.git",
    ["target"] = "./Core"
});

executor.Execute(new { url = "https://...", target = "./Core" });

Error handling

By default the executor returns whatever exit code the process produced. Enable ShouldThrowOnError to turn non-zero exit codes into a ProcessExecutionFailedException that carries the captured stderr:

try
{
    builder
        .SetFileName("dotnet")
        .SetArguments(["build", "Missing.sln"])
        .ShouldThrowOnError()
        .Build()
        .Execute();
}
catch (ProcessExecutionFailedException ex)
{
    Console.WriteLine($"Exit {ex.ExitCode}: {ex.ErrorOutput}");
}

Customizing ProcessStartInfo

For advanced scenarios (working directory, environment variables, redirection flags) use SetupStartInfo:

builder
    .SetFileName("npm")
    .SetArguments(["install"])
    .SetupStartInfo(info =>
    {
        info.WorkingDirectory = "/repo";
        info.Environment["CI"] = "true";
    })
    .Build()
    .Execute();

Accessing the underlying IProcess

The ExecuteEx family returns the underlying IProcess (non-generic) or a ProcessExecutionResult<T> (generic) so callers can inspect exit codes, process metadata, or read raw streams. Both results are IDisposable:

using var result = builder
    .SetFileName("git")
    .SetArguments(["rev-parse", "HEAD"])
    .Build()
    .ExecuteEx();

Console.WriteLine($"git exited with {result.ExitCode}");

API Overview