ProcessX

ProcessX simplifies call an external process with the aync streams in C# 8.0 without complex

Process

await foreach

Table of Contents

• Getting Started
• Cancellation
• Raw Process/StdError Stream
• Read Binary Data
• Change acceptable exit codes
• Reference
• Competitor
• License

Getting Started

Install library from NuGet that support from

.NET Standard 2.0

PM> Install-Package ProcessX

Main API is only

Cysharp.Diagnostics.ProcessX.StartAsync

ProcessErrorException

• Simple, only write single string command like the shell script.
• Asynchronous, by C# 8.0 async streams.
• Manage Error, handling exitcode and stderror.

using Cysharp.Diagnostics; // using namespace

// async iterate.
await foreach (string item in ProcessX.StartAsync("dotnet --info"))
{
    Console.WriteLine(item);
}
// receive buffered result(similar as WaitForExit).
string[] result = await ProcessX.StartAsync("dotnet --info").ToTask();
// like the shell exec, write all data to console.
await ProcessX.StartAsync("dotnet --info").WriteLineAllAsync();
// when ExitCode is not 0 or StandardError is exists, throws ProcessErrorException
try
{
    await foreach (var item in ProcessX.StartAsync("dotnet --foo --bar")) { }
}
catch (ProcessErrorException ex)
{
    // int .ExitCode
    // string[] .ErrorOutput
    Console.WriteLine(ex.ToString());
}

Cancellation

to Cancel, you can use

WithCancellation

// when cancel has been called and process still exists, call process kill before exit.
await foreach (var item in ProcessX.StartAsync("dotnet --info").WithCancellation(cancellationToken))
{
    Console.WriteLine(item);
}

timeout, you can use

CancellationTokenSource(delay)

using (var cts = new CancellationTokenSource(TimeSpan.FromSeconds(1)))
{
    await foreach (var item in ProcessX.StartAsync("dotnet --info").WithCancellation(cts.Token))
    {
        Console.WriteLine(item);
    }
}

Raw Process/StdError Stream

In default, when stdError is used, buffering error messages and throws

ProcessErrorException

GetDualAsyncEnumerable

GetDualAsyncEnumerable

Process

ProcessID

StandardInput

// first argument is Process, if you want to know ProcessID, use StandardInput, use it.
var (_, stdOut, stdError) = ProcessX.GetDualAsyncEnumerable("dotnet --foo --bar");

var consumeStdOut = Task.Run(async () =>
{
    await foreach (var item in stdOut)
    {
        Console.WriteLine("STDOUT: " + item);
    }
});
var errorBuffered = new List();
var consumeStdError = Task.Run(async () =>
{
    await foreach (var item in stdError)
    {
        Console.WriteLine("STDERROR: " + item);
        errorBuffered.Add(item);
    }
});
try
{
    await Task.WhenAll(consumeStdOut, consumeStdError);
}
catch (ProcessErrorException ex)
{
    // stdout iterator throws exception when exitcode is not 0.
    Console.WriteLine("ERROR, ExitCode: " + ex.ExitCode);
// ex.ErrorOutput is empty, if you want to use it, buffer yourself.
// Console.WriteLine(string.Join(Environment.NewLine, errorBuffered));
}

Read Binary Data

If stdout is binary data, you can use

StartReadBinaryAsync

byte[]

byte[] bin = await ProcessX.StartReadBinaryAsync($"...");

Change acceptable exit codes

In default, ExitCode is not 0 throws ProcessErrorException. You can change acceptable exit codes globally by

ProcessX.AcceptableExitCodes

[0]

Reference

ProcessX.StartAsync

// return ProcessAsyncEnumerable
StartAsync(string command, string? workingDirectory = null, IDictionary? environmentVariable = null, Encoding? encoding = null)
StartAsync(string fileName, string? arguments, string? workingDirectory = null, IDictionary? environmentVariable = null, Encoding? encoding = null)
StartAsync(ProcessStartInfo processStartInfo)

// return (Process, ProcessAsyncEnumerable, ProcessAsyncEnumerable)
GetDualAsyncEnumerable(string command, string? workingDirectory = null, IDictionary? environmentVariable = null, Encoding? encoding = null)
GetDualAsyncEnumerable(string fileName, string? arguments, string? workingDirectory = null, IDictionary? environmentVariable = null, Encoding? encoding = null)
GetDualAsyncEnumerable(ProcessStartInfo processStartInfo)
// return Task
StartReadBinaryAsync(string command, string? workingDirectory = null, IDictionary? environmentVariable = null, Encoding? encoding = null)
StartReadBinaryAsync(string fileName, string? arguments, string? workingDirectory = null, IDictionary? environmentVariable = null, Encoding? encoding = null)
StartReadBinaryAsync(ProcessStartInfo processStartInfo)
// return Task
ToTask(CancellationToken cancellationToken = default)
// return Task
WriteLineAllAsync(CancellationToken cancellationToken = default)

Competitor

• Tyrrrz/CliWrap - Wrapper for command line interfaces.
• jamesmanning/RunProcessAsTask - Simple wrapper around System.Diagnostics.Process to expose it as a System.Threading.Tasks.Task.

License

This library is under the MIT License.