- Courses
- 💻Programming Languages
- 🪟PowerShell
- Scripting Fundamentals
- Functions and Modular Code
- Pipeline Input
On this page
PowerShell Pipeline Input – Writing Pipeline-Aware Functions
Updated on June 11, 2026
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):
ValueFromPipelineexact type matchValueFromPipelineByPropertyNameexact type matchValueFromPipelinewith type conversionValueFromPipelineByPropertyNamewith 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:
- Whether the upstream command actually produced output (
Get-Service "nonexistent"returns nothing, not null) - Whether the property name matches exactly (PowerShell is case-insensitive but must match the name or a declared alias)
- Whether the upstream type is compatible with the parameter type
# 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!
Previous
Mandatory Parameters
Next
Returning Objects Properly
-
How the PowerShell Pipeline Works
- What the pipeline enumerates automatically
-
How to Check Whether a Parameter Accepts Pipeline Input
-
ValueFromPipeline— Binding the Entire Piped Object- Why the
processblock is mandatory
- Why the
-
ValueFromPipelineByPropertyName— Binding by Property Name- Binding to aliases
- What happens when the property does not exist
-
Using Both Binding Modes on the Same Parameter
-
Multiple Pipeline Parameters — Binding Order
-
The
begin,process, andendBlocks in Full -
Type Conversion During Pipeline Binding
- Typed array parameters (
[string[]]vs[string])
- Typed array parameters (
-
Processing Null Pipeline Input
-
The
$inputAutomatic Variable -
Native Commands in the Pipeline (PowerShell 7.4+)
-
Investigating Pipeline Binding Errors
-
Practical Pattern: Process One, Many, or No Objects
-
Common Mistakes to Avoid
