When to use foreach in a pipeline?

Question

Hello
I keep running into this confusion - when to use foreach cmdlet in a command line and when not to? (Please note I am not talking about foreach loop construct).
For example I have seen the following 2 do not work in the same way:
import-csv input.csv | foreach {
$UserPrincipalName = $_.UserPrincipalName;
Get-ADUser -filter {userprincipalname -eq $userprincipalname} -properties *
| foreach { set-aduser $_ -UserPrincipalName "$($_.samaccountname)@test.local"}
and
import-csv input.csv | foreach {
$UserPrincipalName = $_.UserPrincipalName;
Get-ADUser -filter {userprincipalname -eq $userprincipalname} -properties * |  set-aduser $_ -UserPrincipalName "$($_.samaccountname)@test.local"
The first one above does what I want but not the second one.
Is there any logic to this?

Answer 1

Hi Guys,
I think I got my head straightened out, so here's the best attempt at explaining this:
The basic pipeline
The $_ is the dynamic variable that describes the object currently precessed in the pipeline. However, it only exists within the scope of the currently processing command. An Example:
Get-ExampleObjects | Process-ExampleObjects -ToLower -Description "I'm a new description" | Set-ExampleObjects
Get-ExampleObjects passes its output (whatever it might be) to the pipeline
This output is piped to Process-ExampleObjects, a command that is designed to handle Pipeline Input.
Within Process-ExampleObjects (which is its own scope), the currently processed Pipeline Object is referenced by the variable $_ and can thus be used. HOWEVER: This does not mean it exists within "| Process-ExampleObjects |" but within "Process-ExampleObjects".
This means that while Process-ExampleObjects can have parameters, they need to be static as far as the current pipeline is concerned.
Once Process-ExampleObjects is done, it passes its output via pipeline to Set-ExampleObjects. This moves the object out of the Process-ExampleObjects scope and directly into the Set-ExampleObjects scope within which the current object is again available
in $_.
Adding Scriptblocks
So far, this is 'fairly simple'. As far as this is concerned, you would never see or use $_ at all. However, complexity is added when we add scriptblocks. Let's modify our last pipeline a bit:
Get-ExampleObjects | Process-ExampleObjects -Filter {$_.Name -like "RAS*"} | Set-ExampleObjects
Now, you may think "Hey! Aren't we using $_ as a parameter!?" on the -Filter Parameter of Process-ExampleObjects.
No, we are not.
What we do, is pass a Scriptblock into Process-ExampleObjects. Think of this above line like this:
Get-ExampleObjects | Process-ExampleObjects -Filter [Scriptblock] | Set-ExampleObjects
The scriptblock thing is passed as it is into the Process-ExampleObjects scope of the pipeline, and is applied to the objects while they are within the command. It's similar to passing a static line of text to a function, which means, on the inside "$_"
arrives as it is, not as its value (which after all would still be null).
Static external variables are still read as such and work. This should work:
$string = "RAS*"
Get-ExampleObjects | Process-ExampleObjects -Filter {$_.Name -like $string} | Set-ExampleObjects
The reason this was implemented in such a way is simple: It allows us to dynamically alter the behavior of a function. But for us to be able to do this, we must somehow be able to refer to the input. That's what $_ is for.
Cursed Nesting
Finally what probably messed with your mind the most, we reach nesting pipelines.
An example where it went wrong:
Import-csv input.csv | foreach {$UserPrincipalName = $_.UserPrincipalName;Get-ADUser -filter {userprincipalname -eq $userprincipalname} -properties * | set-aduser -UserPrincipalName "$($_.samaccountname)@test.local"}
is the same as
Import-csv input.csv | foreach [Scriptblock 1]
This means you get the content of input.csv, pass it via the pipeline to the foreach command, which applies the Scriptblock to each of them.
This scriptblock then is this:
# Scriptblock 1
{$UserPrincipalName = $_.UserPrincipalName; Get-ADUser -filter [ScriptBlock 2] -properties * | set-aduser -UserPrincipalName "$($_.samaccountname)@test.local"}
Scriptblock 2 is not an issue and works just fine (though it is its own special case, but not the issue of the matter).
However, here comes the catch:
The "Get-ADUser | Set-ADUser" segment is a nested pipeline, and as far as "$_" is concerned, that's like working with braces in mathematics: Inner brace first.
Which means for all practical purposes, that once you are past the first pipeline symbol ("|") you can no longer refer to the $_ of the outer Scriptblock 1 until the pipeline is finished. However, before you enter Set-ADUser, $_ doesn't hold a value
yet, which is why the UserPrincipalName will be set to "@test.local"
Takeaway notes:
- When creating nested pipelines in scriptblocks, after the first "|" you can no longer refer to the original "$_" of the scriptblock until the nested pipeline concludes.
Cheers and I hope that was more comprehensible,
Fred
There's no place like 127.0.0.1