Add clean block to script block as a peer to begin, process, and end to allow easy resource cleanup

[daxian-dbw]

This is an alternate implementation of the Clean block in PowerShell. The original PR is #9900.
This implementation doesn't rely on the Dispose method to run the Clean block, but instead makes Clean block more like a peer to begin, process, and end blocks.

The updated RFC is currently under review: PowerShell/PowerShell-RFC#294
The doc issue for this feature: MicrosoftDocs/PowerShell-Docs#8090
The editor syntax PR: PowerShell/EditorSyntax#208

To-do check list:

• initial design and implementation (thanks @vexx32!)
• error handling proposal
• new design and implementation
  • regarding SynchronousExecutionEnumerate
  • regarding steppable pipeline
  • variable analysis integration for 'Clean' block
  • how to handle Exit in Clean block?
    • Exit from within a Clean block terminates the execution in the Clean block
    • But the ExitException is not propagated out of the Clean block
  • how to handle Ctrl+c [mimic finally behavior *]
  • rename the new block from cleanup to clean
  • semantic check for { clean { } }? No
    • decide to not add the semantic check for now, maybe this should be a script analyzer rule instead.
• testing
  • error handling tests
  • functional tests
  • breakpoint in clean block [manually checked]
• update the original accepted RFC for this feature, with details functional behavior and error handling behavior.

* The Ctrl+c behavior is still pending. The updated RFC discusses two different behaviors in the event of pipeline stopping in details in the Pipeline Stopping Behavior section. The current implementation in this PR mimics the finally clause behavior, but it keeps the changes in Stopper that would be needed to support non-cancellable clean block execution.

[iSazonov]

How to handle Exit in 'Clean'?

It would be amazing for cmdlets to terminate whole script or process but acceptable for script blocks.

[PaulHigin]

Still reviewing, but submitting initial comments/questions.

[JamesWTruher]

you suggest that errors in the clean block will be captured in -ErrorVariable but not generally emitted to the user as visible errors? Does that imply that the errors in the cleanup block will not be found in $ERROR? I'm a little nervous about that. I should think the clean up block runs in with implicit SilentlyContinue so errors are captured, but not displayed. What if the user explicitly sets $ErrorActionPreference = "Inquire" (or confirm), will we then prompt?

[daxian-dbw]

you suggest that errors in the clean block will be captured in -ErrorVariable but not generally emitted to the user as visible errors? Does that imply that the errors in the cleanup block will not be found in $ERROR? I'm a little nervous about that.

Errors in Clean block will be captured in -ErrorVariable, and also will be emitted to user as visible errors. All errors happen in Clean should (and can) be found in $Error.

I should think the clean up block runs in with implicit SilentlyContinue so errors are captured, but not displayed. What if the user explicitly sets $ErrorActionPreference = "Inquire" (or confirm), will we then prompt?

I personally prefer to not make the Clean block have a different default ActionPreference for error. I think it should just behave the same as other named blocks. That would also make it easier for the user to quickly know if there are any error in their Clean block.

@JamesWTruher The proposed error handling behavior already works with the changes in this PR, so I think it will be helpful if you can build this PR and play with it. You can also download the build artifacts from CIs, for example, the windows build can be downloaded here. Thanks for the review and I look forward to get more feedback from you!

[daxian-dbw]

Rebased the commits to resolve conflicts introduced by #16199

[daxian-dbw]

SSH remoting test run was cancelled due to an issue in the test pipeline, which was fixed by #16225
Re-open the PR to trigger all CIs.

[ghost]

🎉v7.3.0-preview.1 has been released which incorporates this pull request.:tada:

Handy links:

• Release Notes