Introduce a conceptual help topic about PowerShell's output streams: about_Streams

[mklement0]

Summary of the new document or enhancement

• As a user, I want to understand the respective purpose of PowerShell's 6 output streams, and what content I should expect in each.

• As a developer, I want guidance on what information should be sent to what stream.

A new conceptual about_Streams topic could cover these topics (and would complement about_Redirection, which is only about where to send stream output).

---

As for guidance, @KirkMunro had some thoughts in PowerShell/PowerShell#13636 (comment):

I also think PowerShell streams are misunderstood, and therefore misused. My take:

• Verbose is for messages that will help users troubleshoot why a command that they invoked interactively or in their script may have failed, when the error message itself is not enough. It is also to report information that is not otherwise available (site redirects on a REST API invocation, etc.), which again is intended to help someone understand a bit more technical detail to troubleshoot issues.

• Debug is for messages that will help a command author understand why their command is failing when someone else invoked it (or when they invoked it if they are actively debugging it). These can contain more internal details, and there may be many debug messages if they are necessary for deep troubleshooting, but their target audience is command authors

• Progress is for messages that communicate progress in longer running commands or scripts.

• Information is for messages that help a user understand what is being done in a script (if they are reviewing an ongoing run log or console where a command is running) or what was done by a script (if they are reviewing output of a script after the fact). It is also for developers to have additional streams if they need to pass information through PowerShell, where they can tag the stream and then have specific handling for that stream, passing object data out to a runtime.

Details of requested document:

• Proposed title: about_Streams
• Propose location in the TOC:
• Target audience: end users and developers
• List of related articles to link to: about_Redirection, various Write-* cmdlets

[KirkMunro]

Thanks for logging this @mklement0. Ironically I was sharing my thoughts on the other thread because I wondered if others felt the same, so hashing this out independently is a good idea.

One key point regarding the Debug stream is to call out the differences in behavior on Windows PowerShell 5.1 and PowerShell 6.x and whatever versions of PowerShell 7 still apply S.M.A.ActionPreference.Inquire when -Debug is used (I don't know the version that my PR was first included in that changed this to apply S.M.A.ActionPreference.Continue instead). That detail should be captured because it will influence how you handle messages in modules that support downlevel versions of PowerShell and Windows PowerShell.

One key point to capture regarding the Information stream is the fact that unlike other streams, it is not silenced with S.M.A.ActionPreference.SilentlyContinue, but it can be silenced with S.M.A.ActionPreference.Ignore.

These details plus guidance on what streams are for will ultimately help scripters and command authors choose the right logging model for their work.

[mklement0]

Thanks, @KirkMunro. Small correction: you probably meant S.M.A.ActionPreference.SilentlyContinue and the fact that the information stream is still written to in that case and that it is seemingly the host that prevents display, which is surprising behavior being discussed in this issue of yours: PowerShell/PowerShell#13631 (comment)