How to use the -ExpandProperty Switch with PowerShell

  • Post author:
  • Post category:Main
  • Post last modified:August 7, 2023
  • Reading time:8 mins read

The -ExpandProperty switch in PowerShell allows you to extract the values of specific properties and can be applied to various different scenarios. In this tutorial, I am going to explain to your what the -ExpandProperty switch does and how it differs from the -Property switch. I will also go through various useful examples to demonstrate how you can use the -ExpandProperty switch in different commands or scripts.

System requirements

To run the commands in this tutorial you should be running at least PowerShell version 5.1 and using a Windows 10 or 11 device. I also provide some examples using cmdlets found in the Microsoft Graph PowerShell module, against Microsoft 365. So you can also check out my tutorial on How To Install the Microsoft Graph PowerShell Module.

About the -ExpandProperty switch

The -ExpandProperty switch belongs to the Select-Object cmdlet. When using this switch it indicates to make an attempt is to be made to expand a property of an object. If that selected property is in an array, the value of the array will be returned, whereas, if the select property is an object, the properties of that object are returned for every property inputted.

Examples using the -ExpandProperty switch

Let’s look at some examples of how the -ExpandProperty switch can be used. I will first create a demo object, then I will use some real-world examples of where it may be useful.

ExpandProperty Example 1

I’ll start by creating a new ‘demo’ object named $Object1, within this object I have included the Neighbours property which is an ArrayList of numbers.

$Object1 = [PSCustomObject]@{
    Name = "House"
    HouseNumber = "133"
    Neighbours = [System.Collections.ArrayList]@(
        132, 134

We can view the object in our console by just entering the object name, see how the neighbours property shows on a single line.

Object1 output
Object1 output

The -ExpandProperty switch in this instance can help up extract the values of the Neighbours array. 

$object1 | Select -ExpandProperty Neighbours

Now that we have expanded the Neighbours property, we are returned the values within the array. As we now have the values, we can perform independent actions or each item or action each item independently in a loop.

ExpandProperty for Array
ExpandProperty for Array

Let’s take this example one step further, below I have changed the Neighbours property to a custom object and embedded an array list of names within the Members property.

$object2 = [PSCustomObject]@{
    Name = "House"
    HouseNumber = "133"
    Neighbours = [PSCustomObject]@{
        HouseNumber = "122"
        Members = [System.Collections.ArrayList]@("Daniel", "Jas")
        Car = "Audi"

If we then type $Object2 into our console, we get the below output, where it is clear to us there is nested information within the Neighbours object that is not immediately readable.

Object2 Result
Object2 Result

This information can be extracted by using the -ExpandProperty switch.

$object2 | Select -ExpandProperty Neighbours

You can see now that we have expanded the Neighbours object, we are returned the properties of the object.

Object2 ExpandProperty
Object2 ExpandProperty

If you wanted to then select only the value of the member list, the simplest way would be to wrap the command in parentheses and select the Members property, as I have done in the example below. 

($object2 | Select -ExpandProperty Neighbours).Members

The content contained within the Parentheses is executed first, then we can select the member property of the result to output to our session. 

Expanded Property in Parentheses
Expanded Property in Parentheses

ExpandProperty Example 2

In this example we are going to use the Get-ComputerInfo cmdlet to find information on a computers Operating System.

Starting out we will use the Get-ComputerInfo cmdlet and select the OsSuite property that contains only the available OS Suites.

Get-ComputerInfo | Select  OsSuites

We can see the result of our command is a generic NoteProperty containing information on the OS Suites.

Get-ComputerInfo Output
Get-ComputerInfo Output

In a similar way to one of our earlier examples, we can expand this property to retrieve only the values of the OsSuites property.

Get-ComputerInfo | Select -ExpandProperty OsSuites

From the output below we can see that we now have retrieved only the individual values of the property.

Expand OsSuites Property
Expand OsSuites Property

ExpandProperty Example 3

In this last example, I am using commands from the Microsoft Graph PowerShell module to manage Microsoft 365. My full tutorial titled; How To Use Get-MgUser with Microsoft Graph PowerShell explains more about the Get-MgUser cmdlet.

Below I am trying to find the SignInActivity information for a specific user in my Microsoft 365 tenant.

get-mguser -userid d3657241-22d5-4606-90b7-ce4d0a52f074 | `
Select SignInActivity

However, when I select the SignInActivity property I have resulted with the object name: Microsoft.Graph.PowerShell.Models.MicrosoftGraphSignInActivity.

SignIn Activity Example NotExpanded
SignIn Activity Example NotExpanded

To find the information we need, we need to use the -ExpandProperty switch to return the information within this object.

get-mguser -userid d3657241-22d5-4606-90b7-ce4d0a52f074 `
-Property signinactivity | Select-Object -ExpandProperty signinactivity

Once the above command is run, you can see from the below that we can now find the information we were looking for.

SignIn Activity Example Expanded
SignIn Activity Example Expanded


In this tutorial, I have explained the purpose of the -ExpandProperty switch in PowerShell which belongs to the Select-Object cmdlet. Some real-world and fictional examples have also been demonstrated to help you understand how to use this in practice.

Daniel Bradley

My name is Daniel Bradley and I work with Microsoft 365 and Azure as an Engineer and Consultant. I enjoy writing technical content for you and engaging with the community. All opinions are my own.

This Post Has 2 Comments

  1. Rodrigo

    Thanks a lot for this info, post and knwoledge that you shared to us! It was very helpful to understand how -ExpandProperty works.
    I’m a beginner in powerShell and with this explanation I can use it now for my own exercises.
    Thank you!

    1. Daniel

      Thank you for the kind response!

Leave a Reply