Add VerboseAction, DebugAction, ProgressAction, VerboseVariable, DebugVariable, and ProgressVariable common parameters

[KirkMunro]

PR Summary

• Add VerboseAction (va), DebugAction (da), ProgressAction (pra), VerboseVariable (vv), DebugVariable (dv), and ProgressVariable (prv) common parameters.
• Remove unnecessary restriction around ActionPreference.Ignore (see this discussion in issue 4348). (this has been moved to PR Transition ActionPreference.Suspend enumeration value into a non-supported, reserved state, and remove restriction on using ActionPreference.Ignore in preference variables #10317)
• Add default output for progress messages when rendered in the console.
• Change behavior of Write-Verbose and Write-Warning such that they simply output their messages if they are invoked with -Debug. This was missed in PR Debug parameter now sets debugpreference to continue #8195.
• Fixed bug in handling of PSCmdlet.WriteVerbose and PSCmdlet.WriteWarning methods. When a cmdlet is invoked without any common parameters, and that cmdlet invokes one of these methods, the cmdlet runtime was supposed to read the corresponding preference value once and then use that value in all subsequent invocations, for performance reasons. WriteVerbose and WriteWarning were not properly setting a flag when the value was read, and as a result were reading it again every time. See here for a more detailed discussion about this.

PR Context

As per #6702 and some considerations on one of my RFCs, this PR normalizes the common parameter set to allow for better scripter control for any stream in PowerShell.

This is the first step in facilitating easier capturing of stream data for logging purposes.

For the enquiring mind, it is even important to capture progress records, because some scripts are written to show a bunch of progress messages but not much else, and when these are run unattended and fail, it is impossible to know how far along they went before they failed. Capturing progress messages makes that problem go away.

PR Checklist

• PR has a meaningful title
  • Use the present tense and imperative mood when describing your changes
• Summarized changes
• Make sure all .h, .cpp, .cs, .ps1 and .psm1 files have the correct copyright header
• This PR is ready to merge and is not Work in Progress.
  • If the PR is work in progress, please add the prefix WIP: or [ WIP ] to the beginning of the title (the WIP bot will keep its status check at Pending while the prefix is present) and remove the prefix when the PR is ready.
• Breaking changes
  • None
  • OR
  • Experimental feature(s) needed
    • Experimental feature name(s): PSNewCommonParameters
• User-facing changes
  • Not Applicable
  • OR
  • Documentation needed
    • Issue filed: Document new common parameters in about_commonparameters MicrosoftDocs/PowerShell-Docs#4929
• Testing - New and feature
  • N/A or can only be tested interactively
  • OR
  • Make sure you've added a new test if existing tests do not effectively test the code changed
• Tooling
  • I have considered the user experience from a tooling perspective and don't believe tooling will be impacted.
  • OR
  • I have considered the user experience from a tooling perspective and enumerated concerns in the summary. This may include:
    • Impact on PowerShell Editor Services which is used in the PowerShell extension for VSCode (which runs in a different PS Host).
    • Impact on Completions (both in the console and in editors) - one of PowerShell's most powerful features.
    • Impact on PSScriptAnalyzer (which provides linting & formatting in the editor extensions).
    • Impact on EditorSyntax (which provides syntax highlighting with in VSCode, GitHub, and many other editors).

[Jaykul]

The alias for -Verbose is -vb and the alias for -Debug is -db ...

Should their respective Action and Variable short forms start with those prefixes?

That is, should -VerboseAction be -vba instead of -va, etc.?

I'm not sure. Certainly the InformationAction is the only one of the existing aliases that isn't a two-letter alias (and I don't actually know why), so there's good reason to stick with 2-letter initialisms.

[KirkMunro]

I'm not sure either. Also, used three letters for the progress aliases (pra and prv) to differentiate them from the -PipelineVariable alias while maintaining "suffix" consistency between them and with the other aliases.

That is, should -VerboseAction be -vba instead of -va, etc.?

I don't think we want vba in PowerShell. 😝

Kidding of course. I'm not attached to anything I chose...I just picked what made sense at the time.

[vexx32]

We should probably also make note that using -v as a shorthand for -Verbose is pretty common, especially in interactive cases.

If we're adding more parameters that by default conflict with that shorthand, we should probably add that as an explicit alias as well. :)

[KirkMunro]

So here's an idea. These new parameters make the usefulness of -Verbose and -Debug questionable. Those are convenient, but not as capable as the new common parameters. What if -VerboseAction was defined as a Switchable<ActionPreference>, where Switchable<T> is a new generic type whose constructor accepts the true and false T values for the type, plus assignment operators for bool and T, and an implicit conversion operator to T. Switchable<T> would also need to be supported in the parser as a parameter with no value, of course. This is just thinking out loud, but I've been brainstorming some ideas on how I could obsolete old switches without breaking scripts, and with a proper alias plus the Switchable<T> type, this would allow switches like -Verbose and -Debug, and even -Information if we wanted it, to just work as if they were common switch parameters without even having them explicitly defined (-Warning, -Progress, and -Error would not be necessary since those messages are shown by default).

The benefit with this approach is to simplify and normalize the common parameters without losing muscle memory and without breaking existing scripts. This generic type would also provide a pattern that would allow for switch replacement in any other command, should the need for that arise.

[KirkMunro]

Here is a screenshot that shows what ProgressRecord output looks like using the formatter:

Aside: That this screenshot demonstrates the problem identified in issue #10236 (many *Record types default format does not identify the actual type of message that is being conveyed, but they really should for logging/review/searching purposes).

[ghost]

This pull request has been automatically marked as Review Needed because it has been there has not been any activity for 7 days.
Maintainer, please provide feedback and/or mark it as Waiting on Author

[ghost]

This pull request has been automatically marked as stale because it has been marked as requiring author feedback but has not had any activity for 15 days. It will be closed if no further activity occurs within 10 days of this comment.

[KirkMunro]

C'mon, guys. 1.5 years post PR submission, you finally move forward with some action on this, but then your attention wanes at the end when some important questions are put on the table, and then you let it go stale and be closed? @TravisEz13: How was this marked waiting on author when the author (me) had responded with questions back to @PaulHigin?

It really is no wonder why I put my I put my interest in pushing PRs into this repo on hold until you all could catch up with the PRs that were already open and the discussions that were already started. I'm not all that surprised that this hasn't happened yet, but what does surprise me is that rather than properly managing what's there, you're allowing it get discarded. Such a waste.

[ghost]

This pull request has been automatically marked as Review Needed because it has been there has not been any activity for 7 days.
Maintainer, please provide feedback and/or mark it as Waiting on Author

[KirkMunro]

I'm walking away from my open PRs. I'm not really involved in PowerShell much these days. Personally I spend very little time using it, and at this point I don't have the time nor the motivation to deal with PRs submitted over 18 months ago.

As a point of feedback, this community is stagnant and unhealthy to participate in. It takes far too much personal effort and lobbying like a politician to get anything moving. Ideas on how to help the community move forward take years, and years, and years to bear any fruit at all. In software development, there is a balance between driving software forward based on internal business and internal/external customer priorities, and driving features and functionality that are quality of life improvements for the community of users using a product. This community has been, and in my mind clearly still is, focused almost exclusively on the former, and only considers the latter when it is of benefit to their goals for the former. It is not balanced at all when it comes to community contributions. Glancing at the history of closed PRs, and who those PRs come from, is clear evidence of this, and it seems obvious where your focus is internally for team member MBOs.

[mklement0]

@KirkMunro, I was going to say that we'll miss your contributions in all forms in this community.

But then I realized: there is no we.
But first, let's invite a few more people to the good-bye party: @SteveL-MSFT, @joeyaiello, @bpayette, @rjmholt, @sdwheeler.

I share your assessment of what is problematic about this community; let me point to two particularly striking examples that I've personally expended a lot of energy on:

• Do not require { ... } (curly braces) around variable names for null-conditional member access #14025 (comment) (not requiring {...} around variable names for the null-conditional operators, ?. / ?[])
• Implement accommodations for Windows CLIs, notably batch files and misexec-style programs as part of experimental feature PSNativeCommandArgumentPassing #15143 (comment) (comprehensive solution to the perennial quoting headaches when calling native executables)

In my perception, these two issues (the specific comments tell the history) exemplify several problematic patterns:

• Fiat decisions handed down with little to no explanation, often indicative of unawareness of the specifics of a proposal / lack of sufficient subject-matter expertise, followed by unwillingness to explain or debate the decision.

  • Working groups were supposed to help with that, but in my personal experience it seems to be just more of the same.

• Many quality-of-life-improvement proposals either getting ignored altogether, being met with indignant pushback ("very much by design"), argument-less claims of lack of arguments ("I don't believe you've made the argument sufficiently"), followed by eternal silence when counterarguments are made.

• Vague promises of revisiting issues that never materialize.

I hope that the many talented people that still make up this community have the stamina to continue to contribute, as things - hopefully - improve, but personally I feel burned out and, save for perhaps filing the occasional bug report prompted by real-life use, I will cease my activities here and in the docs repo.