Custom objects (PSCustomObject) in PowerShell - Deep Dive

Overview - Custom objects (PSCustomObject)

What is it?

Custom objects in PowerShell, created using PSCustomObject, let you build your own structured data with named properties. They are like containers where you can store related information together in a clear way. This helps organize data so scripts can handle complex information easily. You create them by defining property names and values, making your data easy to read and use.

Why it matters

Without custom objects, scripts would handle data as plain text or unstructured lists, making it hard to find or use specific pieces of information. Custom objects solve this by grouping related data with clear labels, like a mini database record. This makes scripts more powerful, easier to understand, and simpler to maintain. It also helps when sharing data between commands or exporting it.

Where it fits

Before learning custom objects, you should understand basic PowerShell variables, arrays, and hashtables. After mastering custom objects, you can explore advanced data manipulation, object-oriented scripting, and working with JSON or XML data formats.

Mental Model

Core Idea

A PSCustomObject is a labeled container that groups related pieces of data into one easy-to-use package.

Think of it like...

Imagine a custom object as a labeled box where each label is a property name and inside the box is the value. Instead of juggling loose items, you keep everything organized in one box with clear tags.

┌─────────────────────────────┐
│       PSCustomObject        │
├─────────────┬───────────────┤
│ Property 1  │ Value 1       │
├─────────────┼───────────────┤
│ Property 2  │ Value 2       │
├─────────────┼───────────────┤
│ Property 3  │ Value 3       │
└─────────────┴───────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding basic hashtables

Concept: Learn how to store key-value pairs using hashtables, the foundation for custom objects.

In PowerShell, a hashtable stores data as keys and values. For example: $person = @{Name = 'Alice'; Age = 30} This creates a simple collection where 'Name' and 'Age' are keys, and 'Alice' and 30 are their values.

Result

You get a hashtable with keys and values you can access by name, like $person['Name'] returns 'Alice'.

Knowing hashtables is essential because PSCustomObject builds on this idea but adds more structure and usability.

2

Foundation

Creating a simple PSCustomObject

Concept: Learn how to create a custom object using [PSCustomObject] with properties and values.

You can create a custom object by casting a hashtable: $person = [PSCustomObject]@{Name = 'Alice'; Age = 30} This makes $person an object with properties Name and Age accessible as $person.Name and $person.Age.

Result

You get an object where properties are easy to access and display, unlike plain hashtables.

Casting to PSCustomObject turns a hashtable into a real object, making data handling more natural in PowerShell.

3

Intermediate

Adding properties dynamically

🤔Before reading on: do you think you can add new properties to a PSCustomObject after creation? Commit to yes or no.

Concept: Explore how to add new properties to an existing PSCustomObject using Add-Member.

You can add properties after creating the object: $person = [PSCustomObject]@{Name='Alice'; Age=30} $person | Add-Member -MemberType NoteProperty -Name 'City' -Value 'Seattle' Now $person.City returns 'Seattle'.

Result

The object now has a new property 'City' accessible like the original ones.

Understanding dynamic property addition shows how flexible PSCustomObjects are for evolving data needs.

4

Intermediate

Using PSCustomObject in pipelines

🤔Before reading on: do you think PSCustomObjects can be passed through pipelines and keep their structure? Commit to yes or no.

Concept: Learn how PSCustomObjects flow through pipelines, preserving property names and values for further processing.

When you output a PSCustomObject in a pipeline, its properties remain intact: Get-Process | Select-Object -First 1 | ForEach-Object { [PSCustomObject]@{Name=$_.ProcessName; ID=$_.Id} } This creates custom objects from process info that can be filtered or formatted downstream.

Result

You get structured objects flowing through the pipeline, enabling powerful data manipulation.

Knowing that PSCustomObjects keep their structure in pipelines unlocks advanced scripting and data transformation.

5

Advanced

Custom objects with methods and script properties

🤔Before reading on: can PSCustomObjects have methods like classes? Commit to yes or no.

Concept: Discover how to add script properties or methods to PSCustomObjects for behavior, not just data.

You can add script properties or methods: $person = [PSCustomObject]@{Name='Alice'; Age=30} $person | Add-Member -MemberType ScriptMethod -Name 'Greet' -Value { "Hello, my name is $($this.Name)" } Calling $person.Greet() returns 'Hello, my name is Alice'.

Result

The object now behaves like it has a method, adding dynamic behavior.

Understanding this blurs the line between simple data containers and objects with behavior, enhancing script design.

6

Expert

Performance and memory considerations

🤔Before reading on: do you think creating thousands of PSCustomObjects is always efficient? Commit to yes or no.

Concept: Learn about the performance impact of PSCustomObjects and when to optimize or choose alternatives.

Creating many PSCustomObjects can slow scripts and use more memory. For large data, consider using classes or structured data formats. Also, avoid unnecessary Add-Member calls inside loops; instead, create objects fully formed.

Result

Scripts run faster and use less memory when optimized object creation is applied.

Knowing performance trade-offs helps write scalable scripts and avoid subtle slowdowns in automation.

Under the Hood

PSCustomObject is a special type in PowerShell that wraps a hashtable into a .NET object with properties. When you cast a hashtable to [PSCustomObject], PowerShell creates an object with properties matching the hashtable keys. This object supports property access, pipeline output formatting, and can be extended with methods or script properties. Internally, it uses .NET's PSObject to provide dynamic property handling and integration with PowerShell's type system.

Why designed this way?

PowerShell needed a simple way to create structured data without full class definitions. PSCustomObject was designed to be lightweight and flexible, allowing quick creation of objects with named properties. This approach avoids the complexity of defining classes for simple data grouping, making scripting faster and more accessible. Alternatives like classes are more rigid and verbose, so PSCustomObject fills the gap for everyday scripting needs.

Hashtable (key-value pairs)
      │
      ▼
[PSCustomObject] cast
      │
      ▼
┌─────────────────────────────┐
│       PSCustomObject         │
│ ┌─────────────┐ ┌─────────┐ │
│ │ Property 1  │ │ Value 1 │ │
│ ├─────────────┤ ├─────────┤ │
│ │ Property 2  │ │ Value 2 │ │
│ └─────────────┘ └─────────┘ │
└─────────────────────────────┘
      │
      ▼
PowerShell pipeline and formatting system

Myth Busters - 4 Common Misconceptions

Quick: Does casting a hashtable to PSCustomObject make it immutable? Commit to yes or no.

Common Belief: Once you create a PSCustomObject, its properties cannot be changed or added.

Reality: PSCustomObjects are mutable; you can add, remove, or change properties after creation using Add-Member or direct assignment.

Why it matters: Believing objects are immutable can stop you from dynamically updating data, limiting script flexibility and causing unnecessary object recreation.

Quick: Are PSCustomObjects the same as full PowerShell classes? Commit to yes or no.

Common Belief: PSCustomObjects are just like classes and support all class features.

Reality: PSCustomObjects are simple data containers without full class features like inheritance or strong typing.

Why it matters: Confusing them leads to expecting behaviors like methods or inheritance that PSCustomObjects don't support, causing frustration and bugs.

Quick: Does using Add-Member inside a loop always improve performance? Commit to yes or no.

Common Belief: Adding members dynamically inside loops is efficient and recommended.

Reality: Adding members repeatedly inside loops slows down scripts; it's better to create fully formed objects upfront.

Why it matters: Misusing Add-Member in loops can cause slow scripts and high memory use, hurting automation reliability.

Quick: Can PSCustomObjects be used interchangeably with JSON objects? Commit to yes or no.

Common Belief: PSCustomObjects and JSON objects are the same and interchangeable without conversion.

Reality: PSCustomObjects are PowerShell objects; JSON is a text format. You must convert between them explicitly.

Why it matters: Assuming interchangeability causes errors when exporting or importing data, breaking automation workflows.

Expert Zone

1

PSCustomObjects support extended type data allowing you to customize how properties display or behave without changing the object itself.

2

When outputting PSCustomObjects, PowerShell uses formatting files to decide how properties appear, which can be customized for better readability.

3

PSCustomObjects can be used as lightweight DTOs (Data Transfer Objects) in scripts, bridging between APIs and internal logic without full class overhead.

When NOT to use

Avoid PSCustomObjects when you need strict type enforcement, inheritance, or complex methods; use PowerShell classes instead. For very large datasets or performance-critical scripts, consider using .NET objects or structured data formats like CSV or databases.

Production Patterns

In real-world scripts, PSCustomObjects are used to collect and format data from multiple sources before exporting to CSV or JSON. They are also common in custom cmdlets to return structured results and in pipeline processing to pass rich data between commands.

Connections

JSON data format

PSCustomObjects can be converted to and from JSON, bridging PowerShell objects and text data interchange.

Understanding PSCustomObjects helps grasp how structured data is represented in JSON, enabling smooth data exchange with web APIs.

Object-oriented programming (OOP)

PSCustomObjects are simple objects without full OOP features but share the idea of bundling data with properties.

Knowing PSCustomObjects lays a foundation for learning full OOP concepts like classes and inheritance in PowerShell.

Database records

A PSCustomObject is like a single database record with named fields representing columns.

This connection helps understand how scripts can mimic database-like data handling using objects.

Common Pitfalls

#1 Trying to access a property that doesn't exist causes errors.

Wrong approach:

$person = [PSCustomObject]@{Name='Alice'}
Write-Output $person.Age

Correct approach:

$person = [PSCustomObject]@{Name='Alice'; Age=30}
Write-Output $person.Age

Root cause:

The property 'Age' was never defined, so accessing it returns nothing or errors; forgetting to define all needed properties causes this.

#2 Using Add-Member inside a loop to add properties repeatedly slows down the script.

Wrong approach:

foreach ($i in 1..1000) {
$obj = [PSCustomObject]@{Index=$i}
$obj | Add-Member -MemberType NoteProperty -Name 'Time' -Value (Get-Date)
}

Correct approach:

foreach ($i in 1..1000) {
$obj = [PSCustomObject]@{Index=$i; Time=(Get-Date)}
}

Root cause:

Add-Member is slower than creating objects with all properties at once; using it inside loops causes performance issues.

#3 Assuming PSCustomObjects are immutable and trying to reassign properties incorrectly.

Wrong approach:

$person = [PSCustomObject]@{Name='Alice'; Age=30}
$person.Age += 1 # expecting to update Age

Correct approach:

$person = [PSCustomObject]@{Name='Alice'; Age=30}
$person.Age = $person.Age + 1

Root cause:

PSCustomObject properties can be changed, but you must assign new values explicitly; misunderstanding this leads to unexpected behavior.

Key Takeaways

PSCustomObjects let you create clear, labeled containers for related data in PowerShell scripts.

They are built by casting hashtables and can be extended dynamically with new properties or methods.

PSCustomObjects flow through pipelines preserving structure, enabling powerful data manipulation.

Understanding their performance characteristics helps write efficient and scalable scripts.

They bridge simple scripting and more advanced object-oriented programming concepts.