Process Pipeline Data in PowerShell Parameters

PowerShell pipeline parameters are a powerful feature that enables you to streamline data flow between commands and functions. When creating custom PowerShell functions, two key attributes (ValueFromPipeline and ValueFromPipelineByPropertyName) allow you to accept and manage data passed through the pipeline more efficiently.

Understanding how these PowerShell pipeline parameters work will help you build more dynamic scripts that handle various input types.

What is the pipeline in PowerShell?

The PowerShell pipeline ( | ) is a powerful feature that allows you to pass the output of one command as the input to another command, enabling a seamless flow of data between commands or functions. Instead of storing intermediate results in variables, the pipeline lets you process data directly in a chain, simplifying complex tasks.

The example below uses the Get-Process cmdlet to retrieve the running processes on the local system. PowerShell sends the results over to Where-Object to filter the processes where the CPU usage is greater than 10.

Get-Process | Where-Object { $_.CPU -gt 10 }

Another example uses the Get-ChildItem cmdlet to find MP4 files and then pipes the results to the Remove-Item cmdlet. Piping the first cmdlet’s results to the remove cmdlet eliminates storing the results in an intermediary variable.

Get-ChildItem -Filter *.mp4 -Recurse | Remove-Item

The PowerShell pipeline supports both objects and raw data, allowing you to pass complex data structures into custom functions using parameters like ValueFromPipeline or ValueFromPipelineByPropertyName. These parameter attributes improve script flexibility, scalability, and efficiency by processing input directly from the pipeline, eliminating the need for intermediate variables or complex loops. Whether handling simple strings or complex objects, these pipeline parameters help streamline and optimize your script logic for more effective automation.

ValueFromPipeline parameter attribute

The ValueFromPipeline attribute allows a PowerShell function parameter to accept entire objects passed through the pipeline. When this parameter is enabled, any object passed through the pipeline is bound to the parameter, letting you work with the whole item in your function.

Here’s an example demonstrating how to use the ValueFromPipeline attribute on the Message parameter. The parameter receives every item passed through the pipeline. Note the usage of the process block to iterate over each pipeline object automatically.

Read More: PowerShell Begin Process End Blocks Demystified | Jeff Brown Tech

function Get-Message {
    [CmdletBinding()]
    param (
        [Parameter(ValueFromPipeline)]
        [string]$Message
    )
    process {
        Write-Output "Message: $Message"
    }
}

Passing the strings “Hello” and “World” to the function through the pipeline attach to the Message parameter for processing.

ValueFromPipelineByPropertyName parameter attribute

The ValueFromPipelineByPropertyName parameter works differently. Instead of binding the entire object, it matches a specific property of the object passed through the pipeline to a corresponding parameter in your function.

This PowerShell pipeline parameter is particularly useful when dealing with objects that have multiple properties. It allows you to select only the properties that are important to your function.

The example function below Get-UserDetails has two parameters: Name and Title. The process block outputs a string showing the name and title of the incoming object.

function Get-UserDetails {
    [CmdletBinding()]
    param (
        [Parameter(ValueFromPipelineByPropertyName)]
        [string]
        $Name,
        [Parameter(ValueFromPipelineByPropertyName)]
        [string]
        $Title
    )
    process {
        Write-Output "User $Name holds the position of $Title"
    }
}

Define an array $users with two custom objects containing the properties Name and Title. Piping the array to the Get-UserDetails function binds each object’s named keys to their matching parameter names.

Comparing ValueFromPipeline and ValueFromPipelineByPropertyName

When deciding which PowerShell pipeline parameter to use, it’s essential to understand the key differences:

• ValueFromPipeline: Binds the entire object passed through the pipeline to a single parameter. This method is ideal when working with the whole object or input value.
• ValueFromPipelineByPropertyName: Binds a specific property of the pipeline object to a matching parameter in your function. This method is useful when you only need specific data from complex objects.

PowerShell Parameters Pipeline Summary

Mastering PowerShell pipeline parameters is crucial for writing efficient, reusable scripts. Whether you’re using ValueFromPipeline to process whole objects or ValueFromPipelineByPropertyName to target specific properties, these attributes allow you to take full advantage of PowerShell’s powerful pipeline functionality. By incorporating these pipeline parameters into your functions, you can improve the efficiency and readability of your scripts, making them more adaptable to various inputs and use cases.

Reference:
Adding Parameters that Process Pipeline Input – PowerShell | Microsoft Learn