powershell - When should I use Write-Error vs. Throw? Terminating vs. non-terminating errors

Question

Looking at a Get-WebFile script over on PoshCode, http://poshcode.org/3226, I noticed this strange-to-me contraption:

$URL_Format_Error = [string]"..."
Write-Error $URL_Format_Error
return

What is the reason for this as opposed to the following?

$URL_Format_Error = [string]"..."
Throw $URL_Format_Error

Or even better:

$URL_Format_Error = New-Object System.FormatException "..."
Throw $URL_Format_Error

As I understand, you should use Write-Error for non-terminating errors, and Throw for terminating errors, so it seems to me that you should not use Write-Error followed by Return. Is there a difference?

Answer 1

Write-Error should be used if you want to inform the user of a non-critical error. By default all it does is print an error message in red text on the console. It does not stop a pipeline or a loop from continuing. Throw on the other hand produces what is called a terminating error. If you use throw, the pipeline and/or current loop will be terminated. In fact all execution will be terminated unless you use a trap or a try/catch structure to handle the terminating error.

There is one thing to note, if you set $ErrorActionPreference to "Stop" and use Write-Error it will produce a terminating error.

In the script you linked to we find this:

if ($url.Contains("http")) {
       $request = [System.Net.HttpWebRequest]::Create($url)
}
else {
       $URL_Format_Error = [string]"Connection protocol not specified. Recommended action: Try again using protocol (for example 'http://" + $url + "') instead. Function aborting..."
       Write-Error $URL_Format_Error
    return
   }

It looks like the author of that function wanted to stop the execution of that function and display an error message on screen but did not want the entire script to stop executing. The script author could have used throw however it would mean you would have to use a try/catch when calling the function.

return will exit the current scope which can be a function, script, or script block. This is best illustrated with code:

# A foreach loop.
foreach ( $i in  (1..10) ) { Write-Host $i ; if ($i -eq 5) { return } }

# A for loop.
for ($i = 1; $i -le 10; $i++) { Write-Host $i ; if ($i -eq 5) { return } }

Output for both:

1
2
3
4
5

One gotcha here is using return with ForEach-Object. It will not break processing like one might expect.

More information:

• $ErrorActionPreference: about_Preference_Variables
• try/catch: about_Try_Catch_Finally
• trap: about_Trap
• throw: about_Throw
• return: about_Return