Skip to content

Auto Publish – main to live - 2026-04-02 22:00 UTC#12921

Merged
learn-build-service-prod[bot] merged 2 commits intolivefrom
main
Apr 2, 2026
Merged

Auto Publish – main to live - 2026-04-02 22:00 UTC#12921
learn-build-service-prod[bot] merged 2 commits intolivefrom
main

Conversation

@learn-build-service-prod
Copy link
Copy Markdown
Contributor

This PR was automatically created by Auto Publish system to publish changes from the main branch to the live branch.

SufficientDaikon and others added 2 commits April 2, 2026 15:03
* Add about_Error_Handling and fix error terminology across docs

Create a comprehensive about_Error_Handling reference topic that documents
PowerShell's three error categories: non-terminating, statement-terminating,
and script-terminating errors. Correct false claims in about_CommonParameters
and about_Preference_Variables that state -ErrorAction and
$ErrorActionPreference have "no effect on terminating errors." Update
about_Try_Catch_Finally, about_Throw, about_Trap, and
everything-about-exceptions to use precise terminology consistent with
existing usage in about_Calculated_Properties, about_Pipeline_Chain_Operators,
and about_Pwsh.

Fixes #1583

* Address mklement0 review: fix error terminology precision

- -ErrorAction Stop promotes to script-terminating, not statement-terminating
- $ErrorActionPreference applies to both non-terminating and
  statement-terminating errors (unlike -ErrorAction parameter)
- $ErrorActionPreference = 'Ignore' is now accepted (remove outdated caveat)
- Native command non-zero exit emits non-terminating NativeCommandExitException

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Comprehensive accuracy overhaul: escalation semantics, asymmetry, parse errors

Major corrections verified against PowerShell engine source code:

- Fix: -ErrorAction Stop produces script-terminating errors, not
  statement-terminating. ActionPreferenceStopException sets
  SuppressPromptInInterpreter=true, causing call-stack unwinding.
  Fixed across all 4 affected files.

- Add: New "$ErrorActionPreference asymmetry" section in
  about_Error_Handling documenting that $ErrorActionPreference applies
  to BOTH non-terminating and statement-terminating errors, while
  -ErrorAction only affects non-terminating errors. Includes runnable
  demo and IMPORTANT callout for exceptions (SuppressPromptInInterpreter,
  PS classes, PipelineStoppedException).

- Add: Parse errors to script-terminating generators list (per
  mklement0 review comment).

- Fix: about_Preference_Variables Ignore bullet incorrectly stated
  "Ignore isn't a valid value for $ErrorActionPreference" — it is
  accepted (only Suspend is rejected per ExecutionContext.cs).

- Fix: NOTE block on ThrowTerminatingError now correctly explains
  that $ErrorActionPreference can suppress it via the engine's
  statement-level handler in MiscOps.CheckActionPreference.

- Fix: Summary table updated — -ErrorAction Stop moved from
  statement-terminating to script-terminating column, new row added
  for $ErrorActionPreference behavior per error type.

- Fix: everything-about-exceptions.md — three remaining instances of
  vague "terminating error" updated to "script-terminating error" for
  throw and -ErrorAction Stop contexts.

All claims verified with live PowerShell 7.x tests:
  1. -ErrorAction Stop: next statement in scriptblock does NOT run (script-terminating)
  2. Parse errors: caught as MethodInvocationException
  3. $ErrorActionPreference='Ignore': accepted without error
  4. $ErrorActionPreference='SilentlyContinue': suppresses ThrowTerminatingError
  5. -ErrorAction SilentlyContinue: does NOT suppress ThrowTerminatingError

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Address mklement0 feedback: throw suppression, Ignore/$Error, advanced escalation

Three corrections based on mklement0's review:

1. throw CAN be suppressed by $ErrorActionPreference when set to
   SilentlyContinue or Ignore. Removed the incorrect claim that throw
   is "always" script-terminating "regardless of $ErrorActionPreference".
   Also documented that -ErrorAction on advanced functions translates
   to a scope-local $ErrorActionPreference, so it suppresses throw too.

2. Added NOTE that $ErrorActionPreference = 'Ignore' still records
   terminating errors in $Error. Ignore only prevents $Error recording
   for non-terminating errors.

3. Escalation section now documents the advanced vs. non-advanced
   distinction: $ErrorActionPreference = 'Stop' produces
   script-terminating errors in non-advanced contexts, but
   statement-terminating errors in advanced contexts ([CmdletBinding()]).
   Summary table updated to reflect both contexts.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Refine escalation terminology: terminating (context-dependent) not script-terminating

Per mklement0 feedback, -ErrorAction Stop escalation scope depends on
whether the context is advanced ([CmdletBinding()]) or non-advanced.
Changed about_CommonParameters.md and ErrorAction table to say
"terminating error" generically, with escalation section providing
the full advanced vs. non-advanced explanation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Extend error handling accuracy to about_Throw, about_Try_Catch_Finally

