KirkMunro
commented
9 years ago You picked a good example Joel, because the errors that may be thrown from this example differ if $configurationFile is $null than if $configurationFile is a file that does not exist. If the file does not exist, -ErrorAction can be used to control how the cmdlet throws errors, however if $configurationFile is $null, -ErrorAction has no effect.
The only best practice I can recommend when it comes to handle errors in PowerShell scripts, functions, script modules, etc. in a consistent way is as follows:
Try/catch everything (or alternatively use the trap statement)
Reasoning: if you create a script or function or script module that does not wrap the contents in try-catch (or that does not use trap), then how that script/function/script module works is dependent on how it is called. If it is called from inside of a try/catch block, then terminating errors are actually treated as terminating errors. Otherwise, the script/function/script module will continue to execute after an error that would otherwise be terminating is raised.
Details: In general, I use trap in script modules (Joel's suggestion IIRC) to avoid unnecessary indentation where there is none, and try/catch everywhere else. This includes each begin, process, and end block.
In advanced functions, inside of the catch block, invoke $PSCmdlet.ThrowTerminatingError($_)
Like this:
function Test-Something {
[CmdletBinding()]
param()
try {
# ...
} catch {
$PSCmdlet.ThrowTerminatingError($_)
}
}Reasoning: This format allows PowerShell to display the error details along with the command name just as it would if the error came from a native cmdlet. The format is much easier for function consumers, it is more consistent, and it doesn't get them confused with the details about the innards of the function. If you were to simply invoke throw instead, then the line of script that would be displayed to the caller as the source of the error would be the throw statement itself rather than the line of script that was used to invoke the function when the error occurred. These details shouldn't be exposed to the caller when an error occurs as it will only contribute to confusing them.
In Script Modules, include a trap statement at the top of the script module that simply rethrows any errors that occur.
For example:
trap {throw}Reasoning: This allows a script module to properly fail to load if a terminating error is raised. Without this, script modules may "load" in some unknown/unsupported state even if an error occurs during the loading process.
With all of that in mind, I vote strongly for the Force an exception and catch it approach as the best practice, but with the additional details above that describe how to handle the exception properly (using trap for script modules, try/catch with $PSCmdlet.ThrowTerminatingError($_) for advanced functions, and try/catch{throw} for anything else.
Also, with respect to throw, there are ways to throw ErrorRecord instances that give the caller much better details than they will get from a throw statement that simply throws a string. I have plenty of examples of those, and can dig some up it you want to see it (maybe next week after I'm back home).
indented-automation
KevinMarquette
christianacca
cspotcode
Jaykul
kborowinski
copdips
erikgraa
ChrisLGardner
JustinGrote
https://github.com/PoshCode/PowerShellPracticeAndStyle/blob/master/Best%20Practices/err-05-avoid-testing-for-a-null-variable-as-an-error-condition.md
First of all, let's not have a misleading discussion. The original guideline uses a bad example. Get-ADUser throws an exception when you use the -Identity parameter and it can't find anything. There's obviously no value in writing a warning if you didn't suppress the error, and it's equally silly to let an exception spew and then still test for null -- you need to either suppress the error or use it instead of testing for null.
Let's try a different example. I have a module which requires the user to configure multiple connection strings and a license before it can continue. Imagine that it was this simple to verify that you had, in fact, configured it:
This will cause an error and an empty variable if the ConfigurationFile doesn't exist, but does not throw (it's not terminating) by default. There are a few ways I could handle that in PowerShell.
For what it's worth: the pythonic way is always to just charge ahead, never test, and just deal with the exceptions (or let them output, if they're clear enough on their own). The old C/C++ way is to always check the
hResult, there are no exceptions. The Java and C# way usually involve handling exceptions, but not quite as aggressively as Python, you would rarely force an exception to happen if you could avoid it by a quick test.So which of these should be recommended? Incidentally, for the sake of this discussion, please imagine my
throwstatement to be your preferred way of exiting a function with extreme prejudice.Avoid the error:
Of course, if it's best practice to avoid errors when possible, you still have to have a best practice for dealing with them, because it's not always as easy as
Test-Pathto avoid them.Suppress the error and check the output:
Or I could write that backwards:
Force an exception and catch it
Deal with the error itself