Everything you wanted to know about PSCustomObject - PowerShell (2024)

PSCustomObject is a great tool to add into your PowerShell tool belt. Let's start with the basicsand work our way into the more advanced features. The idea behind using a PSCustomObject is tohave a simple way to create structured data. Take a look at the first example and you'll have abetter idea of what that means.

Creating a PSCustomObject

I love using [PSCustomObject] in PowerShell. Creating a usable object has never been easier.Because of that, I'm going to skip over all the other ways you can create an object but I needto mention that most of these examples are PowerShell v3.0 and newer.

$myObject = [PSCustomObject]@{ Name = 'Kevin' Language = 'PowerShell' State = 'Texas'}

This method works well for me because I use hashtables for just about everything. But there aretimes when I would like PowerShell to treat hashtables more like an object. The first place younotice the difference is when you want to use Format-Table or Export-CSV and you realize that ahashtable is just a collection of key/value pairs.

You can then access and use the values like you would a normal object.

$myObject.Name

Converting a hashtable

While I am on the topic, did you know you could do this:

$myHashtable = @{ Name = 'Kevin' Language = 'PowerShell' State = 'Texas'}$myObject = [pscustomobject]$myHashtable

I do prefer to create the object from the start but there are times you have to work with ahashtable first. This example works because the constructor takes a hashtable for the objectproperties. One important note is that while this method works, it isn't an exact equivalent. Thebiggest difference is that the order of the properties isn't preserved.

If you want to preserve the order, seeOrdered hashtables.

Legacy approach

You may have seen people use New-Object to create custom objects.

$myHashtable = @{ Name = 'Kevin' Language = 'PowerShell' State = 'Texas'}$myObject = New-Object -TypeName PSObject -Property $myHashtable

This way is quite a bit slower but it may be your best option on early versions of PowerShell.

Saving to a file

I find the best way to save a hashtable to a file is to save it as JSON. You can import it back intoa [PSCustomObject]

$myObject | ConvertTo-Json -depth 1 | Set-Content -Path $Path$myObject = Get-Content -Path $Path | ConvertFrom-Json

I cover more ways to save objects to a file in my article onThe many ways to read and write to files.

Working with properties

Adding properties

You can still add new properties to your PSCustomObject with Add-Member.

$myObject | Add-Member -MemberType NoteProperty -Name 'ID' -Value 'KevinMarquette'$myObject.ID

Remove properties

You can also remove properties off of an object.

$myObject.psobject.properties.remove('ID')

The .psobject is an intrinsic member that gives you access to base object metadata. For moreinformation about intrinsic members, seeabout_Intrinsic_Members.

Enumerating property names

Sometimes you need a list of all the property names on an object.

$myObject | Get-Member -MemberType NoteProperty | Select -ExpandProperty Name

We can get this same list off of the psobject property too.

$myobject.psobject.properties.name

Dynamically accessing properties

I already mentioned that you can access property values directly.

$myObject.Name

You can use a string for the property name and it will still work.

$myObject.'Name'

We can take this one more step and use a variable for the property name.

$property = 'Name'$myObject.$property

I know that looks strange, but it works.

Convert PSCustomObject into a hashtable

To continue on from the last section, you can dynamically walk the properties and create a hashtablefrom them.

$hashtable = @{}foreach( $property in $myobject.psobject.properties.name ){ $hashtable[$property] = $myObject.$property}

Testing for properties

If you need to know if a property exists, you could just check for that property to have a value.

if( $null -ne $myObject.ID )

But if the value could be $null you can check to see if it exists by checking thepsobject.properties for it.

if( $myobject.psobject.properties.match('ID').Count )

Adding object methods

If you need to add a script method to an object, you can do it with Add-Member and aScriptBlock. You have to use the this automatic variable reference the current object. Here is ascriptblock to turn an object into a hashtable. (same code form the last example)

$ScriptBlock = { $hashtable = @{} foreach( $property in $this.psobject.properties.name ) { $hashtable[$property] = $this.$property } return $hashtable}

Then we add it to our object as a script property.

$memberParam = @{ MemberType = "ScriptMethod" InputObject = $myobject Name = "ToHashtable" Value = $scriptBlock}Add-Member @memberParam

Then we can call our function like this:

$myObject.ToHashtable()

Objects vs Value types

Objects and value types don't handle variable assignments the same way. If you assign value types toeach other, only the value get copied to the new variable.

$first = 1$second = $first$second = 2

In this case, $first is 1 and $second is 2.

Object variables hold a reference to the actual object. When you assign one object to a newvariable, they still reference the same object.

