Audit use of terminating errors

Describe the feature

Review the use of terminating errors in AWS PowerShell cmdlets and only use terminating errors where absolutely necessary. Especially in "Get" verb cmdlets.

Use Case

This started for me with Get-ACCTAlternateContact and the error "No contact of the inputted alternate contact type found." See: https://github.com/aws/aws-tools-for-powershell/issues/327#issuecomment-1664853213 https://github.com/aws/aws-tools-for-powershell/issues/327#issuecomment-1672147917

However, I think it's a pretty widespread inconvenience in the AWS PowerShell codebase.

Terminating errors do not honor -ErrorAction. You have to use try/catch to handle the errors which is not friendly for interactive shell/command line. (less of a problem for scripted usage)
Terminating errors interrupt the pipeline: Get-Content .\AccountList.txt | ForEach-Object {Get-ACCTAlternateContact -AccountId $_ -AlternateContactType BILLING} | Export-Csv -Path .\billingContacts.csv - if there are 5 items and a terminating error on item 3, the remaining items are not processed.

@jnunn-aws says this is by according to PowerShell precedent but most PowerShell "Get" verb cmdlets don't throw terminating errors.

E.g.:

Get-Item xxx -ErrorAction SilentlyContinue
Get-Job -Id 99 -ErrorAction SilentlyContinue
Get-Alias -Name xxx -ErrorAction SilentlyContinue
Get-Member -InputObject xxx -Name xxx -ErrorAction SilentlyContinue
Get-Module -Name xxx -ErrorAction SilentlyContinue

All of the above return non-terminating errors and honor -ErrorAction.

Unless it's really critical, I'd expect cmdlets to emit a non-terminating errors that I can use -ErrorAction on and that do not interrupt the pipeline.

Proposed Solution

No response

Other Information

No response

Acknowledgements

[ ] I may be able to implement this feature request
[X] This feature might incur a breaking change

AWS Tools for PowerShell version used

4.1.396

PowerShell version used

Name Value PSVersion 7.3.6 PSEdition Core GitCommitId 7.3.6 OS Microsoft Windows 10.0.22621 Platform Win32NT PSCompatibleVersions {1.0, 2.0, 3.0, 4.0ΓÇª} PSRemotingProtocolVersion 2.3 SerializationVersion 1.1.0.1 WSManStackVersion 3.0

Operating System and version

Windows 11

Perhaps the following guidance (excerpted from this SO answer) helps:

How do you choose whether to report a statement-terminating or non-terminating error?

Cmdlet Error Reporting contains helpful guidelines; let me attempt a pragmatic summary:

The general idea behind non-terminating errors is to allow "fault-tolerant" processing of large input sets: failure to process a subset of the input objects should not (by default) abort the - potentially long-running - process as a whole, allowing you to inspect the errors and reprocess only the failed objects later - as reported via the error records collected in the automatic $Error variable.

Report a NON-TERMINATING error, if your cmdlet / advanced function:
- accepts MULTIPLE input objects, via the pipeline input and/or array-valued parameters, AND
- errors occur for SPECIFIC input objects, AND
- these errors DO NOT PREVENT PROCESSING of FURTHER input objects IN PRINCIPLE (situationally, there may be no input objects left and/or previous input objects may already have been processed successfully).
  - In advanced functions, use $PSCmdlet.WriteError() to report a non-terminating error (Write-Error, unfortunately, doesn't cause $? to be set to $False in the caller's scope - see GitHub issue #3629).
  - Handling a non-terminating error: $? tells you whether the most recent command reported at least one non-terminating error.
    - Thus, $? being $False can either mean that any (nonempty) subset of input objects weren't properly processed, possibly the entire set.
    - Preference variable $ErrorActionPreference and/or common cmdlet parameter -ErrorAction can modify the behavior of non-terminating errors (only) in terms of error output behavior and whether non-terminating errors should be escalated to script-terminating ones.
Report a STATEMENT-TERMINATING error in all other cases.
- Notably, if an error occurs in a cmdlet / advanced function that only accepts a SINGLE or NO input object and outputs NO or a SINGLE output object or takes parameter input only and the parameter values given prevent meaningful operation.
  - In advanced functions, you must use $PSCmdlet.ThrowTerminatingError() in order to generate a statement-terminating error.
  - Note that, by contrast, the Throw keyword generates a script-terminating error that aborts the entire script (technically: the current runspace (thread)).
  - Handling a statement-terminating error: A try/catch handler or trap statement may be used (which cannot be used with non-terminating errors), but note that even statement-terminating errors by default do not prevent the rest of the script from running. As with non-terminating errors, $? reflects $False if the previous statement triggered a statement-terminating error.

aws / aws-tools-for-powershell