Support mapping foreground/background ConsoleColor values to VT escape sequences

[daxian-dbw]

PR Summary

Fix: #17937

Update PSStyle to support mapping foreground/background ConsoleColor values to VT escape sequences, and mark the VTUtility class deprecated.

PS:11> [System.Management.Automation.PSStyle] | gm -Static

   TypeName: System.Management.Automation.PSStyle

Name                               MemberType Definition
----                               ---------- ----------
Equals                             Method     static bool Equals(System.Object objA, System.Object objB)
MapBackgroundColorToEscapeSequence Method     static string MapBackgroundColorToEscapeSequence(System.ConsoleColor backgroundColor)
MapColorPairToEscapeSequence       Method     static string MapColorPairToEscapeSequence(System.ConsoleColor foregroundColor, System.ConsoleColor ba…
MapForegroundColorToEscapeSequence Method     static string MapForegroundColorToEscapeSequence(System.ConsoleColor foregroundColor)
ReferenceEquals                    Method     static bool ReferenceEquals(System.Object objA, System.Object objB)
Instance                           Property   static System.Management.Automation.PSStyle Instance {get;}

PR Context

Please see the detailed description in #17937 for the context.

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):
• User-facing changes
  • Not Applicable
  • OR
  • Public method documentation will be automatically refreshed when we do doc updates.
• 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.

[SteveL-MSFT]

VTUtility pre-dates $PSStyle and was not intended to be a long term solution. I wonder if it makes sense to have the helper functions as part of $PSStyle instead and move towards deprecating VTUtility which (although public) was only used in formatting?

[daxian-dbw]

That sounds totally reasonable to me. I can move the changes over to PSStyle as static methods.

[daxian-dbw]

@SteveL-MSFT The changes are moved to PSStyle. VTUtility is now marked as deprecated. Please review again.
One question: shall we make those methods available as instance methods to $PSStyle as well? If so, it's natural to have FromConsoleColor methods in Forground and Background classes respectively, but what about MapColorPairToEscapeSequence?

[SteveL-MSFT]

@daxian-dbw it seems logical and may improve discovery to have FromConsoleColor() onto Foreground and Background classes, so I agree with that. For the color pair, we could either require two calls for foreground and background, or put it onto $PSStyle instance.

[pull-request-quantifier-deprecated]

This PR has 89 quantified lines of changes. In general, a change size of upto 200 lines is ideal for the best PR experience!

---

Quantification details

Label      : Small
Size       : +69 -20
Percentile : 35.6%

Total files changed: 4

Change summary by file extension:
.cs : +69 -20

Change counts above are quantified counts, based on the PullRequestQuantifier customizations.

Why proper sizing of changes matters

Optimal pull request sizes drive a better predictable PR flow as they strike a
balance between between PR complexity and PR review overhead. PRs within the
optimal size (typical small, or medium sized PRs) mean:

• Fast and predictable releases to production:
  • Optimal size changes are more likely to be reviewed faster with fewer
    iterations.
  • Similarity in low PR complexity drives similar review times.
• Review quality is likely higher as complexity is lower:
  • Bugs are more likely to be detected.
  • Code inconsistencies are more likely to be detected.
• Knowledge sharing is improved within the participants:
  • Small portions can be assimilated better.
• Better engineering practices are exercised:
  • Solving big problems by dividing them in well contained, smaller problems.
  • Exercising separation of concerns within the code changes.

What can I do to optimize my changes

• Use the PullRequestQuantifier to quantify your PR accurately
  • Create a context profile for your repo using the context generator
  • Exclude files that are not necessary to be reviewed or do not increase the review complexity. Example: Autogenerated code, docs, project IDE setting files, binaries, etc. Check out the Excluded section from your prquantifier.yaml context profile.
  • Understand your typical change complexity, drive towards the desired complexity by adjusting the label mapping in your prquantifier.yaml context profile.
  • Only use the labels that matter to you, see context specification to customize your prquantifier.yaml context profile.
• Change your engineering behaviors
  • For PRs that fall outside of the desired spectrum, review the details and check if:
    • Your PR could be split in smaller, self-contained PRs instead
    • Your PR only solves one particular issue. (For example, don't refactor and code new features in the same PR).

How to interpret the change counts in git diff output

• One line was added: +1 -0
• One line was deleted: +0 -1
• One line was modified: +1 -1 (git diff doesn't know about modified, it will
  interpret that line like one addition plus one deletion)
• Change percentiles: Change characteristics (addition, deletion, modification)
  of this PR in relation to all other PRs within the repository.

---

Was this comment helpful? 👍  :ok_hand:  :thumbsdown: (Email)
Customize PullRequestQuantifier for this repository.

[daxian-dbw]

For the color pair, we could either require two calls for foreground and background, ..

Agreed. Added the FromConsoleColor to $PSStyle.Foreground and $PSStyle.Background. Skip the color pair for now.

[ghost]

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

Handy links:

• Release Notes