Parameter binding maps command-line values and pipeline objects to command parameters. PowerShell first binds explicitly named arguments, then positional arguments, checks mandatory parameters, and then considers pipeline input. section 4.2 section 4.3.2
Pipeline binding uses two main routes. ByValue passes the entire incoming object to a compatible parameter; ByPropertyName looks for a matching property and passes that property's value. PowerShell tries ByValue first. section 4.3 section 4.4.1
Use this sequence when designing or troubleshooting a pipeline:
- Inspect the producing command's object type with Get-Member, then check the receiving command's help for parameters accepting pipeline input ByValue. section 4.3
- If the object type cannot bind ByValue, look for a property whose name matches a parameter accepting pipeline input ByPropertyName. section 4.3.3 section 4.4.1
- Prefer one ByValue parameter for a data type; use multiple ByPropertyName parameters when the tool needs several pipeline mappings. section 4.4.3
- Trace real commands with Trace-Command -Name ParameterBinding, but remember that the expression runs and can change system state. section 4.3.1
When the binding route changes
Get-Process | Stop-Job cannot bind the Process object to Stop-Job's Job parameter ByValue. PowerShell then finds the process's ID property and binds it to Stop-Job's Id parameter ByPropertyName. Binding succeeds technically, but the ID belongs to a process rather than a job, so the command reports that no matching job exists. section 4.4.1
Enabling pipeline input in an advanced function
Declare [Parameter(ValueFromPipeline=$True)] on a parameter such as [string[]]$ComputerName, then process each incoming value inside PROCESS{}. Add ValueFromPipelineByPropertyName when objects with a ComputerName property should also work. The same function can support both Get-MachineInfo -ComputerName ONE,TWO,THREE and "ONE","TWO","THREE" | Get-MachineInfo. section 11.1.1
Trace-Command -Name ParameterBinding -Expression {get-process |
select -first 1} -PSHost
Trace a short pipeline to inspect the parameter-binding decisions PowerShell makes for each command. section 4.3.1
