You know, I’ve looked at your articles about cmdlets/functions in the pipeline and I feel you’re missing something. The purpose of the InputObject parameter is to pass in a collection as a single object. This is as opposed to using the pipeline where a collection is passed along the pipeline one item at a time. There are cases where you want to pass in a collection as a collection.

Quite simply, I disagree. The documentation for these parameters says quite clearly that inputObject “Specifies an object or objects to input to the cmdlet.” This clearly means that I should be able to pass multiple objects, and have them treated as multiple objects, not as a single array object.

If you look at your example (Select -First 3 -Unique -InputObject $a), this does in fact work. It receives one object, an array. It then selects the first 3 objects, but there is only 1 so that is moot. And lastly it selects unique objects, but again there is only 1 so that is moot as well and finally the object is output using the default formatter. In this case the default formatter is showing the contents of the array.

In this example, Select-Object has no reason to take a single object as an input object, at all. The only time that it would be useful for Select-Object to take a single inputObject would be in combination with the property parameters. In fact, if you want to Select-Object from an array to get the first of last n objects, or to get a set of unique objects, you have to pass the objects in via the pipeline — there’s no other way to make it select from an array. If that was indeed the intent, it should have been written as a separate ParameterSet, and the documentation should be changed to reflect that only a single object can be passed in, and that you can’t use the inputObject parameter with the first, last, or unique parameters at all. That’s worse than useless, it’s misleading and confusing.

Kirk is absolutely right that if you assume that the InputObject argument is only allowed to take a single object, then the behavior is correct – but it’s not logical. In fact, the behavior you see in the output of this command is so useless as to be a bug – even if the documentation did not say the parameter accepts multiple objects as input:

I know that that’s the way the built-in cmdlets work.

But quite frankly, just because someone important wrote something useless is no reason to emulate the behavior. The inputObject parameter IS the same parameter which pipeline objects go into. There’s no logical explanation for us to get different results when we pass an array in via the parameter by name instead of via pipeline: the PowerShell pipeline passing the things in the pipeline into the –inputObject parameter … it’s not using some mystical variable like it does in script functions.

Of course, we all know the powershell pipeline unwraps arrays — that’s convenient, and we can work around it when we really want to pass an array in:

My point in all of this is that InputObject is actually a very useful parameter, because there are cases where you really want to pass a collection as a collection into a cmdlet and then do something with it. By making InputObject instead split the collection passed in and pipeline it through, you’re forcing users to wrap collections in an array just to get them passed in as a collection, and personally I don’t feel they should have to do that.

While it’s true that passing in an array is sometimes desirable that’s not the reason the parameter exists, and I don’t believe it should be the default behavior here. It should be just as easy for me to use the cmdlet with the inputObject parameter directly as it is to input them via the pipeline. If I put in unwrapping for the inputObject parameter, you can work around it in the same way I did in the examples above. Incidentally, I think *PowerShell* should unwrap arrays to ValueFromPipeline parameters regardless of whether they’re on the pipeline, but I recognize it’s probably too late for that.

Basically, this is my argument: If inputObject unwraps arrays, the syntax for passing an array by wrapping it in @(,$array) is simple, for those rare occasions when that’s actually what you want. But if it does not unwrap arrays, you’re forced to call it via a separate pipeline, because unwrapping the array and passing it in one at a time in a foreach loop will almost certainly not do the same thing, and this is much uglier — and not compatible with use within the pipeline, particularly if you need to pass the pipeline output into a different parameter.

I guess my final word would be to agree with Kirk that “InputObject … isn’t documented clearly enough” … in fact, it’s clearly behaving incorrectly according to the documentation, and that’s why I originally proposed to unwrap the inputObject parameter when it’s passed as a parameter: to make it work the way the documentation suggests it would, which seems to me to be a better way than the way it actually works.

The question was: why doesn’t this have any output? Well, the answer is: it can’t have any output. The filter outputs true or false for each item passed into it, but the where scriptblock doesn’t actually pass anything into the filter! Of course we quickly fixed his problem the right way by rewriting the filter to output the items, and getting rid of the where-object call completely … but when I started wondering where he had gotten the bizarre idea to use a filter like that, his answer was: “I read about_filter.” So I went and looked, and sure enough, the example pasted above is straight out of about_filter. And it’s as wrong as it can possibly be.

Let me fix it, and then offer some clarification below. In about_filter there is an example like this: Get-Process | where {$_.processname -like "[a-m]*"} and then a table describing each element of the Where-Object command, and just below it, there is some text about the filter command. Mentally replace that text with this:

You can create a predefined filter by creating a special type of function. When defining the function, you may specify that it is a filter. For the filter script block, you should output items if they pass the test you saw in the preceding example. For instance, the following command creates a filter named process-a-m:

filter process-a-m
    {
        if( $_.processname -like "[a-m]*" ) { Write-Output $_ }
    }

You can then use the filter name in place of your Where-Object command to retrieve the filtered data, as shown in the following example:

Get-Process | process-a-m

The values returned by the command are the same as they would have been had you specified the conditions using the Where-Object cmdlet as above, but the filter is much easier to reuse on multiple calls, particularly if the conditions were more complicated.

Of course, a filter function can take parameters, just like any other function, so you could make the range of starting letters more flexible:

filter process-range([char]$a="a",[char]$m="m")
    {
        if( $_.processname -like "[$a-$m]*" ) { Write-Output $_ }
    }

Now you can use this filter to select between any two letters quite easily:

Get-Process | process b j

Functions vs. Filters

To be clear, functions in PowerShell aren’t like functions in other programming languages, although they can just have a body (and be like other functions) they can instead have pipeline syntax. A function (just like a cmdlet) which is meant to be used in the pipeline has three separate bodies: begin, process, and end, but a filter has only the process part of the body.

Of course, there are other uses for filters than just limiting which objects come through … anything that you could do with foreach-object or where-object, you can basically do with a filter in a much more reusable way. So you don’t have to write the same thing to the output as what came in the input, you could actually add to it, or remove from it. A filter for processes could look use Win32_Process to look up their ‘owner’ and append it as a property, or could return the process path and name as text …

If you’re new to all of this, let me just present an example function to hopefully clear things up:

A function without an internal pipeline block is basically like the begin block of a pipeline-enabled function: the only things present are the parameters to the function (if there are any). Then, process is called once for each item in the pipeline, with the current item set as the $_ variable. Finally, end is called, and you still have the last item in the pipeline present. The scope persists through each part of the function (so you will see that $counter maintains it’s value). The important distinction between this and a function without a process body is that a normal function will only be called once when it is in a pipeline — regardless of how many things are in the pipeline. If you called DemoTheCount with a list of processes, like Get-Process g* | DemoTheCount, you would get something like this (depending on the processes running on your PC):

A filter doesn’t have separate parts, because the whole filter is the process part of the function. If we were to take the process portion of our DemoTheCount function and turn it into a filter, it would only work because the dynamic language would automatically initialize $counter to zero and let you increment it — anything more complex (or where the type couldn’t be deduced) would not. When you create a filter using the filter keyword, it’s pure syntax sugar. The filter process-a-m defined in my correction to the documentation is exactly the same as this function:

You can verify this by creating both of them and then comparing the contents of the resulting functions ((get-content function:\process-a-m) -eq (get-content function:\reprocess-a-m). The filter keyword simply creates a function and with the filter body as the process body for the function.