Skip to content

Commit af777ad

Browse files
authored
Update about_CommonParameters.md: Pipeline variable example
Following a series of questions by a PowerShell learner, I realized that the `PipelineVariable` example in this document is counter-intuitive. So, I wrote a better one. I'll include the details in the PR message.
1 parent eba805d commit af777ad

File tree

1 file changed

+44
-31
lines changed

1 file changed

+44
-31
lines changed

reference/7.4/Microsoft.PowerShell.Core/About/about_CommonParameters.md

Lines changed: 44 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -409,52 +409,65 @@ Valid values are strings, the same as for any variable names.
409409

410410
The following is an example of how `PipelineVariable` works. In this example,
411411
the `PipelineVariable` parameter is added to a `ForEach-Object` command to
412-
store the results of the command in variables. A range of numbers, 1 to 5, are
413-
piped into the first `ForEach-Object` command, the results of which are stored
414-
in a variable named `$temp`.
412+
store the results of the command in variables. Five number are piped into the
413+
first `ForEach-Object` command, the results of which are stored in a variable
414+
named `$Temp`.
415415

416-
The results of the first `ForEach-Object` command are piped into a second
417-
`ForEach-Object` command, which displays the current values of `$temp` and
418-
`$_`.
416+
The results of the first `ForEach-Object` command are piped into a downstream
417+
`ForEach-Object` command, which displays the current values of `$Temp` and
418+
`$PSItem`.
419419

420420
```powershell
421-
# Create a variable named $temp
422-
$temp=8
423-
Get-Variable temp
421+
# Create a variable named $Temp
422+
$Temp = 8
423+
Get-Variable Temp | Format-Table
424+
424425
# Note that the variable just created isn't available on the
425426
# pipeline when -PipelineVariable creates the same variable name
426-
1..5 | ForEach-Object -PipelineVariable temp -Begin {
427-
Write-Host "Step1[BEGIN]:`$temp=$temp"
427+
$InformationPreference = 'Continue'
428+
Write-Information '-----------------------------------------------------------'
429+
111,222,333,444,555 | ForEach-Object -PipelineVariable Temp -Begin {
430+
431+
Write-Information "Upstream (Begin): Temp = '$Temp'"
432+
428433
} -Process {
429-
Write-Host "Step1[PROCESS]:`$temp=$temp - `$_=$_"
430-
Write-Output $_
431-
} | ForEach-Object {
432-
Write-Host "`tStep2[PROCESS]:`$temp=$temp - `$_=$_"
434+
435+
Write-Information "Upstream (Process): Temp = '$Temp', PSItem = '$PSItem'"
436+
Return $PSItem
437+
438+
} | ForEach-Object -Process {
439+
440+
Write-Information "`t`t Downstream: Temp = '$Temp', PSItem = '$PSItem'"
441+
433442
}
434-
# The $temp variable is deleted when the pipeline finishes
435-
Get-Variable temp
443+
Write-Information '-----------------------------------------------------------'
444+
445+
# The $Temp variable is deleted when the pipeline finishes
446+
Get-Variable Temp | Format-Table
436447
```
437448

438449
```Output
439450
Name Value
440451
---- -----
441-
temp 8
442-
443-
Step1[BEGIN]:$temp=
444-
Step1[PROCESS]:$temp= - $_=1
445-
Step2[PROCESS]:$temp=1 - $_=1
446-
Step1[PROCESS]:$temp=1 - $_=2
447-
Step2[PROCESS]:$temp=2 - $_=2
448-
Step1[PROCESS]:$temp=2 - $_=3
449-
Step2[PROCESS]:$temp=3 - $_=3
450-
Step1[PROCESS]:$temp=3 - $_=4
451-
Step2[PROCESS]:$temp=4 - $_=4
452-
Step1[PROCESS]:$temp=4 - $_=5
453-
Step2[PROCESS]:$temp=5 - $_=5
452+
Temp 8
453+
454+
-----------------------------------------------------------
455+
Upstream (Begin): Temp = ''
456+
Upstream (Process): Temp = '', PSItem = '111'
457+
Downstream: Temp = '111', PSItem = '111'
458+
Upstream (Process): Temp = '111', PSItem = '222'
459+
Downstream: Temp = '222', PSItem = '222'
460+
Upstream (Process): Temp = '222', PSItem = '333'
461+
Downstream: Temp = '333', PSItem = '333'
462+
Upstream (Process): Temp = '333', PSItem = '444'
463+
Downstream: Temp = '444', PSItem = '444'
464+
Upstream (Process): Temp = '444', PSItem = '555'
465+
Downstream: Temp = '555', PSItem = '555'
466+
-----------------------------------------------------------
454467
455468
Name Value
456469
---- -----
457-
temp
470+
Temp
458471
```
459472

460473
> [!CAUTION]

0 commit comments

Comments
 (0)