I'm not sure if I'm confused about how some of Powershell documentation regarding parameters work, or if the documentation has some mistakes.

For example, the docs for get-verb [1] say that for parameter -Group, the cmdlet accepts pipeline input, at position 0. However, in the Inputs section, it says "None". Also, this doesn't work:

"common" | get-verb

Since the docs says that -Group accepts pipeline input at position 0, doesn't that imply that the above code should work?

The docs for foreach-object [2] say that for parameter -InputObject, the position is "named". However, it accepts the -InputObject parameter at position 0.

get-service | foreach {$_.name}

Shouldn't that parameter's doc say Position: 0?

[1] https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/get-verb?view=powershell-7.3

[2] https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/foreach-object?view=powershell-7.3

CodePudding user response：

Regarding the first question, the docs are in fact showing inaccurate information and GitHub Issue #9522 was raised to correct this.

Looking at Get-Help we see the following:

PS ..\pwsh> Get-Help Get-Verb -Parameter * | Select-Object Name, Position

name  position
----  --------
Group 0
Verb  1

Yet, if we look at the autogenerated param block using ProxyCommand.Create:

[System.Management.Automation.ProxyCommand]::Create((Get-Command Get-Verb))

We can see the following (positions are reversed from what the doc is showing us):

param(
    [Parameter(Position=0, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)]
    [string[]]
    ${Verb},

    [Parameter(Position=1, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)]
    [ValidateSet('Common','Communications','Data','Diagnostic','Lifecycle','Other','Security')]
    [string[]]
    ${Group}
)

We can also clearly see that -Verb is actually position 0 trying positional binding and one valid verb:

Get-Verb Add

As for 'common' | Get-Verb not working, it does as long as we're also binding -Verb in the call to the cmdlet, either by value from pipeline by property name or positional binding:

# All verbs in `Common` groups. Works fine.
# Positional Binding on `-Verb` (Position 0)
'common' | Get-Verb *

# `Add` verb in `Common` groups. Also works fine.
# `ValueFromPipelineByPropertyName` on both params
[pscustomobject]@{ Group = 'common'; Verb = 'Add' } | Get-Verb

Regarding the second statement / question:

...However, it accepts the -InputObject parameter at Position 0.

This is incorrect, -InputObject in fact can be bound either from pipeline or named. Also note that this parameter is not intended to be used manually in most cases.

Position 0 is actually the -Process parameter and we can clearly see it by testing this code:

ForEach-Object { $_ } -InputObject 'hello'