Start ExternalProcess

Start-ExternalProcess

PPoShTools -> Start-ExternalProcess.ps1

Synopsis

Runs external process.

Syntax

Start-ExternalProcess [-Command] <String> [[-ArgumentList] <String>] 
[[-WorkingDirectory] <String>] [-CheckLastExitCode] [-ReturnLastExitCode] 
[-CheckStdErr] [[-FailOnStringPresence] <String>] [[-Credential] 
<PSCredential>] [[-Output] <PSReference>] [[-OutputStdErr] <PSReference>] 
[[-TimeoutInSeconds] <Int32>] [-Quiet] [-ReportOutputOnError] 
[[-IgnoreOutputRegex] <String>] [<CommonParameters>]

Description

Runs an external process with proper logging and error handling. It fails if anything is present in stderr stream or if exitcode is non-zero.

Parameters

-Command<String>

Command to run.

• PipelineInput: false
• Required: true

-ArgumentList<String>

ArgumentList for Command.

• PipelineInput: false
• Required: false

-WorkingDirectory<String>

Working directory. Leave empty for default.

• PipelineInput: false
• Required: false

-CheckLastExitCode<SwitchParameter> (default: True)

If true, exit code will be validated (if zero, an error will be thrown). If false, it will not be validated but returned as a result of the function.

• DefaultValue: True
• PipelineInput: false
• Required: false

-ReturnLastExitCode<SwitchParameter> (default: True)

If true, the cmdlet will return exit code of the invoked command. If false, the cmdlet will return nothing.

• DefaultValue: True
• PipelineInput: false
• Required: false

-CheckStdErr<SwitchParameter> (default: True)

If true and any output is present in stderr, an error will be thrown.

• DefaultValue: True
• PipelineInput: false
• Required: false

-FailOnStringPresence<String>

If not null and given string will be present in stdout, an error will be thrown.

• PipelineInput: false
• Required: false

-Credential<PSCredential>

If set, then $Command will be executed under $Credential account.

• PipelineInput: false
• Required: false

-Output<PSReference>

Reference parameter that will get STDOUT text.

• PipelineInput: false
• Required: false

-OutputStdErr<PSReference>

Reference parameter that will get STDERR text.

• PipelineInput: false
• Required: false

-TimeoutInSeconds<Int32> (default: 0)

Timeout to wait for external process to be finished.

• DefaultValue: 0
• PipelineInput: false
• Required: false

-Quiet<SwitchParameter> (default: False)

If true, no output from the command will be passed to the console.

• DefaultValue: False
• PipelineInput: false
• Required: false

-ReportOutputOnError<SwitchParameter> (default: True)

If true, STDOUT/STDERR will be displayed if error occurs (even if -Quiet is specified).

• DefaultValue: True
• PipelineInput: false
• Required: false

-IgnoreOutputRegex<String>

Each stdout/stderr line that match this regex will be ignored (not written to console/$output).

• PipelineInput: false
• Required: false

Examples

Example 1

Start-ExternalProcess -Command "git" -ArgumentList "--version"