Muokkaa

Jaa

about_Throw

Short description

Describes the throw keyword, which generates a script-terminating error by default.

Long description

The throw keyword causes a script-terminating error by default. You can use the throw keyword to stop the processing of a command, function, or script.

Unlike statement-terminating errors, the throw keyword unwinds the entire call stack. Execution stops completely unless the error is caught by a try/catch block or trap statement.

Note

$ErrorActionPreference can suppress throw. When set to SilentlyContinue or Ignore, the error doesn't propagate and execution continues at the next statement. When calling an advanced function with -ErrorAction SilentlyContinue, the parameter translates to a scope-local $ErrorActionPreference value, so it also suppresses throw inside that function. Even when suppressed, throw still records an entry in $Error. The Ignore value only prevents $Error recording for non-terminating errors like those generated by $PSCmdlet.ThrowTerminatingError().

For more information about error categories and $ErrorActionPreference behavior, see about_Error_Handling.

For example, you can use the throw keyword in the statement 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

Exception: 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."

Exception: 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)

Exception: System.Diagnostics.Process (pwsh) System.Diagnostics.Process (pwsh) System.Diagnostics.Process (pwsh)

You can use the TargetObject property of the ErrorRecord object in the $Error automatic variable to examine the error.

$Error[0].TargetObject

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    125   174.44     229.57      23.61    1548   2 pwsh
     63    44.07      81.95       1.75    1732   2 pwsh
     63    43.32      77.65       1.48    9092   2 pwsh

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

OperationStopped: 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.

See also

  • Last updated on