I want all of the functions in my module to default to $ErrorActionPreference = 'Stop'
. Is it possible without modifying all the functions?
I have a file per function.
Assuming that your module is a script module, i.e., implemented in PowerShell code:
Important:
Modules have their own stack of scopes that is independent of the scopes of non-module code (and other modules'). While this provides isolation from the caller's environment that is generally useful, it also means that the caller's $ErrorActionPreference
value never takes effect for script-module functions (unless you directly run from the global scope, which modules also see) - but it does so for compiled cmdlets. This highly problematic behavior is discussed in this GitHub issue.
Even though you therefore currently cannot control a script module's error behavior from the caller by way of $ErrorActionPreference
, by setting (overriding) $ErrorActionPreference
in your module you're closing that door permanently.
However, using the -ErrorAction
common parameter for a specific call instead of the $ErrorActionPreference
preference variable will still override your module-global $ErrorActionPreference
value, because, behind the scenes, PowerShell translates the -ErrorAction
argument to a function-local $ErrorActionPreference
variable with that value.
The -ErrorAction
and $ErrorActionPreference
mechanisms are plagued by inconsistencies and obscure behaviors - this GitHub docs issue provides a comprehensive overview of PowerShell's error handling.
I want all of the functions in my module to default to
$ErrorActionPreference = 'Stop'
. Is it possible without modifying all the functions?
Yes - simply place $ErrorActionPreference = 'Stop'
in your RootModule
*.psm1
file's top-level code. (The RootModule
entry of a module's manifest file (*.psd1
) specifies a module's main module - see the docs).
RootModule
entry that references a .psm1
file, simply create a .psm1
file in your module folder (typically named for the enclosing module) with content $ErrorActionPreference = 'Stop'
, and reference it from the RootModule
entry - see this answer for background information.Unless overridden by the caller by using the common -ErrorAction
parameter when calling your module's functions (assuming they are advanced functions), your module's top-level $ErrorActionPreference
value will be in effect for all of your module's functions, except if your function directly emits a statement-terminating error[1], in which case it is the caller's $ErrorActionPreference
value that matters.
If your module is a binary module, i.e., exports compiled cmdlets (typically implemented in C#):
Compiled cmdlets don't have their own scope - they run in the caller's scope. It is therefore the caller's $ErrorActionPreference
that matters, which can be overridden on a per-call basis with common parameter -ErrorAction
, but only for non-terminating errors.
As with advanced functions in script modules, directly emitted statement-terminating errors[1] are always subject to the caller's $ErrorActionPreference
value, even if -ErrorAction
is used. (Note that binary cmdlets do not emit script-terminating errors).
[1] Statement-terminating errors occur in the following scenarios:
Directly, to abort execution of the enclosing cmdlet or advanced function/script:
When a binary cmdlet encounters a severe error that prevents it from continuing, it reports such an error with the ThrowTerminatingError()
method (or just throws an exception).
An advanced PowerShell function/script would similarly have to use $PSCmdlet.ThrowTerminatingError()
, which, however, is rare in practice; the typically used Throw
statement creates a script-terminating error instead, which by default also terminates the entire thread, i.e., also terminates the caller and all its callers.
Indirectly, in PowerShell code:
When an expression causes a runtime error, such as 1 / 0
or 'a,b' -split ',', 'NotAnInt'
.
When a .NET method call throws an exception, such as [int]::Parse('NotAnInt')
When, inside an advanced function/script, another cmdlet or advanced function / script is called that itself directly emits a statement-terminating error.
Note that advanced functions/scripts cannot relay statement-terminating errors as such:
By default (with $ErrorActionPreference
containing 'Continue'
, possibly just in the local scope) the expression's / other command's terminating error effectively becomes a non-terminating error from the caller's perspective.
With $ErrorActionPreference
set to 'Stop'
, the originally statement-terminating error is promoted to a script-terminating error.
It looks like you can do this with explicit default parameter setting in the $PSDefaultParameterValues
session-wide preference variable.
This includes the ability to set the ErrorAction Common Parameter default for specific functions. Keep in mind, you would want to append the current value of $PSDefaultParameterValues
since it uses a hash table, and other functions may currently have defaults set in the current session. This would also mean that [CmdletBinding()]
needs to be included in every function that is being given this default value.
$PSDefaultParameterValues
is a hash table, so you would want to modify in a fashion like so:
$PSDefaultParameterValues += @{
"Get-Function:ErrorAction"="Stop"
"Get-Command:ErrorAction"="Stop"
"Get-MyFunction*:ErrorAction"="Stop"
}
or
$PSDefaultParameterValues.add("Get-Function:ErrorAction","Stop")
Wildcards are accepted in function/cmdlet names, which may make it easier to get all of your functions in one line if you have a unique noun prefix naming scheme for imports from your module (though, this would include any other functions/cmdlets if any are imported into a session that include the same naming prefix).
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With