Confused about Powershell parameter documentation

Question

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

If you are not sure use Format-Table to see properties, it is great at enumerating through objects : get-service | Format-Table. If you have a group property use get-service | foreach-object { $_.Group }. I like doing following for debugging : get-service | foreach-object { $_ | Format-Table } — jdweng
– jdweng, Commented Dec 4, 2022 at 21:49

Santiago Squarzon · Accepted Answer · 2022-12-04 22:24:43Z

1

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'

edited Dec 4, 2022 at 22:24

answered Dec 4, 2022 at 22:09

Santiago Squarzon

65.5k5 gold badges26 silver badges59 bronze badges

Sign up to request clarification or add additional context in comments.

7 Comments

Dess Over a year ago

Can you please explain why this works: 'common' | Get-Verb * ; I as read it, that would have tried to bind 'common' at position 0 which, as you demonstrated, is -Verb.

Santiago Squarzon Over a year ago

no, position 0 is * in this case. * is bound to -Verb and 'common' is bound by pipeline to -Group

Dess Over a year ago

Also, why get-verb 'add' works, but 'add' | get-verb doesn't?

Dess Over a year ago

Ok, want to make clear that I meant: The ProxyCommand output says that -Verb param is at position 0, and it accepts pipeline input, and that input type is string[]. The design seems ok to me, but still doesn't work, which is weird.

postanote Over a year ago

You can have PowerShell show you how your code or other code like 'common' | Get-Verb and 'common' | Get-Verb * is processed/evaluated in real-time by using the cmdlets Invoke-ScriptAnalyzer and Trace-Command.

|

Collectives™ on Stack Overflow

Confused about Powershell parameter documentation

1 Answer 1

7 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

7 Comments

Your Answer

Sign up or log in

Post as a guest

Related