$third = [PSCustomObject]@{Key=3}$fourth = $third$fourth.Key = 4

Because $third and $fourth reference the same instance of an object, both $third.key and$fourth.Key are 4.

psobject.copy()

If you need a true copy of an object, you can clone it.

$third = [PSCustomObject]@{Key=3}$fourth = $third.psobject.copy()$fourth.Key = 4

Clone creates a shallow copy of the object. They have different instances now and $third.key is 3and $fourth.Key is 4 in this example.

I call this a shallow copy because if you have nested objects (objects with properties contain otherobjects), only the top-level values are copied. The child objects will reference each other.

PSTypeName for custom object types

Now that we have an object, there are a few more things we can do with it that may not be nearly asobvious. First thing we need to do is give it a PSTypeName. This is the most common way I seepeople do it:

$myObject.PSObject.TypeNames.Insert(0,"My.Object")

I recently discovered another way to do this from thispost by /u/markekraus. He talks about this approach that allows you todefine it inline.

$myObject = [PSCustomObject]@{ PSTypeName = 'My.Object' Name = 'Kevin' Language = 'PowerShell' State = 'Texas'}

I love how nicely this just fits into the language. Now that we have an object with a proper typename, we can do some more things.

Using DefaultPropertySet (the long way)

PowerShell decides for us what properties to display by default. A lot of the native commands have a.ps1xml formatting file that does all the heavy lifting. From thispost by Boe Prox, there's another way for us to do this on our custom objectusing just PowerShell. We can give it a MemberSet for it to use.

$defaultDisplaySet = 'Name','Language'$defaultDisplayPropertySet = New-Object System.Management.Automation.PSPropertySet('DefaultDisplayPropertySet',[string[]]$defaultDisplaySet)$PSStandardMembers = [System.Management.Automation.PSMemberInfo[]]@($defaultDisplayPropertySet)$MyObject | Add-Member MemberSet PSStandardMembers $PSStandardMembers

Now when my object just falls to the shell, it will only show those properties by default.

Update-TypeData with DefaultPropertySet

This is nice but I recently saw a better way using Update-TypeData to specifythe default properties.

$TypeData = @{ TypeName = 'My.Object' DefaultDisplayPropertySet = 'Name','Language'}Update-TypeData @TypeData

That is simple enough that I could almost remember it if I didn't have this post as a quickreference. Now I can easily create objects with lots of properties and still give it a nice cleanview when looking at it from the shell. If I need to access or see those other properties, they'restill there.

$myObject | Format-List *

Update-TypeData with ScriptProperty

Something else I got out of that video was creating script properties for your objects. Thiswould be a good time to point out that this works for existing objects too.

$TypeData = @{ TypeName = 'My.Object' MemberType = 'ScriptProperty' MemberName = 'UpperCaseName' Value = {$this.Name.toUpper()}}Update-TypeData @TypeData

You can do this before your object is created or after and it will still work. This is what makesthis different than using Add-Member with a script property. When you use Add-Member the way Ireferenced earlier, it only exists on that specific instance of the object. This one applies to allobjects with this TypeName.

Function parameters

You can now use these custom types for parameters in your functions and scripts. You can have onefunction create these custom objects and then pass them into other functions.

param( [PSTypeName('My.Object')]$Data )

PowerShell requires that the object is the type you specified. It throws a validation error ifthe type doesn't match automatically to save you the step of testing for it in your code. A greatexample of letting PowerShell do what it does best.

Function OutputType

You can also define an OutputType for your advanced functions.

function Get-MyObject{ [OutputType('My.Object')] [CmdletBinding()] param ( ...

The OutputType attribute value is only a documentation note. It isn't derived from the functioncode or compared to the actual function output.

The main reason you would use an output type is so that meta information about your functionreflects your intentions. Things like Get-Command and Get-Help that your development environmentcan take advantage of. If you want more information, then take a look at the help for it:about_Functions_OutputTypeAttribute.

With that said, if you're using Pester to unit test your functions then it would be a good ideato validate the output objects match your OutputType. This could catch variables that just fallto the pipe when they shouldn't.

Closing thoughts

The context of this was all about [PSCustomObject], but a lot of this information applies toobjects in general.

I have seen most of these features in passing before but never saw them presented as a collection ofinformation on PSCustomObject. Just this last week I stumbled upon another one and was surprisedthat I had not seen it before. I wanted to pull all these ideas together so you can hopefully seethe bigger picture and be aware of them when you have an opportunity to use them. I hope you learnedsomething and can find a way to work this into your scripts.