About
Bud.Exec is a wrapper around the System.Diagnostics.Process
API. Bud.Exec provides a number of static methods for executing processes. Bud.Exec's API has been inspired by Python's subprocess functions.
Usage
All the API is contained in the Bud.Exec
static class. You can import this class statically for brevity:
using static Bud.Exec;
Run
method
Run
is the most general method in the Bud.Exec
API. All other methods in Bud.Exec
delegate to it.
Here's the simplest way to use Run
:
var process = Run("git", "status");
The Run
method returns an object of type System.Diagnostics.Process
. The process will have terminated before this method returns. You can get the exit code via process.ExitCode
.
Note that by default the Run
method pipes standard output and standard error to the standard output and standard error of the parent process. You can change this behaviour by passing stdout
and stderr
parameters to the Run
method:
var stdout = new StringWriter();
var stderr = new StringWriter();
var process = Run("git", "status", stdout: stdout, stderr: stderr);
Console.WriteLine($"stdout: {stdout.ToString}, stderr: {stderr.ToString()}");
Call
method
You can also use Call
to suppress all output:
var process = Call("git", "status");
Args
and Arg
methods
If your arguments contain spaces or double-quotation marks, you can use the Args
or Arg
methods.
You can use the Args
method to generate the arguments string from a list of strings:
Run("git", Args("commit", "-m", "This message contains \" and spaces."));
You can also use the Args
and Arg
method inside a string:
Run("git", $"--git-dir {Arg(gitDir)} --work-tree {Arg(workDir)} add {Args(filesList)}");
CheckCall
and CheckOutput
methods
CheckCall
and CheckOutput
methods throw exceptions if the process returns with a non-zero exit code.
CheckCall
suppresses the output of the invoked process. It also returns the Process
object. Here's an example of how to use the CheckCall
method:
try {
CheckCall("git", "status");
} catch (ExecException ex) {
Console.WriteLine(ex.Message);
}
CheckOutput
returns the string containing the captured standard output of the process. The error output of the process will end up in the exception if the process fails. Here's how you can use the CheckOutput
method:
try {
var gitStatus = CheckOutput("git", "status");
Console.WriteLine($"Git status: {gitStatus}");
} catch (ExecException ex) {
Console.WriteLine(ex.Message);
}
Note: the Message
property contains a great deal of information about the failed process, such as the path of the executable, the arguments passed to it, the working directory of the process, the exit code, and the error output of the process.
Working directory
All process execution methods in the Bud.Exec
API take the cwd
parameter. This parameter is optional and sets the working directory in which the executed process will run. Here's an example of how to use it:
CheckCall("git", "status", cwd: "/foo/bar");
Environment variables
All process execution methods in the Bud.Exec
API take the env
parameter. This parameter is optional and sets the environment variables of the executed process. Here's an example of how to use it:
CheckCall("git", "status", env: EnvCopy(EnvVar("FOO_BAR", "42")));
The example above creates a copy of the environment of the current process and adds the variable FOO_BAR
to it.
Standard input
All process execution methods in the Bud.Exec
API take the stdin
parameter. This parameter is optional and passes some input to the executed process. Here's an example of how to use it:
var stdin = new StringReader("this is sparta\n");
CheckCall("hello-world", stdin: stdin);