Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 34 ยท Objects and the Pipeline

The Pipeline

Understand the PowerShell pipeline: how the pipe passes objects one at a time, why it streams, which cmdlets block, and how ByValue and ByPropertyName binding work.

The pipeline is how PowerShell commands cooperate. The pipe character | takes whatever the command on its left produced and hands it to the command on its right. You build a result by chaining small commands, each doing one job: get things, filter them, sort them, act on them. Because the things passed along are objects, nothing needs to be parsed between stages.

This lesson explains what really happens inside a pipeline: objects move one at a time, so results can appear before the first command has finished; a few commands must wait for everything; and the receiving command decides how to bind each incoming object to a parameter. The PowerShell snippets are read-only. JavaScript generators in the stand-ins model the streaming so you can watch it happen.

The shape of a pipeline

POWERSHELL
Get-Service | Where-Object Status -eq Running | Sort-Object DisplayName | Select-Object -First 5

Read it left to right as a conveyor belt:

  1. Get-Service puts service objects on the belt.
  2. Where-Object lets through only those whose Status is Running.
  3. Sort-Object orders them by DisplayName.
  4. Select-Object -First 5 keeps the first five.

The last command's output goes to the screen through a hidden final stage, Out-Default, which formats the objects into the table you see. Formatting happens last, which is why Formatting and Output warns against putting Format-Table in the middle of a pipeline.

A pipeline is a conveyor belt

Produce A command emits objects.
Transform Filter, sort or reshape them.
Consume The last command acts or displays.

Each stage only needs to understand objects.

1 / 2

Objects flow one at a time

A pipeline does not run Get-Service to completion and then hand a finished list to the next command. Each object is passed on as soon as it exists. This is called streaming and it has two practical benefits: results show up early and memory use stays small, because the whole data set is never held at once.

POWERSHELL
Get-ChildItem -Path C:\ -Recurse -ErrorAction SilentlyContinue | Select-Object -First 5

This lists the first five items and stops. Select-Object -First tells the upstream commands to quit once it has enough, so PowerShell does not walk the entire drive. The same command written as a variable assignment first would walk everything:

POWERSHELL
$all = Get-ChildItem -Path C:\ -Recurse   # waits for the full list, uses lots of memory
$all | Select-Object -First 5

Remember this when working with large files or folders: prefer one pipeline over "collect everything, then filter".

Commands that must wait

A few commands cannot do their work until they have seen every object. Sort-Object is the classic example: you cannot know which item is first until all of them have arrived. It collects everything, sorts, then emits the results. Group-Object and Measure-Object also need the whole input, while Where-Object, ForEach-Object and Select-Object -First keep the stream moving.

That affects where to put filters. Put Where-Object before Sort-Object so you sort fewer items, and use a command's own filter parameter when it has one:

POWERSHELL
# Better: let Get-ChildItem filter at the source
Get-ChildItem -Filter *.log | Sort-Object Length

# Slower: collect everything, then filter, then sort
Get-ChildItem | Sort-Object Length | Where-Object Extension -eq .log

How binding works

When an object arrives at the next command, PowerShell must decide which parameter receives it. It tries two methods, in this order.

ByValue. The command has a parameter whose type matches the incoming object's type and which is marked as accepting pipeline input by value. Stop-Process has an -InputObject parameter that takes Process objects, so this works:

POWERSHELL
Get-Process -Name notepad | Stop-Process

ByPropertyName. If the object has a property whose name matches a parameter that accepts pipeline input by property name, that property's value is bound. So any object with a Name property can be piped to Stop-Service:

POWERSHELL
Import-Csv services.csv | Stop-Service     # the CSV has a column called Name

Each row of the CSV becomes an object with a Name property, and Stop-Service -Name takes it by property name.

You can see which parameters accept pipeline input in the help:

POWERSHELL
Get-Help Stop-Service -Full

Look for "Accept pipeline input?" under each parameter: True (ByValue), True (ByPropertyName) or both. When a pipeline does not behave as you expect, this is the first place to check. If a command does not accept pipeline input at all, use ForEach-Object (you will learn it in Grouping and Measuring) to take each object and call the command yourself.

Try it: watching objects stream

JavaScript generators produce values on demand, so they model a streaming pipeline nicely. Each stage below logs when it handles an object. Watch how the stages take turns, and how first(3) stops everything early.

JS Stand-in: a streaming pipeline with generators

Press Run (or Ctrl + Enter) to see the console output here.

No output.

You can see that every number goes all the way through the pipeline before the next one is produced. That is the real behaviour of PowerShell commands, which process objects individually. What is the stand-in: the logging and the generator mechanism; real cmdlets use their own begin, process and end stages, which you will write yourself in Advanced Functions.

Try it: a stage that has to wait

Now add a sort. Because sorting needs every item, the producer finishes completely before the first sorted value comes out.

JS Stand-in: why sorting blocks the stream

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The first consumer receives line only appears after all four produce lines. That is the reason a pipeline that ends in Sort-Object shows nothing for a while on a large input, while one without it starts printing straight away.

Binding by property name

The last stand-in imitates ByPropertyName binding: a function that declares which property it wants, and a source of objects that carry extra properties it ignores.

JS Stand-in: binding by property name

Press Run (or Ctrl + Enter) to see the console output here.

No output.

What is real: the binding rules, which are described in the PowerShell help and can be confirmed with Get-Help <command> -Full. What is the stand-in: real PowerShell also converts types, checks parameter sets and reports a detailed error; here a plain property check imitates the match.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does Get-ChildItem -Recurse | Select-Object -First 5 do to the folder walk?

    Streaming lets Select-Object -First stop the upstream command early, so the whole drive is not scanned.
  2. 2. Why does Sort-Object delay the first visible result?

    Sorting cannot know which item is first until it has seen all of them, so it collects its input before it emits anything.
  3. 3. Where do you check whether a parameter accepts pipeline input?

    The full help lists, per parameter, whether it accepts pipeline input by value, by property name, or both.
  4. 4. A CSV with a Name column is piped to Stop-Service. Which binding method is used?

    The rows are custom objects, not service objects, so the Name property of each row is bound to the -Name parameter by property name.
  5. 5. Where should a Where-Object filter usually go relative to Sort-Object?

    Filtering first reduces the amount of data that the blocking sort has to hold and order.

Summary

  • The pipe | passes objects from one command to the next; formatting for display happens last.
  • Objects stream one at a time, so results can appear early and Select-Object -First can stop work.
  • Sort-Object, Group-Object and Measure-Object must see all input first; filter before them.
  • Binding is ByValue (matching type) or ByPropertyName (matching property name); check Get-Help -Full.
  • The JavaScript generators on this page are stand-ins that model streaming; the cmdlets are real PowerShell.

Next: Where-Object, Select-Object and Sort-Object.