Need help with ProcessX?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

Cysharp
134 Stars 9 Forks MIT License 35 Commits 1 Opened issues

Description

Simplify call an external process with the async streams in C# 8.0.

Services available

!
?

Need anything else?

Contributors list

GitHub Actions

ProcessX

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

Process
code. You can receive standard output results by
await foreach
, it is completely asynchronous and realtime.

image

Table of Contents

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
and throws
ProcessErrorException
when error detected.
  • 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
of IAsyncEnumerable.
// 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
with error messages after process exited. If you want to use stdError in streaming or avoid throws error when process using stderror as progress, diagnostics, you can use
GetDualAsyncEnumerable
method. Also
GetDualAsyncEnumerable
can get raw
Process
, you can use
ProcessID
,
StandardInput
etc.
// 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
to read
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
property. Default is
[0]
.

Reference

ProcessX.StartAsync
overloads, you can set workingDirectory, environmentVariable, encoding.
// 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

License

This library is under the MIT License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.