On this page

PowerShell Pipeline Input – Writing Pipeline-Aware Functions

Updated on June 11, 2026

Enrico Hochkoeppler Profile

By Enrico Hochkoeppler

Web Developer & TutoriaLibre Founder

Making a function accept pipeline input means it can receive objects from the pipeline exactly the way built-in cmdlets like Get-Service, Stop-Process, and Where-Object do. The mechanism is the [Parameter()] attribute with ValueFromPipeline or ValueFromPipelineByPropertyName, combined with a process block that runs once per piped object. Without the process block, only the last piped object is processed — a silent bug that is one of the most common mistakes when writing pipeline-enabled functions.

This lesson covers both binding modes in full, the streaming behaviour of the pipeline, how PowerShell resolves type mismatches, how to check pipeline support on existing cmdlets, and how to investigate binding failures.


How the PowerShell Pipeline Works​

A pipeline connects commands with the | operator. The left side produces objects; the right side receives them. The critical characteristic of the PowerShell pipeline — the one that makes it fundamentally different from pipelines in Bash or cmd.exe — is that it passes .NET objects, not text, and it does so one object at a time in a streaming fashion.


Get-Service | Where-Object Status -eq Running | Sort-Object DisplayName

Get-Service emits ServiceController objects one at a time as it generates them. Where-Object receives each one, evaluates the condition, and passes matching objects to Sort-Object. At no point is the entire collection assembled in memory before processing starts. The pipeline streams.

This streaming behaviour has two important practical consequences. First, output appears progressively — a pipeline processing one million objects starts displaying results immediately, not after all objects are generated. Second, memory usage is bounded — the pipeline never needs to hold the entire collection in memory at once.

What the pipeline enumerates automatically​

PowerShell automatically enumerates any type that implements the IEnumerable interface when it is piped. Arrays are enumerated — their elements are sent one at a time:


@(1, 2, 3) | Measure-Object

# Count: 3  — three separate objects were received

Hashtables are not automatically enumerated — the entire hashtable is sent as a single object:


@{ One = 1; Two = 2 } | Measure-Object

# Count: 1  — one hashtable object was received

Strings implement IEnumerable over their characters, but PowerShell deliberately does not enumerate them — a string is sent as a single object, not as a stream of characters.

To enumerate a hashtable manually, call .GetEnumerator():


@{ Server = "prod-01"; Port = 443 }.GetEnumerator() | ForEach-Object {

    "$($_.Key) = $($_.Value)"

}

How to Check Whether a Parameter Accepts Pipeline Input​

Before writing a function that pipes to an existing cmdlet, verify which parameters accept pipeline input and in which mode. Use Get-Help -Full or Get-Help -Parameter *:


Get-Help Start-Service -Parameter *

Look for the Accept pipeline input? field in the parameter descriptions. The value tells you the binding mode:


-Name <String[]>

    Accept pipeline input?  True (ByPropertyName, ByValue)



-InputObject <ServiceController[]>

    Accept pipeline input?  True (ByValue)

ByValue means the parameter uses ValueFromPipeline. ByPropertyName means it uses ValueFromPipelineByPropertyName. A parameter that shows both accepts input by either mechanism.

You can also inspect parameters programmatically:


(Get-Command Start-Service).Parameters.Values |

    Where-Object { $_.Attributes.ValueFromPipeline -or $_.Attributes.ValueFromPipelineByPropertyName } |

    Select-Object Name,

        @{ n="ByValue";        e={ ($_.Attributes | Where-Object ValueFromPipeline).ValueFromPipeline } },

        @{ n="ByPropertyName"; e={ ($_.Attributes | Where-Object ValueFromPipelineByPropertyName).ValueFromPipelineByPropertyName } }

This shows every pipeline-accepting parameter on Start-Service alongside which binding mode each uses.


ValueFromPipeline — Binding the Entire Piped Object​

ValueFromPipeline binds the entire pipeline object to the parameter when the object's type matches the parameter's declared type (or can be converted to it).


function Show-Item {

    [CmdletBinding()]

    param(

        [Parameter(ValueFromPipeline)]

        [string]$Item

    )

    process {

        "Item: $Item"

    }

}



"apple", "banana", "cherry" | Show-Item

