CODEWITHSUNDEEP
powershell
Dess
Dess

Reputation: 2649

Confused about Powershell parameter documentation

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

Upvotes: 1

Views: 141

Answers (1)

Santiago Squarzon
Santiago Squarzon

Reputation: 59822

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'

Upvotes: 1

Related Questions