PowerShell Basics Level: Beginner Chapter 3: Think in Objects, Not Text

The pipeline and parameter binding

The pipe character sends objects from one command to the next. Parameter binding is how PowerShell decides which input goes to which parameter.

Lesson 3 of 7 in Chapter 3: Think in Objects, Not Text. Previous step in this path: Arrays. 3 learning objectives, 6 examples, and a knowledge check.

Start: what you will learn

The pipe character sends objects from one command to the next. Parameter binding is how PowerShell decides which input goes to which parameter.

Learning objectives

  • Explain what the pipeline passes between commands
  • Describe parameter binding in plain words
  • Predict where a filtered result comes from in a short pipeline

Concept in simple words

What it is: The pipeline is the pipe character, written as |, that sends objects from one command to the next, and parameter binding is how PowerShell decides which incoming object goes to which parameter of the next command. The pipe does not send text, and it does not send a screenshot of a table. It sends the real objects, with their properties and their types still attached.

Why it works

Why it exists: PowerShell commands return objects because objects keep facts separate and typed. A service object keeps its name separate from its status, and a number stays a number, so later commands can sort numbers numerically and filter by one named property, rather than guessing which column of text holds the fact they need. The pipeline is the delivery system that makes that possible.

Why text parsing fails and objects succeed: In a text based shell, you must cut up displayed text by column or by spaces, and that breaks as soon as a name gets longer, a column moves, or a value contains a space. Text sorting also fails in a quiet way, because text sorting puts 10 before 2, since it compares characters from left to right, while number sorting puts 2 before 10. With objects, you sort by the real numeric property, you filter by the real named property, and a longer name cannot shift the facts into the wrong column.

Think of it like this

Think of it like this: The pipeline is like a conveyor belt between two workers. The first worker puts labelled boxes on the belt, and the second worker picks each box up and checks the label to decide where it belongs. If a box has no label the second worker recognises, it cannot be placed, and the work stops or comes back empty. The labels here are the object type and the property names, and parameter binding is the second worker checking those labels.

How it works, step by step

How it works, step by step: First, run the command on the left of the pipe and look at what it returns. Check its properties, because those are the facts the next command will see. Then write the command on the right, and ask yourself what input it accepts, which you can check in its help. A pipe does not make two commands compatible by itself, the right hand command must have a parameter that accepts the kind of input you are sending.

How it works, step by step, continued: Next, add a shaping step, such as Where-Object to keep only objects that pass a test, or Select-Object to keep only some properties. Inside Where-Object, $_ means the current object on the belt, so $_.CPU means the CPU property of the object being checked right now. The same current object is also called $PSItem, so $_ and $PSItem mean the same thing inside a pipeline step.

How Where-Object works, in detail: Where-Object runs its test once per object, and the test must return true or false for that object. If the test returns true, the object survives and moves on. If the test returns false, the object is dropped and moves no further. The braces hold the test, and the comparison operators inside the test decide the rule, such as -eq for equals, -ne for not equals, -gt for greater than, -lt for less than, -ge for greater than or equal, -le for less than or equal, -like for a wildcard pattern with * and ?, and -match for a regular expression pattern. String comparisons are case insensitive by default, so "Running" -eq "running" returns true, unless you use a case sensitive form such as -ceq.

How Select-Object works, in detail: Select-Object decides which properties each surviving object keeps, and it returns new objects that hold only those properties. For example, Select-Object Name, Status returns objects with only Name and Status, and any property you did not name is gone from that point on. Select-Object can also decide which objects survive by position, with -First for the first few, -Last for the last few, -Skip to skip a number at the start, and -Unique to drop duplicates. Use -ExpandProperty when you want the value inside a property on its own, rather than an object that holds that property, such as a plain list of names instead of objects with a Name column.

How Sort-Object works, in detail: Sort-Object orders objects by a property, such as Sort-Object Name, and -Descending reverses the order. Sorting is different from filtering, because sorting must see the whole set before it can produce a complete sorted result, while Where-Object can pass each object on as soon as it passes the test. So a pipeline with Sort-Object waits at that step until all input has arrived, and then releases objects in sorted order.

