PowerShell Pipeline iteration - powershell

Question

I often write functions that need to accept pipelines like:
function Invoke-ExchangeHubChecks
{
[cmdletbinding()]
param
(
[Parameter(Position=0,Mandatory=$true,ValueFromPipeline=$true,ValueFromPipelineByPropertyName=$true)]
[object[]]$oServersToTest,
[int]$QueueWarnThreshold = 50,
[int]$QueueFailThreshold = 100
)
begin
{
$oHubTests = #()
$c=0
}
Process
{
$c++
$Server = $oServersToTest[0]
$oHubTests += [pscustomobject]#{
Identity = $server.Identity
Queue = "blah"
Count = $c
}
}
end
{
$oHubTests
}
}
end
{
$oHubTests
}
}
I often see code snippets with a foreach inside the process block. My understanding is that the process block replaces the need for the foreach block (in most cases).
I need to add a "filter" to the input object "$oServersToTest". I have used "where-object" to create the filter:
$Server = $oServersToTest[0] | Where-Object {$_.IsHub}
However, as it iterates over the collection, it is adding objects that don't match the where clause to the custom object, proved by $c:
Output:
Identity Queue Count
-------- ----- -----
Server01 blah 1
Server02 blah 2
Server03 blah 3
Server04 blah 4
Server05 blah 5
blah 6
blah 7
Server06 blah 8
Server07 blah 9
Server08 blah 10
Server09 blah 11
Server10 blah 12
blah 13
blah 14
Is this an example where I must use a foreach inside the process block:
Process
{
$c++
#$Server = $oServersToTest[0] | Where-Object{$_.IsHubServer}
$TestResult = #()
$oServersToTest | Where-Object {$_.IsHubServer} | Foreach-object{
$TestResult += [pscustomobject]#{
Identity = $_.Identity
Queue = "blah"
Count = $c
}
}
$oHubTests += $TestResult
}
End
{
$oHubTests
}
Which works, but why does this work and not the other way? To me, it's doing twice the work.
(Powershell 5.0)
TIA

Answer 1

I would use a foreach() loop inside the process block.
As Jeff Zeitlin points out, this also lets you support processing of collections with named parameters and pipelining alike.
The reason for using foreach() over ForEach-Object is three-fold:
Performance:
When the input collection is already in memory (which it is in both cases), the overhead from implicit parameter binding will make ForEach-Object slower than foreach()
Readability:
IMO, having a named variable (like $Server) makes the script more readable and you avoid confusion with nested ForEach-Object or Where-Object clauses inside the loop
Functionality:
With a plain ol' foreach(), you get fast flow control options like break and continue for free.
process {
$oHubTests += foreach($server in $oServersToTest |Where-Object {$_.IsHubServer}){
$c++
[pscustomobject]#{
Identity = $server.Identity
Queue = "blah"
Count = $c
}
}
}
If the only thing your cmdlet does is take the input and construct corresponding [pscustomobject]'s, then I would cut out the $oHubTests part completely, and just output the objects as they flow through:
function Invoke-ExchangeHubChecks
{
[CmdletBinding()]
param
(
[Parameter(Position=0,Mandatory=$true,ValueFromPipeline=$true,ValueFromPipelineByPropertyName=$true)]
[object[]]$oServersToTest,
[int]$QueueWarnThreshold = 50,
[int]$QueueFailThreshold = 100
)
begin {
$c=0
}
process {
foreach($server in $oServersToTest |Where-Object {$_.IsHubServer}){
$c++
[pscustomobject]#{
Identity = $server.Identity
Queue = "blah"
Count = $c
}
}
}
}

Answer 2

You are addressing one of the most complicated design structures of powershell for me. Creating a cmdlet that can process an array of objects as provided as a parameter or per item piped into the cmdlet.
For example do-something -input $items or $items | do-something.
The process block is meant mostly for when a cmdlet accept pipeline values. It doesn't replace the for loop as you think it. The pipe has already done an implicit loop on the collection although that is not 100% accurate but that is a different story. I'll continue with this somehow inaccurate statement for simplicity.
With such cases, the begin,process and end allow you to control what happens at each part of the pipe or imaginary loop. Before and end are executed only once and can used for initialization and finalizing. In the above example first begin executed, then process for each item piped from the collection and then end. But if the collection is used as a normal parameter then it's begin, process with a loop inside and then end.
I understand that is complicated but try to visualize with a do-something implementation that just writes to the host what is going on.
I had to understand this sequence when developing MarkdownPS. Check this example and the examples of usage on the root. Get-ChildItem | Select-Object Name | New-MDList. FYI the last example is a demonstration of the inaccurate statement I used in this answer.