Question about pipeline variables and pipeline shortcut(s)?

Question

In the creation of a script I'm writing, I ran across the use of what appears to be a pipeline shortcut that I have never seen before.

For example:

$acl | select -expandproperty Access | ? {$_.IdentityReference -eq "AD\$Group"}

     can be shortened to

$acl.Access.Where({$_.IdentityReference -eq "AD\$Group"}) 

What is this? $acl.Access makes sense to me as it's just a property reference but I do not see any such .Where() method being available on this object. As such it seems .Where({}) is some sort of pipeline shortcut for " | Where-Object {}". Where can I find documentation for such a thing? Do others like this exist?

Second question. I have a need to add a calculated property to my results, and within the property expression I have to perform piping as well, so where I would typically just reference $_ from the parent pipeline, this is lost within the expression statement.

I can get around this by using -PipelineVariable up within the pipeline, but it seems this only works when used with cmdlets and is not available when starting a pipeline with a variable (which I do often). Is there a way around this?

This works:

$acl = Get-Acl -Path "AD:\$dn"
$acl | select -expandproperty access -PipelineVariable AccessRight | ? {$_.IdentityReference -eq "AD\$Group"} | select *, @{N='ObjectTypeName';E={($ADGuidMap.GetEnumerator() | ? {$_.Value -eq $AccessRight.ObjectType}).Name}}  

I'd really like to be able to do this with the shortcut as anywhere I can shorten my oneliner I would like to do. Unfortunately the following will not work as I cannot use pipelinevariable at this location.

$acl.Access.Where({$_.IdentityReference -eq "AD\$Group"}) -PipeLineVariable AccessRight | select *, @{N='ObjectTypeName';E={($ADGuidMap.GetEnumerator() | ? {$_.Value -eq $AccessRight.ObjectType}).Name}} 

It's always bugged me about not being able to use Pipeline variables outside of cmdlets so I finally figured I'd ask if there was some sort of way around that.

Answer 1

As for the first question:

• The .Where() and .ForEach() methods are intrinsic members, i.e. members that PowerShell implicitly makes available on objects of any type.

• While they function similarly to their cmdlet counterparts, Where-Object and ForEach-Object, there are important differences.

  • See this answer for more information.

As an aside: You could have simplified your command even when using the Where-Object cmdlet, namely with simplified syntax:

$acl.Access | Where-Object IdentityReference -eq "AD\$Group"

---

As for the second question:

Because the .Where() method isn't a cmdlet, you cannot use the common
-PipelineVariable parameter with it.

Given that .Access typically returns multiple objects, using the pipeline with -PipelineVariable enables an elegant solution.

If you do want to avoid the pipeline (operator), you can combine the .Where() and .ForEach() methods as follows, with the help of an intermediate (regular) variable:

$acl.Access.
  Where({ $_.IdentityReference -eq "AD\$Group" }).
  ForEach({
      $aclEntry = $_
      Select-Object -InputObject $aclEntry -Property *, 
        @{
          N = 'ObjectTypeName'
          E = { ($ADGuidMap.GetEnumerator().Where({ $_.Value -eq $aclEntry.ObjectType })).Name }
        }
    })

---

Update:

As you've discovered yourself, if you stick with a pipeline, you can combine -PipeLineVariable with Write-Output in order to capture each element of an array / collection in a pipeline variable as it flows through the pipeline, for use a later script block, as the following (contrived) example shows:

$array = 0..3
Write-Output $array -Pipeline arrayElement |
Where-Object { 0 -eq $_ % 2 } | # filter out odd numbers
 ForEach-Object { $_ + 1 } | # add 1
 ForEach-Object { "pipeline variable / `$_: $arrayElement / $_" }

Output, which shows that each element of input array $array was individually captured in pipeline variable $arrayElement:

pipeline variable / $_: 0 / 1
pipeline variable / $_: 2 / 3