Update about_CommonParameters.md: Pipeline variable example

[skycommand]

PR Summary

Following a series of questions by a PowerShell learner, I realized that the PipelineVariable example in this document is counterintuitive. So, I wrote a better one.

Here are the questions:

1. Why is the output different on my PC?
2. Why is the counter always -1 or 0?
3. Why are a mix of Write-Host and Write-Output commands in the example? Isn't Write-Host supposed to be evil?
4. Why do I get different results when I uniformly use Write-Host or Write-Output?

Here are my answers.

1: Why is the output different on my PC?

The output isn't different when you paste the original code into Windows Terminal, regardless of PowerShell's version. But if you:

• Paste the example into the prompt line of PowerShell 7.5 inside Console Host
• Run the example from a PS1 file
• Paste the example into the prompt line between &{ and }

...you get the following output, the last line of which poses a mental hurdle for a newbie. Examples are supposed to clarify, not befuddle.

Name                           Value
----                           -----
temp                           8
Step1[BEGIN]:$temp=
Step1[PROCESS]:$temp= - $_=1
        Step2[PROCESS]:$temp=1 - $_=1
Step1[PROCESS]:$temp=1 - $_=2
        Step2[PROCESS]:$temp=2 - $_=2
Step1[PROCESS]:$temp=2 - $_=3
        Step2[PROCESS]:$temp=3 - $_=3
Step1[PROCESS]:$temp=3 - $_=4
        Step2[PROCESS]:$temp=4 - $_=4
Step1[PROCESS]:$temp=4 - $_=5
        Step2[PROCESS]:$temp=5 - $_=5
temp

Pasting the example into the prompt line of PowerShell 5.1 inside the Console Host generates a different result:

Name                           Value
----                           -----
temp                           8
Step1[BEGIN]:$temp=
Step1[PROCESS]:$temp= - $_=1
        Step2[PROCESS]:$temp=1 - $_=1
Step1[PROCESS]:$temp=1 - $_=2
        Step2[PROCESS]:$temp=2 - $_=2
Step1[PROCESS]:$temp=2 - $_=3
        Step2[PROCESS]:$temp=3 - $_=3
Step1[PROCESS]:$temp=3 - $_=4
        Step2[PROCESS]:$temp=4 - $_=4
Step1[PROCESS]:$temp=4 - $_=5
        Step2[PROCESS]:$temp=5 - $_=5
Get-Variable : Cannot find a variable with the name 'temp'.
At line:15 char:1
+ Get-Variable temp
+ ~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (temp:String) [Get-Variable], ItemNotFoundException
    + FullyQualifiedErrorId : VariableNotFound,Microsoft.PowerShell.Commands.GetVariableCommand

This is much better. Instead of a mysterious "temp" out of nowhere, we have a clear error message.

My solution: I used Format-Table and deliberately added empty lines. To be honest, though, I added the empty lines for readability. It wasn't until later when I discovered the effect they have on the Console Host.

2: Why is the counter always -1 or 0?

To be honest, the OP didn't put the question in this precise fashion. It took me a while to understand the issue.

Firstly, $_ is not the counter. It's the iterator. The PowerShell team has already recognized this concern a long time ago, and introduced $PSItem.

Secondly, there is a miscommunication. The output isn't saying "1 - $PSItem = 2". It is saying:

• $Temp equals 1
• $PSItem equals 2

My solution:

• Use $PSItem instead of $_
• Use a different input array: 111, 222, 333, 444, and 555
• Put the value between quotation marks.
• Use different wording:

  Upstream (Process): Temp = '', PSItem = '111'
                 Downstream: Temp = '111', PSItem = '111'
  

4 and 5: Write-Host vs. Write-Output

No, Write-Host isn't evil. But mixing Write-Host and Write-Output is bound to trigger unfathomable conditions, and here, we have one. Newbies don't immediately grasp that Write-Output emits to pipeline, while Write-Host writes directly to the screen device. Hence, the use of Write-Output is counterintuitive.

My solution:

• Use Write-Information to emit to screen.
• Use return instead of Write-Output to emit to pipeline.

PR Checklist

• Descriptive Title: This PR's title is a synopsis of the changes it proposes.
• Summary: This PR's summary describes the scope and intent of the change.
• Contributor's Guide: I have read the contributor's guide.
• Style: This PR adheres to the style guide.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 5add506:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md	✅Succeeded	View (powershell-5.1)
reference/7.4/Microsoft.PowerShell.Core/About/about_CommonParameters.md	✅Succeeded	View (powershell-7.4)
reference/7.5/Microsoft.PowerShell.Core/About/about_CommonParameters.md	✅Succeeded	View (powershell-7.5)

For more details, please refer to the build report.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[sdwheeler]

@skycommand Thanks for the update and the thoughtful descriptions of your changes. It really helped me understand the motivation for the changes.

[learn-build-service-prod]

Learn Build status updates of commit f798a40:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md	✅Succeeded	View (powershell-5.1)
reference/7.4/Microsoft.PowerShell.Core/About/about_CommonParameters.md	✅Succeeded	View (powershell-7.4)
reference/7.5/Microsoft.PowerShell.Core/About/about_CommonParameters.md	✅Succeeded	View (powershell-7.5)
reference/7.6/Microsoft.PowerShell.Core/About/about_CommonParameters.md	✅Succeeded	View (powershell-7.6)

For more details, please refer to the build report.