ValueFromPipelineByPropertyName attempts to fill a parameter from the property of an object in the input pipeline. When filling a value by property name, the name and type of the property is important, but not the object that implements the property.
For example, a function might be created to accept a string value from a Name property:
function Get-Name {
[CmdletBinding()]
param (
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[String]$Name
)
process {
$Name
}
}
Any command that returns an object which contains a Name property in a string is acceptable input for this function. Additional parameters might be defined, which would further restrict the input object type, assuming the new properties are mandatory:
function Get-Status {
[CmdletBinding()]
param (
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[String]$Name,
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[String]$Status
)
process {
'{0}: {1}' -f $Name, $Status
}
}
This new function would accept pipeline input from Get-Service, as the output from Get-Service has both Name and Status properties. Using Get-Member against Get-Service would show that the Status property is an enumeration value described by System.ServiceProcess.ServiceControllerStatus. This value is acceptable to the Get-Status function as it can be coerced into a string, which satisfies the Status parameter.
The previous function is not limited to a specific input object type. A PSCustomObject can be created with properties to satisfy the parameters for the Get-Status function:
[PSCustomObject]@{ Name = 'Name'; Status = 'Running' } | Get-Status
As with the ValueFromPipeline input, the parameter binder will attempt to fill as many of the parameters as possible from the input pipeline. Trace-Command, as used when exploring ValueFromPipeline, can be used to show the behavior of the parameter binder.