The three strings are piped to Show-Item. Because $Item is typed as [string] and has ValueFromPipeline, PowerShell binds each string to $Item in turn. The process block runs once per object. Output:


Item: apple

Item: banana

Item: cherry

Why the process block is mandatory​

Without a process block, the function body runs only once, after all pipeline input has been consumed, and $Item holds only the last piped value:


function Show-Item-Wrong {

    param(

        [Parameter(ValueFromPipeline)]

        [string]$Item

    )

    "Item: $Item"   # NO process block — runs once at the end

}



"apple", "banana", "cherry" | Show-Item-Wrong

# Output: Item: cherry  — only the last value!

This is the most common pipeline bug in PowerShell functions. The process block is what tells PowerShell to execute the function body for every piped object:

BlockWhen it runsRequired for per-object processing?beginOnce before any pipeline inputNoprocessOnce per piped objectYesendOnce after all pipeline inputNo


ValueFromPipelineByPropertyName — Binding by Property Name​

ValueFromPipelineByPropertyName reads a named property from each piped object and binds its value to the parameter. The property name must match the parameter name (or one of its aliases).


function Show-Name {

    [CmdletBinding()]

    param(

        [Parameter(ValueFromPipelineByPropertyName)]

        [string]$Name

    )

    process {

        "Name: $Name"

    }

}



$objects = @(

    [PSCustomObject]@{ Name = "Alice"; Age = 30 }

    [PSCustomObject]@{ Name = "Bob";   Age = 25 }

)



$objects | Show-Name

Each custom object has a Name property. Because $Name has ValueFromPipelineByPropertyName, PowerShell reads the Name property from each piped object and binds it to $Name. The Age property is ignored. Output:


Name: Alice

Name: Bob

Binding to aliases​

ValueFromPipelineByPropertyName also matches property names against parameter aliases. If $ComputerName has [Alias("CN")] and a piped object has a CN property, the binding succeeds:


function Test-AliasBind {

    [CmdletBinding()]

    param(

        [Parameter(ValueFromPipelineByPropertyName)]

        [Alias("CN", "MachineName")]

        [string]$ComputerName

    )

    process { "Computer: $ComputerName" }

}



[PSCustomObject]@{ CN = "Server01" } | Test-AliasBind

# Output: Computer: Server01

What happens when the property does not exist​

When the piped object has no property matching the parameter name or any of its aliases, the parameter receives $null and the function still runs. This is a silent failure — no error is thrown:


"hello" | Show-Name

# Output: Name:   (empty — string has no .Name property)

When $null input is a problem, add [ValidateNotNullOrEmpty()] to the parameter. This raises a validation error when the bound value is null or empty, making the failure explicit.


Using Both Binding Modes on the Same Parameter​

A parameter can accept both the entire piped object and a named property from a piped object simultaneously:


function Get-ObjectInfo {

    [CmdletBinding()]

    param(

        [Parameter(ValueFromPipeline, ValueFromPipelineByPropertyName)]

        [string]$Name

    )

    process { "Received: $Name" }

}



# ByValue — piping strings directly

"Server01", "Server02" | Get-ObjectInfo



# ByPropertyName — piping objects with a Name property

Get-Service "bits", "wuauserv" | Get-ObjectInfo

The first pipeline pipes strings directly. Because $Name is [string] and ValueFromPipeline is active, each string binds by value. The second pipeline pipes ServiceController objects. Because they have a Name property and ValueFromPipelineByPropertyName is active, the Name property value binds.


Multiple Pipeline Parameters — Binding Order​

A function can have multiple pipeline-accepting parameters. When a piped object arrives, PowerShell resolves binding in a specific order (per the official binding process):

  1. ValueFromPipeline exact type match
  2. ValueFromPipelineByPropertyName exact type match
  3. ValueFromPipeline with type conversion
  4. ValueFromPipelineByPropertyName with type conversion

This means that if both a ValueFromPipeline and a ValueFromPipelineByPropertyName parameter could bind to the same piped object, the ValueFromPipeline parameter wins for the whole-object binding. The ValueFromPipelineByPropertyName parameter can still bind from a named property simultaneously:


function Test-BothModes {

    [CmdletBinding()]

    param(

        [Parameter(ValueFromPipeline)]

        $Value,



        [Parameter(ValueFromPipelineByPropertyName)]

        $Name

    )

    process {

        "Value: $Value | Name: $Name"

    }

}



[PSCustomObject]@{ Name = "Alice"; Value = 10 } | Test-BothModes

# Output: Value: 10 | Name: Alice

$Value receives 10 via ValueFromPipeline (type conversion — PSCustomObject can bind to an untyped parameter). $Name receives "Alice" via ValueFromPipelineByPropertyName simultaneously.


The begin, process, and end Blocks in Full​

These three blocks give complete control over the pipeline processing lifecycle. They can contain any code and work together to implement correct streaming behaviour:


function Measure-PipelineItems {

    [CmdletBinding()]

    param(

        [Parameter(ValueFromPipeline)]

        [object]$InputObject

    )



    begin {

        $count = 0

        $sum   = 0

        Write-Verbose "Beginning pipeline processing"

    }



    process {

        $count++

        if ($InputObject -is [int] -or $InputObject -is [double]) {

            $sum += $InputObject

        }

        Write-Verbose "Processed item $count : $InputObject"

    }



    end {

        [PSCustomObject]@{

            Count   = $count

            Sum     = $sum

            Average = if ($count -gt 0) { [math]::Round($sum / $count, 2) } else { 0 }

        }

    }

}



1, 2, 3, 4, 5 | Measure-PipelineItems -Verbose

begin initialises $count and $sum once before any objects arrive. process increments the counter and accumulates the sum for each piped integer. end produces the final aggregated result as a single output object after all input is consumed. The -Verbose flag activates the Write-Verbose messages in process. Output (non-verbose portion):


Count   Sum Average

-----   --- -------

    5    15       3

Type Conversion During Pipeline Binding​

When the piped object's type does not exactly match the parameter's declared type, PowerShell attempts a type conversion. This is transparent when it succeeds:


function Process-Id {

    [CmdletBinding()]

    param(

        [Parameter(ValueFromPipeline)]

        [int]$Id

    )

    process { "Processing ID: $Id" }

}



"42", "100", "7" | Process-Id

# Output: Processing ID: 42, Processing ID: 100, Processing ID: 7

The strings "42", "100", and "7" are each converted to [int] during binding. If conversion fails — piping "hello" to a [int] parameter — PowerShell raises a ParameterBindingException and that specific object is skipped (with an error written to the error stream), unless -ErrorAction Stop is in effect.

Typed array parameters ([string[]] vs [string])​

A parameter typed as [string[]] can receive both a single string and an array. When typed as [string], it can only receive a single string:


function Show-Names {

    [CmdletBinding()]

    param(

        [Parameter(ValueFromPipeline)]

        [string[]]$Names

    )

    process {

        foreach ($n in $Names) { "Name: $n" }

    }

}



# Single value piped

"Alice" | Show-Names



# Array piped (not enumerated — sent as one array object)

$list = @("Alice", "Bob", "Charlie")

$list | Show-Names      # sends three separate strings — process runs 3 times

, $list | Show-Names    # the comma operator prevents enumeration — process runs 1 time with an array

The unary comma operator , wraps a value in a single-element array, which PowerShell does not further enumerate. This is the mechanism for sending an entire array as one pipeline object rather than as individual elements.


Processing Null Pipeline Input​

When a pipeline produces $null, the function receives it. Without a guard, this can produce confusing output or errors:


function Show-Server {

    [CmdletBinding()]

    param(

        [Parameter(ValueFromPipeline)]

        [string]$ComputerName

    )

    process {

        if ([string]::IsNullOrEmpty($ComputerName)) {

            Write-Warning "Received empty input — skipping"

            return

        }

        "Processing: $ComputerName"

    }

}



$null | Show-Server

# Output: WARNING: Received empty input — skipping

Alternatively, add [ValidateNotNullOrEmpty()] to the parameter declaration to reject null and empty values at the binding stage, before process runs:


param(

    [Parameter(ValueFromPipeline)]

    [ValidateNotNullOrEmpty()]

    [string]$ComputerName

)

The $input Automatic Variable​

In a basic function (one without begin/process/end blocks), the $input automatic variable represents all pipeline input as an enumerable collection:


function Show-All {

    param()

    foreach ($item in $input) {

        "Item: $item"

    }

}



"one", "two", "three" | Show-All

$input is a forward-only enumerator. Once consumed, it cannot be rewound. In advanced functions with [CmdletBinding()] and process blocks, $input is empty — use the parameter variable instead. Reserve $input for simple functions that process the entire input collection at once.


Native Commands in the Pipeline (PowerShell 7.4+)​

Before PowerShell 7.4, piping the output of a native command (like curl or tar) that produced raw binary data converted the bytes to .NET strings, corrupting binary content. Starting with PowerShell 7.4, the PSNativeCommandPreserveBytePipe feature is mainstream and preserves byte-stream data when piping native command output to files or to other native commands:


# PowerShell 7.4+: binary data preserved correctly

curl.exe https://example.com/archive.zip | Out-File archive.zip -AsByteStream

When working with native commands in pipelines on earlier PowerShell versions, redirect binary output to a file using native shell mechanisms rather than PowerShell's pipeline to avoid corruption.


Investigating Pipeline Binding Errors​

When a pipeline command fails with a binding error, Trace-Command reveals exactly what PowerShell attempted:


Trace-Command -PSHost -Name ParameterBinding -Expression {

    Get-Service "bits", "wuauserv" | My-CustomFunction

}

-PSHost sends trace output to the console. -Name ParameterBinding filters to only parameter binding trace events. The output shows every candidate parameter, every type match attempt, every conversion attempted, and the final binding decision or failure reason.

When a pipeline silently receives $null where a value was expected, check:


# Check what a command actually emits

Get-Service "bits" | Get-Member | Select-Object -First 1 TypeName

# TypeName: System.ServiceProcess.ServiceController



# Check whether the parameter type accepts that type

Get-Help My-CustomFunction -Parameter InputObject

# Shows Accept pipeline input?: True (ByValue) or False

Practical Pattern: Process One, Many, or No Objects​

A robust pipeline-aware function handles all three input scenarios:


function Invoke-ServerCheck {

    [CmdletBinding()]

    param(

        [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]

        [ValidateNotNullOrEmpty()]

        [string[]]$ComputerName

    )



    begin {

        $results = [System.Collections.Generic.List[PSCustomObject]]::new()

    }



    process {

        foreach ($computer in $ComputerName) {

            Write-Verbose "Checking: $computer"

            $online = Test-Connection -ComputerName $computer -Count 1 -Quiet

            $results.Add([PSCustomObject]@{

                ComputerName = $computer

                Online       = $online

                CheckedAt    = Get-Date

            })

        }

    }



    end {

        $results

    }

}



# Direct call

Invoke-ServerCheck -ComputerName "Server01", "Server02"



# Pipeline from array

"Server01", "Server02" | Invoke-ServerCheck



# Pipeline from objects with ComputerName property

Get-ADComputer -Filter * | Select-Object -First 10 | Invoke-ServerCheck -Verbose

The foreach loop inside process handles the case where a single process invocation receives an array ([string[]]). The begin block initialises the results list once. The end block emits all results at the end of the pipeline as a single batch, allowing callers to sort or filter the complete result set.


Common Mistakes to Avoid​

Omitting the process block. Without it, only the last piped object is bound to the parameter and the function body runs once. Always include a process block when accepting pipeline input.

Not typing the parameter. An untyped parameter ($Item with no type) accepts any value by value, which works but prevents ValueFromPipelineByPropertyName from matching correctly in some edge cases. Type parameters to make binding explicit and predictable.

Calling the function inside a loop instead of accepting pipeline input. Looping to call a function repeatedly defeats the purpose of pipeline support. Write the function to accept ValueFromPipeline and let the pipeline do the iteration.

Assuming piped strings have a .Name property. Plain strings have no Name property. ValueFromPipelineByPropertyName on a $Name parameter receives $null when strings are piped. Use ValueFromPipeline for direct value binding when the input is a scalar type.

Not checking what the upstream command actually emits. A common debugging mistake is assuming a cmdlet returns what you expect. Always run Get-Member on the upstream command's output before writing the downstream function.

Found this helpful? Share the knowledge...

... or support this project to keep it alive!

Buy Me a Coffee

Previous

Mandatory Parameters

Next

Returning Objects Properly