PowerShell Pipeline Parameters: How to Create Pipeline-Ready Functions

You may have explored how the PowerShell pipeline works and how built-in cmdlets pass data from one command to another. But did you know you can create your own custom functions that also use the pipeline? Yes! With a parameter binding, your functions can act just like built-in cmdlets, seamlessly accepting data from the pipeline.

This tutorial will guide you to equipping your custom functions with the power of the pipeline, transforming how you automate and structure your PowerShell scripts.

Rather than relying on loops or manual inputs, unlock new levels of efficiency and flexibility in your scripting!

Enabling Pipeline Input with ValueFromPipeline

For your function to receive information from the pipeline, you must configure one or more parameters to accept it. You’ll configure parameters to use the ValueFromPipeline or ValueFromPipelineByPropertyName attribute.

Let’s start by setting up a function that installs software on multiple computers to pass an array of computer names to it without using a loop.

Add the ValueFromPipeline attribute to the ComputerName parameter, allowing each incoming pipeline object to be treated as the ComputerName parameter.

PowerShell will bind each incoming pipeline object to $ComputerName with this setup.

function Install-Software {
    param(
        [Parameter(Mandatory)]
        [ValidateSet(1,2)]
        [int]$Version,

        [Parameter(Mandatory, ValueFromPipeline)]
        [string]$ComputerName
    )
    process {
        Write-Host "I installed software version $Version on $ComputerName. Yippee!"
    }
}

Now, pass an array of computer names to the function using the pipeline.

$computers = @("SRV1", "SRV2", "SRV3")
$computers | Install-Software -Version 1

Without the process block, the function would only handle the last item. The process block allows the function to independently process each item in the array.

Binding by Property Name with ValueFromPipelineByPropertyName

Perhaps you have multiple properties in your pipeline objects that need to match the parameters of your function. If so, let’s assume a CSV file contains both the ComputerName and Version fields.

To demonstrate binding by property name, start by saving a CSV file containing these properties:

@(
    [pscustomobject]@{'ComputerName' = 'SRV1'; 'Version' = 1}
    [pscustomobject]@{'ComputerName' = 'SRV2'; 'Version' = 2}
    [pscustomobject]@{'ComputerName' = 'SRV3'; 'Version' = 2}
) | Export-Csv -Path C:\Scripts\software_installs.csv -NoTypeInformation

Update the function to accept Version and ComputerName by property name.

With ValueFromPipelineByPropertyName, the function matches properties in each object (such as those imported from a CSV) with parameters in the function.

function Install-Software {
    param(
        [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
        [ValidateSet(1,2)]
        [int]$Version,

        [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
        [string]$ComputerName
    )
    process {
        Write-Host "I installed software version $Version on $ComputerName. Yippee!"
    }
}

Now, use Import-Csv to import the file and pipe each object to Install-Software.

Import-Csv -Path C:\Scripts\software_installs.csv | Install-Software

Each row’s ComputerName and Version fields bind to the respective parameters in the function. This approach enables easy bulk processing of software installations across multiple computers with version control.

Conclusion

In this tutorial, you learned how to enable pipeline support in PowerShell functions, making them more versatile and powerful. You can now design custom functions that seamlessly accept data from the pipeline, similar to built-in cmdlets.

With pipeline-enabled functions, you gain finer control over data input, simplifying script design and improving readability.

As you continue working with PowerShell, consider integrating these techniques to write efficient, pipeline-ready functions. Make your scripts more adaptable and effective in automating tasks!