Suggestion: make it easier to discover which cmdlet parameters accept pipeline input, via the syntax diagram

^{Related: #4715 and #4626.}

Currently, it is not easy to discover which of a given cmdlet’s / advanced function’s parameters accept pipeline input and how (by value and/or by property name):

Using the example of Rename-Item:

• You can use Get-Help Rename-Item -Full and then browse the entire topic for Accept pipeline input? lines

• You can use a nontrivial command such as the following:
  Get-Help Rename-Item -Parameter * | ? pipelineInput -like 'true*' | Select-Object Name, Type, pipelineInput

The above yields:

name        type                       pipelineInput                 
----        ----                       -------------                 
Credential  @{name=PSCredential; uri=} true (ByPropertyName)         
LiteralPath @{name=String; uri=}       true (ByPropertyName)         
NewName     @{name=String; uri=}       true (ByPropertyName)         
Path        @{name=String; uri=}       true (ByValue, ByPropertyName)

Neither option is convenient.

Perhaps the syntax diagrams could be enhanced with symbols that reflect pipeline-binding behavior?

Something along the lines of (these are mere examples; the idea is to be concise):

• | … by value (only)
• ⌠ … by property name (only)
• |⌠ … by both value and property name

Applied to the Rename-Item example, with the symbols placed inside (...) after the parameter (for example):

Rename-Item [-Path(|⌠)] <String> [-NewName] <String> [-Credential(⌠) <PSCredential>] [-Force] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction <SwitchParameter>] 
    [<CommonParameters>]
    
Rename-Item [-NewName(⌠)] <String> [-Credential(⌠) <PSCredential>] [-Force] [-PassThru] -LiteralPath(⌠) <String> [-Confirm] [-WhatIf] [-UseTransaction <SwitchParameter>] 
    [<CommonParameters>]

Note: A crucial piece missing from the above is that parameters have aliases and that binding by property name often happens via those aliases; e.g., Select-String’s -LiteralPath has an alias of PSPath, and when you pipe Get-ChildItem output to Select-String, the objects bind by .PSPath, not .LiteralPath.

Written as of PowerShell Core v6.0.0-beta.3.

[rkeithhill]

This is somewhat orthogonal to the Get-Command -Syntax request but a number of us PS users, rely on a command called Get-Parameter to get this info. It comes with the PSCX module. Here’s the output from this command for Rename-Item:

PS C:\> Get-Parameter Rename-Item

    Command: Microsoft.PowerShell.Management/Rename-Item
    Set:    ByPath *


Name                   Aliases      Position Mandatory Pipeline ByName Provider        Type
----                   -------      -------- --------- -------- ------ --------        ----
Confirm                {cf}         Named    False     False    False  All             SwitchParameter
Credential             {Cr*}        Named    False     False    True   All             PSCredential
Force                  {F*}         Named    False     False    False  All             SwitchParameter
NewName                {N*}         1        True      False    True   All             String
PassThru               {Pas*}       Named    False     False    False  All             SwitchParameter
Path                   {Pat*}       0        True      True     True   All             String
UseTransaction         {usetx}      Named    False     False    False  All             SwitchParameter
WhatIf                 {wi}         Named    False     False    False  All             SwitchParameter


    Command: Microsoft.PowerShell.Management/Rename-Item
    Set:    ByLiteralPath


Name                   Aliases      Position Mandatory Pipeline ByName Provider        Type
----                   -------      -------- --------- -------- ------ --------        ----
Confirm                {cf}         Named    False     False    False  All             SwitchParameter
Credential             {Cr*}        Named    False     False    True   All             PSCredential
Force                  {F*}         Named    False     False    False  All             SwitchParameter
LiteralPath            {PSPath, L*} Named    True      False    True   All             String
NewName                {N*}         1        True      False    True   All             String
PassThru               {Pas*}       Named    False     False    False  All             SwitchParameter
UseTransaction         {usetx}      Named    False     False    False  All             SwitchParameter
WhatIf                 {wi}         Named    False     False    False  All             SwitchParameter

Personally, I find this far easier to parse than the output of Get-Command -Syntax.

[dragonwolf83]

Prefixing the command doesn’t help if another module uses it and didn’t prefix it themselves. You could use Import-Module -Prefix "CX" -Name PSCX to explicitly load PSCX with a custom prefix, though that would not be good for code re-use.

What I do is modify the PSD1 file in the module directory to comment it out from CmdletsToExport. However, it would be lost in an upgrade and need to be redone if that command is still there.