One of the consistent questions about PowerShell is: what’s the best way to write a script or a function to process pipeline objects and be able to take it’s parameters as a normal function?
Of scripts and functions
The first thing to know is that in PowerShell, there’s really no difference between a script (just a file with a .ps1 ending) and a function as you’ll see written below. If you take a function Get-Square, and remove the first and last lines ( Function Get-Square { … } ) you could put them in a file called “Get-Square.ps1” in your PATH, you use them exactly the way you would the function that was pre-loaded into memory by dot-sourcing or pasting it on the command line. Of course, doing that easily requires writing the function parameters on their own line using PARAM(...) syntax, which is why I recommend doing that.
Of functions and the pipeline
When your script or function is used on the pipeline its begin block is called once when the pipeline starts up, and then the process block is called repeatedly: once to process each pipeline object, and finally, the end block is called after all the objects have been processed through the whole pipeline. If you don’t understand that, you should play with this function, try calling it by passing a series of numbers through multiple instances of it:
function Test-SquarePipe {
PARAM( $label, $color="White" )
BEGIN { Write-Host "Begin $Label" -Foreground $color }
PROCESS {
Write-Host "$Label `t $_" -Foreground $color
$_ * $_
}
END { Write-Host "End $Label" -Foreground $color }
}
# for example ...
1..5 | Test-SquarePipe one cyan | Test-SquarePipe two yellow | Test-SquarePipe three green
Incidentally, if you don’t specify the begin, process, or end blocks, the body of your function is treated as the end block. This is so that you can use the special $Input variable, which collects all the things passed in on the pipeline, and thus only works in the end block. That would allow the following function to behave the same way regardless of whether it was invoked on the pipeline or by passing an $InputObject. Notice, however, the difference between this, and the function above.
Function Test-SquareEnd {
PARAM( $label, $color="White", $InputObject )
BEGIN { Write-Host "Begin $Label" -Foreground $color }
PROCESS { Write-Host "$Label `t $_" -Foreground $color }
END {
## because one of $Input or $InputObject must be null:
Foreach($item in $Input + $InputObject) {
Write-Host "$Label `t $item" -Foreground $color
$item * $item
}
}
}
# and test it like this
1..5 | Test-SquareEnd one cyan | Test-SquareEnd two yellow | Test-SquareEnd three green
# Or like this
1..5 | Test-SquarePipe one cyan | Test-SquareEnd two yellow | Test-SquareEnd three green
Our challenge
The basic idea here is to rewrite that function such that it can be used to process a set of numbers from either the pipeline or an argument, without interfering with the processing of other parameters. We require that the function process items as they come in, rather than waiting until it’s received all input before processing them the way Test-SquareEnd does.
In PowerShell 2.0 this would be easy
In the current CTP 3 of PowerShell 2, you just specify ValueFromPipeline=$true for the parameter you want to set from the pipeline, and the function will work the same way whether you pass the numbers as a parameter or along the pipeline — you can even control which attribute of the objects on the pipeline will be used, but that’s a whole other article.
Function Get-Square {
PARAM(
$label
, [ConsoleColor]$color = "White"
, [Parameter(ValueFromPipeline=$true)]
[Int[]]$InputObject
)
BEGIN { Write-Host "Begin $Label" -Foreground $color }
END { Write-Host "End $Label" -Foreground $color }
PROCESS {
ForEach($i in $InputObject) {
Write-Host "$Label $i" -Foreground $color
$i * $i
}
}
}
## Either way we call these, they have the same output
## Unlike what Get-SquarePipe or Get-SquareEnd
1,2,3,4 | Get-Square one green | Get-Square two cyan
Get-Square one green 1,2,3,4 | Get-Square two cyan
Of course, PowerShell 2.0 is still in beta status, and even after it’s released you may need to write scripts that are backwards compatible to PowerShell 1.0, and the excercise of doing so may help you to understand more about how PowerShell functions work, and particularly how they behave in the pipeline.
Our solution
Since in a PowerShell 1.0 function it’s not really supported directly, we need to do some extra work:
function Get-Square {
PARAM(
$label = ""
, [ConsoleColor]$color = "White"
, [Int[]]$InputObject = $null
)
BEGIN {
if ($InputObject) {
## If you accepted additional params, you'd need to pass those in
Write-Output $InputObject | &($MyInvocation.InvocationName) -Label $label -Color $color
## break
} else {
Write-Host "Begin $Label" -Foreground $color
}
}
PROCESS {
## If you specify a type for $InputObject, test for that here
if($_ -is [Int]) {
Write-Host "$Label $_" -Foreground $color
$_ * $_
} elseif($_) {
throw "$_ is not a System.Int32"
}
}
END {
if(!$InputObject) {
Write-Host "End $Label" -Foreground $color
}
}
}
An explanation
Of course, this is just an example method, squaring things isn’t that exciting — but what’s special about it is that the output is almost exactly the same whether you call it with parameters Get-Square 1,2,3,4 or on the pipeline: 1,2,3,4 | Get-Square.
The trick is that it actually executes the same way in either case:
- If you call it by passing the int (or array of ints) as an argument (
$InputObject), it calls itself and passes those values on the pipeline. - When the integers are passed on the pipeline, the special pipeline iterator variable
$_is set, and the process block is executed.
- When it has to (re)invoke itself, it passes any other parameters as parameters, which means you need to have default values for them.
There is one tiny difference in the processing, which in real-world use is practically never noticeable (you can see it in our example if you call it like this):
Get-Square one green 1,2,3 | Get-Square two cyan
1,2,3 | Get-Square one green | Get-Square two cyan
You’ll see that unlike the PowerShell 2.0 pipeline function, when you pass the numbers as a parameter, the first one of them actually gets passed through the process block before the begin block of the second function on the pipeline is called. This usually doesn’t have any effect, but it’s something to keep in the back of your head.
A few precautions:
- You have to default values for parameters, because you’ll be passing them all as named parameters, in the re-invoke step, and
$nullcan cause problems. - If you need to do additional processing in the
beginblock, you should only do so in anELSEcase: when $InputObject is null. That way, the code will only execute once each time you call the function. - The same goes for the
endblock: you have to keep your code in anIf(!$InputObject)block to avoid executing it twice (when you pass the values as an argument, and it re-invokes itself).
- The test cases in the
processblock must wrap all of your process block code, so that you don’t process the arguments twice, and you shouldn’t refer to $InputObject, but instead should use the automatic$_variable which is the value passed when the function is (re)invoked via the pipeline.
Here’s some sample output, in case you’re wondering:
PS> Get-Square test cyan 2,3,4
Begin test
test 2
4
test 3
9
test 4
16
End test
PS> 2,3,4|Get-Square test cyan
Begin test
test 2
4
test 3
9
test 4
16
End test