How each pipeline step transforms objects: Think of a pipeline as a series of transformations, where each step receives objects, changes the set or the shape, and passes new objects on. Get-Service produces full service objects. Where-Object keeps a subset, but the objects keep their full shape. Select-Object then produces new, narrower objects with only the named properties. The next step can only see what the previous step passed on, so if you select only Name and then try to filter by Status, the filter finds nothing, because Status was already dropped.

How to check what a step passes on: When a pipeline gives you an empty result, stop and check each step in turn. Run the left part on its own, then add one step at a time, and use Get-Member after a step to see what properties are still present. This step by step check finds the step that dropped your property or filtered out every object, and it is faster than guessing at the whole line at once.

What parameter binding is, in simple words: Parameter binding is PowerShell matching each incoming object to a parameter of the next command. A parameter is a named input of a command, such as -Name, and binding is the act of placing a value into that parameter. PowerShell binds arguments you type on the command line first, and then it tries to bind pipeline input. If no parameter accepts the incoming object, the pipeline step cannot use that input, so check the help for that command before you blame the data.

How ByValue binding works: ByValue means by type. PowerShell looks at the type of the incoming object, and tries to place the whole object into a parameter that expects that type. For example, a service object piped into Get-Service binds ByValue to its InputObject parameter, because that parameter expects service objects. The whole object goes in, not only one property, so the receiving command gets the full object to work with.

How ByPropertyName binding works: ByPropertyName means by name. PowerShell looks at the property names on the incoming object, and tries to place a property value into a parameter with the same name. For example, a custom object with a Name property piped into Get-Service binds its Name value to the -Name parameter, because the property name matches the parameter name. The property name must match the parameter name or one of its aliases, and the property value must match or be convertible to the type the parameter expects.

In what order PowerShell tries binding: PowerShell tries ByValue first, and then ByPropertyName. In more detail, it first tries an exact type match ByValue, then an exact name match ByPropertyName, and then it tries again with type conversion, first ByValue with conversion, then ByPropertyName with conversion. You do not need to memorise this full order for everyday work, but it explains why a command sometimes binds in a way you did not expect, because an exact type match wins over a name match.

How to check binding for a command: Use Get-Help with the -Parameter option, such as Get-Help Get-Service -Parameter Name, and look for the line that says Accept pipeline input. That line tells you whether the parameter accepts pipeline input, and whether it accepts it ByValue, ByPropertyName, or both. Get-Member tells you what properties the incoming object has, so together these two checks tell you whether a ByValue or ByPropertyName match is even possible.

How to see binding in action: For a deeper look, PowerShell provides Trace-Command, which can trace parameter binding, such as Trace-Command -Name ParameterBinding -PSHost -Expression { Get-Service | Get-Service }. This is a diagnostic tool, not an everyday command, but it shows you, step by step, which parameter PowerShell tried and which one it chose. Use it when a pipeline binding puzzle resists the simpler Get-Help and Get-Member checks.

Why it works

Why filtering early helps, and when it does not: Filtering early, with Where-Object soon after the source command, reduces the number of objects later steps must handle, and it keeps the pipeline easy to read. Select-Object -First can also stop the upstream command early, once the requested number of objects has been produced, so it can save work. Sorting, by contrast, cannot save work in the same way, because it must see every object before it can order them.

Where formatting belongs: Formatting commands such as Format-Table are for display at the end of a pipeline, not for shaping data in the middle. Format-Table turns objects into formatting instructions for the screen, and later steps can no longer filter, sort, or export those formatting instructions as if they were the original data. So build your objects first, filter and select and sort them, and format them last, only when you want to look at them.

Common mistakes, in plain words: The most common mistake is assuming the pipeline passes text, and then trying to cut up displayed text by hand, when the object already has the property you need. Another is piping into a command that cannot accept that kind of input, and then blaming the second command before checking its help. A third is filtering by a property after Select-Object already dropped it. A fourth is placing Format-Table in the middle of a pipeline and then wondering why later steps see nothing useful. A fifth is using = instead of -eq inside a Where-Object test, so you store a value instead of testing it.