- about_Throw: Add $ErrorActionPreference suppression caveat (throw CAN
  be suppressed by SilentlyContinue/Ignore), add NOTE block with Ignore
  still recording in $Error, update description to "by default"
- about_Try_Catch_Finally: Add NOTE about throw suppression with cross-ref
  to about_Error_Handling, fix $tempPath -> $tempFile code bug (line 264)
- about_Preference_Variables: Fix Ignore bullet - clarify that Ignore only
  prevents $Error recording for non-terminating errors, not terminating
- everything-about-exceptions: Change -ErrorAction Stop from
  "script-terminating" to "terminating" (context-dependent behavior)

All claims verified against live PowerShell 7.6 behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Final polish: qualify Ignore/$Error claims and About.md index

- About.md: Update throw index to "script-terminating error by default"
- about_Automatic_Variables: Qualify $Error/Ignore as non-terminating only
- about_CommonParameters: Qualify Ignore bullet as non-terminating only

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add about_Error_Handling to index; fix stale descriptions and dates

- About.md: Add missing about_Error_Handling entry to topic index
- About.md: Update about_Trap and about_Try_Catch_Finally descriptions
  to say "statement-terminating and script-terminating errors"
- about_Try_Catch_Finally.md: Fix [07] link text to match target heading
- Update ms.date on about_Trap, about_CommonParameters,
  about_Preference_Variables, everything-about-exceptions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Editorial changes - mostly formatting

* Copy changes to all versions

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Sean Wheeler <sean.wheeler@microsoft.com>
@learn-build-service-prod
Copy link
Copy Markdown
Contributor Author

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link
Copy Markdown
Contributor Author

Learn Build status updates of commit 23d8ca7:

✅ Validation status: passed

File Status Preview URL Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md ✅Succeeded View (powershell-5.1)
reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md ✅Succeeded View (powershell-5.1)
reference/5.1/Microsoft.PowerShell.Core/About/about_Error_Handling.md ✅Succeeded View (powershell-5.1)
reference/5.1/Microsoft.PowerShell.Core/About/about_Preference_Variables.md ✅Succeeded View (powershell-5.1)
reference/5.1/Microsoft.PowerShell.Core/About/about_Throw.md ✅Succeeded View (powershell-5.1)
reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md ✅Succeeded View (powershell-5.1)
reference/5.1/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md ✅Succeeded View (powershell-5.1)
reference/5.1/Microsoft.PowerShell.Utility/Select-String.md ✅Succeeded View (powershell-5.1)
reference/7.4/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md ✅Succeeded View (powershell-7.4)
reference/7.4/Microsoft.PowerShell.Core/About/about_CommonParameters.md ✅Succeeded View (powershell-7.4)
reference/7.4/Microsoft.PowerShell.Core/About/about_Error_Handling.md ✅Succeeded View (powershell-7.4)
reference/7.4/Microsoft.PowerShell.Core/About/about_Preference_Variables.md ✅Succeeded View (powershell-7.4)
reference/7.4/Microsoft.PowerShell.Core/About/about_Throw.md ✅Succeeded View (powershell-7.4)
reference/7.4/Microsoft.PowerShell.Core/About/about_Trap.md ✅Succeeded View (powershell-7.4)
reference/7.4/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md ✅Succeeded View (powershell-7.4)
reference/7.4/Microsoft.PowerShell.Utility/Select-String.md ✅Succeeded View (powershell-7.4)
reference/7.5/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md ✅Succeeded View (powershell-7.5)
reference/7.5/Microsoft.PowerShell.Core/About/about_CommonParameters.md ✅Succeeded View (powershell-7.5)
reference/7.5/Microsoft.PowerShell.Core/About/about_Error_Handling.md ✅Succeeded View (powershell-7.5)
reference/7.5/Microsoft.PowerShell.Core/About/about_Preference_Variables.md ✅Succeeded View (powershell-7.5)
reference/7.5/Microsoft.PowerShell.Core/About/about_Throw.md ✅Succeeded View (powershell-7.5)
reference/7.5/Microsoft.PowerShell.Core/About/about_Trap.md ✅Succeeded View (powershell-7.5)
reference/7.5/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md ✅Succeeded View (powershell-7.5)
reference/7.5/Microsoft.PowerShell.Utility/Select-String.md ✅Succeeded View (powershell-7.5)
reference/7.6/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md ✅Succeeded View (powershell-7.6)

This comment lists only the first 25 files in the pull request.
For more details, please refer to the build report.

@learn-build-service-prod learn-build-service-prod bot merged commit 0051ed3 into live Apr 2, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants