PowerShell Basics Level: Beginner Chapter 3: Think in Objects, Not Text
Custom objects
A custom object is an object you build yourself, with the properties you choose. It is the clean way to shape a result for a report or for the next step.
Lesson 6 of 7 in Chapter 3: Think in Objects, Not Text. Previous step in this path: Objects. 3 learning objectives, 6 examples, and a knowledge check.
Start: what you will learn
A custom object is an object you build yourself, with the properties you choose. It is the clean way to shape a result for a report or for the next step.
Learning objectives
- Build a custom object with PSCustomObject
- Explain when a custom object helps
- Read properties from a custom object
Concept in simple words
What it is: A custom object is an object you build yourself, with exactly the properties you choose, using [PSCustomObject] followed by a hash table, which is a set of name and value pairs inside @{ }. A hash table on its own is a lookup structure, where you look up a value by its key, while a custom object turns those pairs into properties, so you can read them with dot notation, display them as a table row, and pass them through the pipeline like any other object.
Why it works
Why it exists: Commands do not always return the shape you need for a report or for the next step. A custom object lets you combine a name from one place and a status from another into one clean row, and because it is a real object, the normal pipeline tools, such as sorting and filtering, still work on it. Without custom objects, you would be stuck with the column order and the property names the original command chose, even when a report needs different names or a different order.
Why it works this way: [PSCustomObject] tells PowerShell to build an object whose properties are the pairs you list, in the order you list them. That order matters, because PowerShell displays properties in that order, and a report reads better when the most important fact comes first. The values keep their types, so a number stays a number for sorting, a true or false value stays a true or false value for filtering, and a date stays a date for ordering by time.
Think of it like this
Think of it like this: A built in command gives you a ready made form, with its own boxes already printed on it. A custom object is a blank form where you write your own box labels, so the finished row shows exactly the facts you want, in the order you want them. The blank form still behaves like a form afterwards, so you can sort a pile of blank forms, filter them, and display them as a table.
How it works, step by step
How it works, step by step: First, write [PSCustomObject]@{, then list your properties as Name = value pairs, one per line, and close with }. The order you write the properties is the order they display, so put the most important fact first. Then store the object in a variable if you want to use it again, or pipe it straight on. You can separate pairs with new lines, or with semicolons on one line, but one pair per line reads most clearly while you are learning.
How it works, step by step, continued: Next, read a property back with dot notation, just like a built in object, for example $report.FreeGB. You can also collect several custom objects into a list, display them as a table, or export them, for example to a CSV file, which is a simple text file with comma separated values, using Export-Csv. When you export, use -NoTypeInformation with Export-Csv, so the file does not start with an extra type information line that can confuse a spreadsheet.
How to build a list of custom objects: One clean pattern is to collect the output of a foreach loop, such as $rows = foreach ($svc in Get-Service) { [PSCustomObject]@{ Name = $svc.Name; Status = $svc.Status } }. Each loop run builds one custom object, and PowerShell gathers every object from the loop into one list in $rows. This pattern avoids adding items one by one with +=, and it keeps the building step and the collecting step in one clear block.
How values from other objects work: A property value does not have to be text you type, it can come from another object, such as Service = $svc.Name, where $svc holds a service object and .Name reads its name. This is how you combine data, because the custom object takes a fact from one source and places it under a label you chose. If the source value changes later, the custom object does not update by itself, because it holds a copy of the value at build time, not a live link to the source.
How property names work, including spaces: Use simple property names with letters and no spaces when you can, such as ComputerName rather than Computer Name, because simple names work with plain dot notation. If you must use a space or a special character, put the name in quotes in the hash table, such as @{ "Computer Name" = "srv1" }, and then read it back with quotes around the name after the dot, such as $report."Computer Name". Quoted names work, but they are harder to type and easier to mistype, so prefer simple names.
How types affect later steps: Because values keep their types, a custom object with a numeric FreeGB property sorts numerically, so 9 sorts before 10, while a custom object with a text FreeGB property sorts as text, so "10" sorts before "9", because text sorting compares characters from left to right. The same rule applies to filtering, because -lt on numbers compares size, while -lt on text compares in text order. So store numbers without quotes when you mean numbers, and store true or false values as $true or $false when you mean yes or no flags.
How custom objects work in a pipeline: A custom object behaves like any other object afterwards. You can pipe a list of custom objects to Where-Object to keep only rows that pass a test, such as Where-Object { $_.FreeGB -lt 10 }, to Sort-Object to order them by a property, such as Sort-Object FreeGB -Descending, and to Select-Object to keep only some properties for a final report. This is why custom objects are so useful, because they do not need special tools, the tools you already know work on them unchanged.
How a custom object differs from Select-Object: Select-Object reshapes an existing object by keeping only named properties, and it works well when the original object already has the facts you need. A custom object is better when you need to rename properties, combine facts from two sources, add a calculated fact, or build a row from scratch with no source object at all. A good rule is to use Select-Object when reshaping is enough, and to build a custom object when reshaping cannot give you the shape you need.
How to add a property to an existing object: If you already hold an object and you want to add one property to it, without rebuilding it from scratch, PowerShell provides Add-Member, which adds a member to an object. For new rows, [PSCustomObject] is usually clearer, because the whole shape is visible in one block, but Add-Member is worth knowing as the tool for extending an object you did not create. Do not confuse the two, because Add-Member changes an existing object, while [PSCustomObject] builds a new one.
When to use it
When to use it, and when not to: Use a custom object when you are building a report, combining data from two sources, or preparing data for export. Do not build one when Select-Object already gives you the shape you need, because the simplest tool that gives the right shape is the right tool. Also do not build a custom object for a single value you will read once, because a plain variable is simpler and easier to read.
Common mistakes, in plain words: The most common mistake is using a plain hash table @{ } on its own and expecting it to display as a table row, when only [PSCustomObject] gives you that row shape. Another is using spaces or special characters in property names without quotes, which breaks the syntax or makes reading back harder. A third is storing numbers as text, and then wondering why sorting puts 10 before 9. A fourth is assuming a custom object updates when its source changes, when it holds a snapshot of values at build time. A fifth is forgetting a closing brace, so PowerShell waits for more input or reports an incomplete block.
How to spot a custom object problem: If your output shows keys and values in two columns instead of one row, you probably built a plain hash table rather than a custom object. If a property read gives you nothing, check the exact spelling, including quoted names with spaces. If sorting looks like text order instead of number order, check whether the values are in quotes. If a value looks stale, check whether you built the object before the source changed, and rebuild it after the change.
Worked examples
Read each example in order. Each one explains its parts, then shows what to look for in the output.
Syntax
[PSCustomObject]@{ Property = value }Example 1
Builds one object with three properties you chose. The order you write them is the order they display.
[PSCustomObject]@{
Computer = "srv1"
Service = "Spooler"
Status = "Running"
}Illustrative output: Computer Service Status -------- ------- ------ srv1 Spooler Running
Example 2
Reads one property back with dot notation, exactly like a built in object.
$report = [PSCustomObject]@{ Name = "srv1"; FreeGB = 42 }
$report.FreeGBIllustrative output: 42
Example 3
This builds one object with two properties you chose. Task holds the text Backup, and Done holds $true, which is the boolean value for true, meaning yes. Booleans hold only true or false, so Done is a clear yes or no flag, and you could read it back later with dot notation, such as $item.Done.
[PSCustomObject]@{
Task = "Backup"
Done = $true
}Illustrative output: Task Done ---- ---- Backup True
Example 4
The first block builds a list of two custom objects, wrapped in @() to make clear it is a list. Each object has the same two properties, Computer and Status, but different values. The last line pipes the list to Select-Object, which keeps both properties and displays the list as a table with two rows, one per object.
$servers = @(
[PSCustomObject]@{ Computer = "srv1"; Status = "Running" },
[PSCustomObject]@{ Computer = "srv2"; Status = "Stopped" }
)
$servers | Select-Object Computer, StatusIllustrative output: Computer Status -------- ------ srv1 Running srv2 Stopped
Example 5
The first line stores a real service object in $svc. The custom object then takes its values from that object, with Service reading $svc.Name and State reading $svc.Status, rather than text typed by hand. Change the service name in the first line, and the custom object values change with it, because they come from the source object at build time.
$svc = Get-Service -Name Spooler
[PSCustomObject]@{
Service = $svc.Name
State = $svc.Status
}Illustrative output: Service State ------- ----- Spooler Running
Example 6
The first line builds a custom object with a quoted property name, because the name contains a space. The second line reads that property back with quotes after the dot, because plain dot notation cannot handle a name with a space. The result is srv1, but prefer simple names without spaces when you can, because they are easier to type and to read.
$report = [PSCustomObject]@{ "Computer Name" = "srv1" }
$report."Computer Name"Illustrative output: srv1
Nothing on this page executes PowerShell code. The outputs above are illustrative only.
Common mistakes and troubleshooting
Read these before you try the examples, so you can spot the same problems in your own work.
- Using a plain hash table @{ } on its own and expecting it to display as a table row. Wrap it in [PSCustomObject].
- Using spaces or special characters in property names without quotes, which breaks the syntax.
- Using a plain hash table @{ } on its own and expecting it to display as a neat table row, when only [PSCustomObject] gives you that row shape.
- Storing numbers as text, such as FreeGB = "42", and then wondering why sorting puts "10" before "9", because text sorting compares characters, not size.
- Assuming a custom object updates when its source changes. A custom object holds a snapshot of values at build time, so rebuild it after the source changes.
- Forgetting a closing brace on the hash table, so PowerShell waits for more input or reports an incomplete block. Count your opening and closing braces before you run the block.
Knowledge check
Knowledge check
How do you build a custom object in PowerShell?
Pick one answer. Feedback appears right away, and you can try again.
Remember this and next step
Remember this: [PSCustomObject]@{ } builds an object with your own properties, in your own order, and it behaves like any other object afterwards, with dot notation for reading, Where-Object for filtering, Sort-Object for ordering, and Select-Object for reshaping, while a plain hash table on its own is a lookup structure, not a table row, numbers must stay unquoted to sort as numbers, and a custom object holds a snapshot of values at build time, not a live link to its source.
Next step: The Filter parameter