Class ProcessRunner

Provides methods to help create external processes, and efficiently capture the standard error and standard output streams.

Inheritance

Object

ProcessRunner

Inherited Members

Object.ToString()

Object.Equals(Object)

Object.Equals(Object, Object)

Object.ReferenceEquals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Namespace: Swan

Syntax

public static class ProcessRunner

Methods

GetProcessEncodedOutputAsync(String, String, Encoding, CancellationToken)

Runs the process asynchronously and if the exit code is 0, returns all of the standard output text. If the exit code is something other than 0 it returns the contents of standard error. This method is meant to be used for programs that output a relatively small amount of text using a different encoder.

Declaration

public static Task<string> GetProcessEncodedOutputAsync(string filename, string arguments = "", Encoding encoding = null, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
String	filename	The filename.
String	arguments	The arguments.
Encoding	encoding	The encoding.
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task<String>	The type of the result produced by this Task.

GetProcessOutputAsync(String, String, String, CancellationToken)

Runs the process asynchronously and if the exit code is 0, returns all of the standard output text. If the exit code is something other than 0 it returns the contents of standard error. This method is meant to be used for programs that output a relatively small amount of text.

Declaration

public static Task<string> GetProcessOutputAsync(string filename, string arguments = "", string workingDirectory = null, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
String	filename	The filename.
String	arguments	The arguments.
String	workingDirectory	The working directory.
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task<String>	The type of the result produced by this Task.

Examples

The following code explains how to run an external process using the GetProcessOutputAsync(String, String, String, CancellationToken) method.

class Example
{
    using System.Threading.Tasks;
    using Swan;

    static async Task Main()
    {
        // execute a process and save its output
         var data = await ProcessRunner.
         GetProcessOutputAsync("dotnet", "--help");

        // print the output
        data.WriteLine();
    }
}

GetProcessResultAsync(String, String, String, Encoding, CancellationToken)

Executes a process asynchronously and returns the text of the standard output and standard error streams along with the exit code. This method is meant to be used for programs that output a relatively small amount of text.

Declaration

public static Task<ProcessResult> GetProcessResultAsync(string filename, string arguments, string workingDirectory, Encoding encoding = null, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
String	filename	The filename.
String	arguments	The arguments.
String	workingDirectory	The working directory.
Encoding	encoding	The encoding.
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task<ProcessResult>	Text of the standard output and standard error streams along with the exit code as a ProcessResult instance.

Examples

The following code describes how to run an external process using the GetProcessResultAsync(String, String, String, Encoding, CancellationToken) method.

class Example
{
    using System.Threading.Tasks;
    using Swan;

    static async Task Main()
    {
        // Execute a process asynchronously
        var data = await ProcessRunner.GetProcessResultAsync("dotnet", "--help");

        // print out the exit code
        $"{data.ExitCode}".WriteLine();

        // print out the output
        data.StandardOutput.WriteLine();
        // and the error if exists
        data.StandardError.Error();
    }
}

Exceptions

Type	Condition
ArgumentNullException	filename.

GetProcessResultAsync(String, String, CancellationToken)

Executes a process asynchronously and returns the text of the standard output and standard error streams along with the exit code. This method is meant to be used for programs that output a relatively small amount of text.

Declaration

public static Task<ProcessResult> GetProcessResultAsync(string filename, string arguments = "", CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
String	filename	The filename.
String	arguments	The arguments.
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task<ProcessResult>	Text of the standard output and standard error streams along with the exit code as a ProcessResult instance.

Exceptions

Type	Condition
ArgumentNullException	filename.

RunProcessAsync(String, String, ProcessRunner.ProcessDataReceivedCallback, ProcessRunner.ProcessDataReceivedCallback, Boolean, CancellationToken)

Runs an external process asynchronously, providing callbacks to capture binary data from the standard error and standard output streams. The callbacks contain a reference to the process so you can respond to output or error streams by writing to the process' input stream. The exit code (return value) will be -1 for forceful termination of the process.

Declaration

public static Task<int> RunProcessAsync(string filename, string arguments, ProcessRunner.ProcessDataReceivedCallback onOutputData, ProcessRunner.ProcessDataReceivedCallback onErrorData, bool syncEvents = true, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
String	filename	The filename.
String	arguments	The arguments.
ProcessRunner.ProcessDataReceivedCallback	onOutputData	The on output data.
ProcessRunner.ProcessDataReceivedCallback	onErrorData	The on error data.
Boolean	syncEvents	if set to true the next data callback will wait until the current one completes.
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task<Int32>	Value type will be -1 for forceful termination of the process.

Examples

The following example illustrates how to run an external process using the RunProcessAsync(String, String, ProcessRunner.ProcessDataReceivedCallback, ProcessRunner.ProcessDataReceivedCallback, Boolean, CancellationToken) method.

class Example
{
    using System.Diagnostics;
    using System.Text;
    using System.Threading.Tasks;
    using Swan;

    static async Task Main()
    {
        // Execute a process asynchronously 
        var data = await ProcessRunner
        .RunProcessAsync("dotnet", "--help", Print, Print);

        // flush all messages
        Terminal.Flush();
    }

    // a callback to print both output or errors
    static void Print(byte[] data, Process proc) =>
        Encoding.GetEncoding(0).GetString(data).WriteLine();
}

RunProcessAsync(String, String, String, ProcessRunner.ProcessDataReceivedCallback, ProcessRunner.ProcessDataReceivedCallback, Encoding, Boolean, CancellationToken)

Runs an external process asynchronously, providing callbacks to capture binary data from the standard error and standard output streams. The callbacks contain a reference to the process so you can respond to output or error streams by writing to the process' input stream. The exit code (return value) will be -1 for forceful termination of the process.

Declaration

public static Task<int> RunProcessAsync(string filename, string arguments, string workingDirectory, ProcessRunner.ProcessDataReceivedCallback onOutputData, ProcessRunner.ProcessDataReceivedCallback onErrorData, Encoding encoding, bool syncEvents = true, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
String	filename	The filename.
String	arguments	The arguments.
String	workingDirectory	The working directory.
ProcessRunner.ProcessDataReceivedCallback	onOutputData	The on output data.
ProcessRunner.ProcessDataReceivedCallback	onErrorData	The on error data.
Encoding	encoding	The encoding.
Boolean	syncEvents	if set to true the next data callback will wait until the current one completes.
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task<Int32>	Value type will be -1 for forceful termination of the process.

Comments