about_Throw
Short description
Describes the throw
keyword that generates a terminating error.
Long description
The throw
keyword causes a terminating error. You can use the throw
keyword
to stop the processing of a command, function, or script.
For example, you can use the throw
keyword in the script block of an if
statement to respond to a condition or in the catch
block of a
try
-catch
-finally
statement.
The throw
keyword can throw any object, such as a user message string or the
object that caused the error.
Syntax
The syntax of the throw
keyword is as follows:
throw [<expression>]
The expression in the throw
syntax is optional. When the throw
statement
doesn't appear in a catch
block, and it doesn't include an expression, it
generates a ScriptHalted error.
throw
ScriptHalted
At line:1 char:6
+ throw <<<<
+ CategoryInfo : OperationStopped: (:) [], RuntimeException
+ FullyQualifiedErrorId : ScriptHalted
If the throw
keyword is used in a catch
block without an expression, it
throws the current RuntimeException again. For more information, see
about_Try_Catch_Finally.
Throwing a string
The optional expression in a throw
statement can be a string, as shown in the
following example:
throw "This is an error."
This is an error.
At line:1 char:6
+ throw <<<< "This is an error."
+ CategoryInfo : OperationStopped: (This is an error.:String) [], R
untimeException
+ FullyQualifiedErrorId : This is an error.
Throwing other objects
The expression can also be an object that throws the object that represents the PowerShell process, as shown in the following example:
throw (Get-Process pwsh)
At line:1 char:6
+ throw <<<< (get-process PowerShell)
+ CategoryInfo : OperationStopped: (System.Diagnostics.Process (Pow
erShell):Process) [],
RuntimeException
+ FullyQualifiedErrorId : System.Diagnostics.Process (PowerShell)
You can use the TargetObject property of the ErrorRecord object in the
$Error
automatic variable to examine the error.
$Error[0].TargetObject
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
319 26 61016 70864 568 3.28 5548 PowerShell
You can also throw
an ErrorRecord object or a .NET exception. The
following example uses the throw
keyword to throw a
System.FormatException object.
$formatError = New-Object System.FormatException
throw $formatError
One of the identified items was in an invalid format.
At line:1 char:6
+ throw <<<< $formatError
+ CategoryInfo : OperationStopped: (:) [], FormatException
+ FullyQualifiedErrorId : One of the identified items was in an invalid
format.
The resulting error
The throw
keyword can generate an ErrorRecord object. The Exception
property of the ErrorRecord object contains a RuntimeException object.
The remainder of the ErrorRecord object and the RuntimeException object
varies depending on the object thrown.
The throw
object is wrapped in an ErrorRecord object, and the ErrorRecord
object is automatically saved in the $Error
automatic variable.
Using throw
to create a mandatory parameter
Unlike past versions of PowerShell, don't use the throw
keyword for parameter
validation. See
about_Functions_Advanced_Parameters
for the correct way.