How to spot a pipeline problem: If a pipeline returns nothing, run it step by step from the left, and check each step with Get-Member. If a property seems missing, check whether an earlier Select-Object dropped it. If a step ignores your input, check its help for Accept pipeline input, and check whether your object type or property name matches. If later steps behave oddly after a table, check whether Format-Table appeared before them.

Worked examples

Read each example in order. Each one explains its parts, then shows what to look for in the output.

Syntax

Syntax
Get-Command | Where-Object { <condition> } | Select-Object <properties>

Example 1

$_ is the current object. This keeps only processes whose CPU property is greater than 10.

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

Illustrative output: Name CPU ---- --- pwsh 12.5

Example 2

Select-Object keeps only the named properties from each service object.

Example 2
Get-Service | Select-Object Name, Status

Illustrative output: Name Status ---- ------ Spooler Running

Example 3

Get-Service puts service objects on the pipeline, and Where-Object keeps only the ones whose Status property equals Running, where -eq means equals. Select-Object then keeps only the Name property, and -First 1 keeps only the first surviving object, so you see one running service name instead of a full table.

Example 3
Get-Service | Where-Object { $_.Status -eq "Running" } | Select-Object Name -First 1

Illustrative output: Name ---- Spooler

Example 4

This is ByPropertyName binding. The custom object has a Name property, and Get-Service has a -Name parameter that accepts pipeline input ByPropertyName, so PowerShell places the value Spooler into -Name, and Get-Service returns the matching service object. Change the Name value to another service name, and you get that service instead, because only the property value changed.

Example 4
[PSCustomObject]@{ Name = "Spooler" } | Get-Service

Illustrative output: Status Name ------ ---- Running Spooler

Example 5

This is ByValue binding. The first Get-Service returns a full service object, and the second Get-Service accepts service objects ByValue through its InputObject parameter, so the whole object is placed there, and the same service object comes back. This shows that ByValue passes the whole object, not only one property, even though the two commands look the same.

Example 5
Get-Service -Name Spooler | Get-Service

Illustrative output: Status Name ------ ---- Running Spooler

Example 6

The custom object holds a Tags property that is itself a list of two values, a and b. Select-Object without -ExpandProperty would return an object with a Tags column. With -ExpandProperty, PowerShell expands the property and returns the values a and b on their own, one per line, with no Tags column. Use this form when you want plain values, not objects that hold those values.

Example 6
[PSCustomObject]@{ Name = "srv1"; Tags = "a", "b" } | Select-Object -ExpandProperty Tags

Illustrative output: a b

Nothing on this page executes PowerShell code. The outputs above are illustrative only.

Diagram

Get-Processproduces objects|Where-Objectfilters objects|Select-Objectshows chosen propertiesObjects flow left to right. Text is only created at the end, for display.

Choose a stage above to see what it does.

Common mistakes and troubleshooting

Read these before you try the examples, so you can spot the same problems in your own work.

  • Assuming the pipeline passes text. It passes objects, and that is why properties survive.
  • Piping a command into another command that cannot accept its output type, then blaming the second command. Check Get-Help for its input types.
  • Assuming the pipeline passes text, and then trying to cut up the displayed text by hand, when the object already has the property you need.
  • Filtering by a property after Select-Object already dropped it, so the filter finds nothing and the result comes back empty.
  • Placing Format-Table in the middle of a pipeline, and then trying to filter, sort, or export the formatting output as if it were the original data.
  • Using = instead of -eq inside a Where-Object test, so you store a value instead of testing whether two values are equal.

Knowledge check

Knowledge check

What does the pipeline pass between commands?

Pick one answer. Feedback appears right away, and you can try again.

Remember this and next step

Remember this: The pipeline passes objects, not text, $_ is the current object, Where-Object keeps objects that pass a true or false test, Select-Object keeps only named properties or a chosen number of objects, Sort-Object needs the whole set before it can order, Format-Table belongs last for display only, and binding matches each object to a parameter ByValue first, by type, then ByPropertyName, by matching property name, and you can verify both sides with Get-Member and Get-Help.

Next step: Other command chaining