Getting Started with PSCustomObject in PowerShell

It has always been very easy to create hashtables and arrays in PowerShell, but there are times that a generic object comes in handy. Both hashtables and arrays are collections of objects, but a PSCustomObject is constructed of properties and values. PSCustomObject’s can be stored in arrays and hashtables, but ultimately they are intended to be a collection of properties.

When you need to store data in a structured format that can be extended upon, or in a more ordered fashion, PSCustomObject works great!

Creating a PSCustomObject in PowerShell

The fastest and easiest way to create a PSCustomObject is to use the following method, which works in all versions of PowerShell 3.0 and above.

You can also use the New-Object -TypeName PSObject -Property @{} which will work in earlier versions of PowerShell, but it is also slower. This speed comes into play when you need to create or manipulate many objects in a script.

You will notice that there appears to be a hashtable appended to the type declaration, [PSCustomObject], this is because we are passing the properties and values as key-values, best suited for a hashtable. The other benefit to this approach is that the PSCustomObject properties are ordered, unlike in a traditional hashtable where the keys will not maintain their initial order. Each of the created properties will be a NoteProperty like a typical PowerShell object.

Of course, we have created an empty PSCustomObject, which doesn’t do much good. How do we add properties? In the old days, we would use Add-Member to add properties to an existing object. There is an easier way, on initial object creation.

Great! We have properties now, but often in a script, you may need to add an additional property. This is where Add-Member is still handy. You can use this with PSCustomObject as seen below.

Now that we have our custom object, read on to learn how to access the properties!

Returning Properties from a PSCustomObject

Just creating an object doesn’t do much good, so how do we go about retrieving the members? Just like any other typical PowerShell object, we can simply pass the name of the property using dot-notation to the object. There are three flexible ways to be aware of, as shown below.


As you can see from above, there are a lot of ways that we can address a property using PSCustomObject. What else can we do with our PSCustomObject? To find out, read on!

Extending our PSCustomObject

Ok, so now that we have a basic object what can we do with it? Since this is a standard PowerShell object, we have the ability to use more than just a NoteProperty on the object. Most of the time you will just use the key-value pair that is a NoteProperty, but we can actually extend the object to use an evaluated ScriptBlock every time the object is accessed. Let’s create a new object with two properties, one that is a NoteProperty and the second, which is a ScriptBlock that just returns the output from Get-Date.

You may notice on subsequent runs that the value of DateTime is not updating. That is because the output is evaluated on the creation of the object. If we want to have this code dynamically evaluated we need an actual ScriptProperty member type. To do this, we need to use Add-Member as shown in the following.

As you can see from the above code, each time the code is run the DateTimeDynamic is evaluated and returned.

Bonus! Returning a Function as a Property

Even cooler is the ability to return a function as a property! Simply assign the function to a property name and it will run and store the value in the memory of the object the first time it is run.

Conclusion

As you can see, PSCustomObject is incredibly useful. There are many possibilities that the object unlocks, especially with the ScriptBlock and ScriptProperty methods. With the ability to evaluate a function as a value as well, you can easily extend the object in to unique use cases. Explore PSCustomObject and see how it can be added to your scripts today!

Related Topics:

  • PowerShell
  • BECOME A PETRI MEMBER:

    Don't have a login but want to join the conversation? Sign up for a Petri Account

    Register
    Entrepreneur, hustler, husband, dad, Automator, content producer, published author, Microsoft MVP, DevOps pro and passionate problem-solver.