How does -InputObject parameter of the Sort-Object cmdlet work?

Question

PowerShell 4.0

I read about Sort-Object cmdlet here (TechNet page). I don't understand how to use -InputObject parameter. That page hasn't examples for it. Also I didn't find this info in Internet. I would be very grateful for the examples of its using, or for the links to Internet pages with that info.

I have tried to use it how I understand its purpose (according documentation):

$items = ('a','b','c','d')
$result = sort -InputObject $items -Descending

But the result variable has the same value like it has items instead of its descended version.

Thank you.

That's because `Sort-Object` (by design) doesn't work when you bind your input collection to `-InputObject` by name - you need to pipe your values to `Sort-Object`, at which point they're automatically bound to the `InputObject` parameter. In that sense, all the examples in the help page shows the (implicit) use of `-InputObject` — Mathias R. Jessen, Feb 09 '16 at 10:46
I don't understand your answer. I added my attempt (code example). — Andrey Bushman, Feb 09 '16 at 11:10
Yes, your sample shows my point exactly. The correct way of doing it is `$items |sort -Descending`. See `help sort -parameter inputobject` — Mathias R. Jessen, Feb 09 '16 at 11:12
I know how the `$items |sort -Descending` expression works. Also I have read the documentation before I created this theme. I want to get the example of `-InputObject` parameter using. In my code example I got not the same result that I expected. Your example don't use that parameter. — Andrey Bushman, Feb 09 '16 at 11:17
Yes it does, just not explicitly. Please run `Trace-Command -Name ParameterBinding -Expression {1,2|sort} -PSHost` to see what's actually going on with your input — Mathias R. Jessen, Feb 09 '16 at 11:21

score 16 · Accepted Answer · answered Feb 09 '16 at 12:41

InputObject is a generic name used for a parameter that takes pipeline input. It's part of internal PowerShell naming convention and there is nothing special about it.

Your example doesn't work as you think it should, because when you pass a collection to the InputObject parameter it's treated as a single item and not unwrapped to individial elements, so it doesn't get sorted. This allows you to sort a collection of collections.

Consider this examples:

This is how Sort-Object works:

function Add-Quotes
{
    Param
    (
        [Parameter(ValueFromPipeline = $true)]
        $InputObject
    )

    Process
    {
        "'$InputObject'"
    }
}

Note that array is automatically unwrapped by the pipeline, then idividial items are assigned the $InputObject variable in each iteration and then processed in Process block:

PS> $items | Add-Quotes
'a'
'b'
'c'
'd'

But when you pass a collection to the InputObject it's not iterated over, because there is no pipeline to unwrap it:

PS> Add-Quotes -InputObject $items
'a b c d'

Sometimes it's a desired behavior, sometimes you need to unwrap collections no matter where they came from. In this case you use internal foreach loop to do so:

function Add-Quotes
{
    Param
    (
        [Parameter(ValueFromPipeline = $true)]
        [string[]]$InputObject
    )

    Process
    {
        foreach($item in $InputObject)
        {
            "'$item'"
        }
    }
}

PS > $items | Add-Quotes
'a'
'b'
'c'
'd'

PS > Add-Quotes -InputObject $items
'a'
'b'
'c'
'd'

Hope this makes it clear for you.

js2010 · Answer 2 · 2017-07-06T18:58:39.350

The process block of a function automatically deals with a collection over a pipe, but not if it's passed as a command line argument. Some cmdlets put in an extra foreach loop to process -inputobject collections or lists, but most don't.

However, any parameter that can take input from a pipe, can also take a script block from the command line. So that may come in handy some time. You'll see examples like this in the help.

PS C:\> echo a,b,c,d | sort -InputObject { $_.ToUpper() } -Descending
D
C
B
A

How does -InputObject parameter of the Sort-Object cmdlet work?

2 Answers2

Linked