Skip to content

Commit 5add506

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 af777ad commit 5add506

File tree

1 file changed

+47
-37
lines changed

1 file changed

+47
-37
lines changed

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

Lines changed: 47 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -419,55 +419,65 @@ Valid values are strings, the same as for any variable names.
419419

420420
The following is an example of how `PipelineVariable` works. In this example,
421421
the `PipelineVariable` parameter is added to a `ForEach-Object` command to
422-
store the results of the command in variables. A range of numbers, 1 to 5, are
423-
piped into the first `ForEach-Object` command, the results of which are stored
424-
in a variable named `$temp`.
422+
store the results of the command in variables. Five number are piped into the
423+
first `ForEach-Object` command, the results of which are stored in a variable
424+
named `$Temp`.
425425

426-
The results of the first `ForEach-Object` command are piped into a second
427-
`ForEach-Object` command, which displays the current values of `$temp` and
428-
`$_`.
426+
The results of the first `ForEach-Object` command are piped into a downstream
427+
`ForEach-Object` command, which displays the current values of `$Temp` and
428+
`$PSItem`.
429429

430430
```powershell
431-
# Create a variable named $temp
432-
$temp=8
433-
Get-Variable temp
431+
# Create a variable named $Temp
432+
$Temp = 8
433+
Get-Variable Temp | Format-Table
434+
434435
# Note that the variable just created isn't available on the
435436
# pipeline when -PipelineVariable creates the same variable name
436-
1..5 | ForEach-Object -PipelineVariable temp -Begin {
437-
Write-Host "Step1[BEGIN]:`$temp=$temp"
437+
$InformationPreference = 'Continue'
438+
Write-Information '-----------------------------------------------------------'
439+
111,222,333,444,555 | ForEach-Object -PipelineVariable Temp -Begin {
440+
441+
Write-Information "Upstream (Begin): Temp = '$Temp'"
442+
438443
} -Process {
439-
Write-Host "Step1[PROCESS]:`$temp=$temp - `$_=$_"
440-
Write-Output $_
441-
} | ForEach-Object {
442-
Write-Host "`tStep2[PROCESS]:`$temp=$temp - `$_=$_"
444+
445+
Write-Information "Upstream (Process): Temp = '$Temp', PSItem = '$PSItem'"
446+
Return $PSItem
447+
448+
} | ForEach-Object -Process {
449+
450+
Write-Information "`t`t Downstream: Temp = '$Temp', PSItem = '$PSItem'"
451+
443452
}
444-
# The $temp variable is deleted when the pipeline finishes
445-
Get-Variable temp
453+
Write-Information '-----------------------------------------------------------'
454+
455+
# The $Temp variable is deleted when the pipeline finishes
456+
Get-Variable Temp | Format-Table
446457
```
447458

448459
```Output
449460
Name Value
450461
---- -----
451-
temp 8
452-
453-
Step1[BEGIN]:$temp=
454-
Step1[PROCESS]:$temp= - $_=1
455-
Step2[PROCESS]:$temp=1 - $_=1
456-
Step1[PROCESS]:$temp=1 - $_=2
457-
Step2[PROCESS]:$temp=2 - $_=2
458-
Step1[PROCESS]:$temp=2 - $_=3
459-
Step2[PROCESS]:$temp=3 - $_=3
460-
Step1[PROCESS]:$temp=3 - $_=4
461-
Step2[PROCESS]:$temp=4 - $_=4
462-
Step1[PROCESS]:$temp=4 - $_=5
463-
Step2[PROCESS]:$temp=5 - $_=5
464-
465-
Get-Variable : Cannot find a variable with the name 'temp'.
466-
At line:1 char:1
467-
+ Get-Variable temp
468-
+ ~~~~~~~~~~~~~~~~~
469-
+ CategoryInfo : ObjectNotFound: (temp:String) [Get-Variable], ItemNotFoundException
470-
+ FullyQualifiedErrorId : VariableNotFound,Microsoft.PowerShell.Commands.GetVariableCommand
462+
Temp 8
463+
464+
-----------------------------------------------------------
465+
Upstream (Begin): Temp = ''
466+
Upstream (Process): Temp = '', PSItem = '111'
467+
Downstream: Temp = '111', PSItem = '111'
468+
Upstream (Process): Temp = '111', PSItem = '222'
469+
Downstream: Temp = '222', PSItem = '222'
470+
Upstream (Process): Temp = '222', PSItem = '333'
471+
Downstream: Temp = '333', PSItem = '333'
472+
Upstream (Process): Temp = '333', PSItem = '444'
473+
Downstream: Temp = '444', PSItem = '444'
474+
Upstream (Process): Temp = '444', PSItem = '555'
475+
Downstream: Temp = '555', PSItem = '555'
476+
-----------------------------------------------------------
477+
478+
Name Value
479+
---- -----
480+
Temp
471481
```
472482

473483
> [!CAUTION]

0 commit comments

Comments
 (0)