Class: RT.Util.CommandRunner

Assembly: RT.Util.Core, Version=1.0.0.9999, Culture=neutral, PublicKeyToken=null
Namespace: RT.Util
Show inherited types...
Inherits from:
- object

Summary

Provides features to execute cmd.exe commands in a hidden window and retrieve their output. This class is geared heavily towards executing console programs, batch files and console scripts, but can also execute built-in commands and non-console programs. Because the command goes through cmd.exe, the PATH, PATHEXT and file associations are all automatically taken care of.

Remarks

When the command completes, whether by exiting naturally or by being aborted, the CommandRunner.State changes first. Then the CommandRunner.CommandEnded event fires. Finally, the CommandRunner.EndedWaitHandle is signalled. By the time the CommandRunner.State has changed to CommandRunnerState.Exited, it is guaranteed that all the output has been processed and the CommandRunner.ExitCode can be retrieved.

This class is thread-safe: all public members may be used from any thread.

Constructors

CommandRunner()

Creates a new instance of CommandRunner.

Instance methods

void	Abort()	Aborts the command by killing the process and all its children, if any. Throws if the command has not been started yet. Does nothing if the command has already ended. See Remarks. (see also remarks)
void	Pause(TimeSpan? duration = null)	Pauses the command for the specified duration by suspending every thread in every process in the process tree. Throws if the command hasn't been started or has been aborted. Does nothing if the command has exited. If called when already paused, will make sure the command is paused for at least the specified duration, but will not shorten the resume timer. See Remarks. (see also remarks)
void	ResumePaused()	Resumes the command after it has been paused. If the command was paused with a timeout, the timer is cleared. Throws if the command has not been started yet or has been aborted. Does nothing if the command is not paused.
void	SetCommand(IEnumerable<string> args)	Sets the CommandRunner.Command property by combining and escaping all arguments in such a way that a program parsing them with standard Windows tools will receive the exact strings passed in. Null values are allowed and are filtered out. The first value is escaped as a path to an executable and all others as parameters. Thus it is not possible to use this method to construct arguments that are handled specially by cmd.exe such as redirects, pipes and environment variable expansions. (see also remarks)
void	SetCommand(params string[] args)
void	Start(byte[] stdin = null)	Starts the command with all the settings as configured.
void	StartAndWait(byte[] stdin = null)	Starts the command with all the settings as configured. Does not return until the command exits.

Static methods

string	ArgsToCmdExeLine(params string[] args)	Escapes the arguments (while skipping nulls) for use with cmd.exe. The first argument is escaped as a filepath to an executable or a script, and the rest as arguments.
string	ArgsToCmdExeLine(IEnumerable<string> args)
string	ArgsToCommandLine(params string[] args)	See CommandRunner.ArgsToCommandLine(IEnumerable<string>).
string	ArgsToCommandLine(IEnumerable<string> args)	Given a number of argument strings, constructs a single command line string with all the arguments escaped correctly so that a process using standard Windows API for parsing the command line will receive exactly the strings passed in here. See Remarks. (see also remarks)
string	EscapeCmdExeMetachars(string command)	Escapes all cmd.exe meta-characters by prefixing them with a ^. See CommandRunner.ArgsToCommandLine(IEnumerable<string>) for more information.
FluidCommandRunner	Run(params string[] args)	Executes the specified command using a fluid syntax. Use method chaining to configure any options, then invoke FluidCommandRunner.Go() (or one of its variants) to execute the command. See Remarks. (see also remarks)
FluidCommandRunner	RunRaw(string command)

Instance properties

bool	CaptureEntireStderr	Specifies whether the entire stderr output should be captured. This can consume large amounts of memory, and so defaults to `false`.
bool	CaptureEntireStdout	Specifies whether the entire stdout output should be captured. This can consume large amounts of memory, and so defaults to `false`.
string	Command	The raw command to be executed, as a single string. Any command supported by cmd.exe is permitted. See also CommandRunner.SetCommand(params string[]), which simplifies running commands with spaces and/or arguments. Once the command has been started, this property becomes read-only and indicates the value in effect at the time of starting. See Remarks.
WaitHandle	EndedWaitHandle	Exposes a waitable flag indicating whether the command has ended, either by exiting naturally or by being aborted. See also Remarks on CommandRunner. (see also remarks)
byte[]	EntireStderr	Gets the entire stderr output produced by the program. This property can only be accessed once the command has ended (exited or aborted), and only if CommandRunner.CaptureEntireStderr is `true`. You may modify the returned array, but subsequent invocations will then return the modified array. The relative interleaving of stdout and stderr is not preserved in this property.
byte[]	EntireStdout	Gets the entire stdout output produced by the program. This property can only be accessed once the command has ended (exited or aborted), and only if CommandRunner.CaptureEntireStdout is `true`. You may modify the returned array, but subsequent invocations will then return the modified array. The relative interleaving of stdout and stderr is not preserved in this property.
IDictionary<string, string>	EnvironmentVariables	Overrides for the environment variables to be set for the command process. These overrides are in addition to the variables inherited from the current process.
int	ExitCode	Gets the exit code returned by the command. If the command has not started or exited yet, or has been aborted, this method will throw an InvalidOperationException.
DateTime?	PausedUntil	Gets the time at which the command will wake up again, `DateTime.MaxValue` if the command is paused indefinitely, or null if the command is not paused.
RunAsUserParams	RunAsUser	Credentials and parameters used to run the command as a different user. Null to run as the same user as the current process. Once the command has been started, this property becomes read-only and indicates the value in effect at the time of starting.
CommandRunnerState	State	Indicates the current state of the runner. Some properties are only readable and/or writable in specific states. Note that this property is not guaranteed to reflect whether the actual command is running or not, or whether a call to CommandRunner.Abort() resulted in the command of being terminated; rather, this is the logical state of the CommandRunner itself.
string	WorkingDirectory	The working directory to be used when starting the command. Once the command has been started, this property becomes read-only and indicates the value in effect at the time of starting.

Events

Action	CommandEnded	Raised once the command ends (that is, exits naturally or is aborted) and all the clean-up has completed. See Remarks. (see also remarks)
Action	CommandResumed	Raised whenever the command execution resumes after it was paused. This includes manual calls to CommandRunner.ResumePaused().
Action<byte[]>	StderrData	Raised whenever the command has produced new output on stderr (but no more often than about once in 50ms).
Action<string>	StderrText	Same as CommandRunner.StdoutText but for stderr.
Action<byte[]>	StdoutData	Raised whenever the command has produced new output on stdout (but no more often than about once in 50ms).
Action<string>	StdoutText	Raised whenever the command has produced new text on stdout. For ASCII outputs, this is identical to CommandRunner.StdoutData, however utf8-encoded text is guaranteed to correctly handle the possibility that part of a character's encoding has not been output yet. Other encodings are not supported.