@@ -53,6 +53,8 @@ run directly, and a function, which a caller invokes and which must leave the ca
5353 error. A non-zero exit code does not raise a PowerShell error by default.
5454- ** ERR-24** In a script, pass ` -ErrorAction Stop ` to a module command whose non-terminating errors
5555 must stop the script. The script's own ` $ErrorActionPreference ` does not reach module functions.
56+ Set the preference as well (ERR-01): ` -ErrorAction Stop ` on a call does not make a terminating
57+ error of that command end the script.
5658
5759### Streams
5860
@@ -222,9 +224,13 @@ carries.
222224
223225Each statement below was verified on PowerShell 7.6 and Windows PowerShell 5.1.
224226
225- - ` throw ` is suppressed when any caller up the call stack passed ` -ErrorAction SilentlyContinue ` or
226- ` -ErrorAction Ignore ` . Execution then continues with the statement after the ` throw ` , and the
227- function returns as if it had succeeded.
227+ - ` throw ` is suppressed when any caller up the call stack passed ` -ErrorAction SilentlyContinue ` , or
228+ ` -ErrorAction Ignore ` on PowerShell 7. Execution then continues with the statement after the
229+ ` throw ` , and the function returns as if it had succeeded. A bare ` throw ` that passes on an error
230+ raised with ` -ErrorAction Stop ` is the exception, described under the table below. On Windows
231+ PowerShell 5.1, ` -ErrorAction Ignore ` does not suppress a ` throw ` : the command that was given the
232+ parameter ends with another error,
233+ ` The value Ignore is not supported for an ActionPreference variable ` .
228234- ` Write-Error -ErrorAction Stop ` ignores the caller's ` -ErrorAction ` , and unless ` -ErrorRecord ` is
229235 passed it replaces the original exception with a ` WriteErrorException ` .
230236- ` $PSCmdlet.ThrowTerminatingError() ` always ends the function, and the caller's ` -ErrorAction ` does
@@ -241,6 +247,41 @@ Each statement below was verified on PowerShell 7.6 and Windows PowerShell 5.1.
241247- Under ` $ErrorActionPreference = 'Stop' ` , ` Write-Error ` terminates. Statements that follow it in the
242248 same block do not run.
243249
250+ ### What a calling script sees (ERR-01, ERR-10, ERR-11, ERR-24)
251+
252+ A module function fails in its ` begin ` block, in one of three ways, and the script that calls it is
253+ started with ` -File ` . Measured on PowerShell 7.7.0, PowerShell 7.6.10, and Windows PowerShell 5.1:
254+
255+ | The calling script | ` $PSCmdlet.ThrowTerminatingError() ` | ` throw $_ ` | ` Write-Error -ErrorRecord $_ -ErrorAction Stop ` |
256+ | --- | --- | --- | --- |
257+ | Has no ` try ` and sets no preference | Goes on, exit code 0 | Ends, exit code 1 | Ends, exit code 1 |
258+ | Passes ` -ErrorAction Stop ` | Goes on, exit code 0 | Ends, exit code 1 | Ends, exit code 1 |
259+ | Passes ` -ErrorAction SilentlyContinue ` | Goes on, exit code 0 | Goes on, and so does the function | Ends, exit code 1 |
260+ | Sets ` $ErrorActionPreference = 'Stop' ` | Ends, exit code 1 | Ends, exit code 1 | Ends, exit code 1 |
261+ | Makes the call inside ` try ` | ` catch ` runs | ` catch ` runs | ` catch ` runs |
262+ | Makes the call twice in a loop | Both calls run | Ends at the first | Ends at the first |
263+
264+ ` throw ` with text or with an exception object behaves as ` throw $_ ` does, and so does a bare ` throw `
265+ in ` catch ` , with one exception. A bare ` throw ` that passes on an error raised with
266+ ` -ErrorAction Stop ` behaves as the last column does, and so does such an error that no ` catch `
267+ handles: the script ends under ` -ErrorAction SilentlyContinue ` as well.
268+
269+ A compiled cmdlet that raises a terminating error, as ` ConvertFrom-Json ` does for invalid text,
270+ behaves as the first column does.
271+
272+ ERR-10 chooses the first column: the function fails as a cmdlet does, and the caller decides whether
273+ the script stops. The last column ends the calling script whatever the caller asked for. ` -ErrorAction `
274+ no longer works for the caller, and a loop ends at its first failure, which is why ERR-11 rules that
275+ form out even with ` -ErrorRecord ` .
276+
277+ The first two rows are the price of that choice. A script that does not set
278+ ` $ErrorActionPreference = 'Stop' ` goes on after the failure and ends with exit code 0, and
279+ ` -ErrorAction Stop ` on the call does not change that. A script therefore needs both: the preference
280+ for a terminating error (ERR-01), and ` -ErrorAction Stop ` for a non-terminating error of a module
281+ command (ERR-24). Text for callers, such as a README, a runbook, or a help example, says the same.
282+ It does not offer ` -ErrorAction Stop ` as the way to make a failed command end a script or fail a job
283+ step.
284+
244285### Strict mode (ERR-02, ERR-03)
245286
246287` Set-StrictMode ` applies to the scope where it runs and to the scopes below it. At the top of a
@@ -320,6 +361,14 @@ non-zero exit code raise an error that follows `$ErrorActionPreference`. It does
320361PowerShell 5.1, and some tools use non-zero exit codes for success (` robocopy ` returns values up to 7
321362for normal outcomes), so an explicit ` $LASTEXITCODE ` test is the portable form.
322363
364+ ### Log files (ERR-30)
365+
366+ These rules send messages to the streams and add no logging module. A project that also wants log
367+ files adds them with the ` powershell-logging ` skill, which uses the PSFramework module. Its code
368+ calls ` Write-PSFMessage ` where these rules name ` Write-Verbose ` , ` Write-Debug ` , and ` Write-Warning ` ,
369+ and the message still reaches the stream. A project that requires PSFramework, in its manifest or
370+ in a ` #requires -Modules ` line, has made that choice: do not turn those calls back.
371+
323372### Messages in a loop (ERR-32)
324373
325374PowerShell builds the message before ` Write-Verbose ` decides whether to show it. Measured with
0 commit comments