about_Member-Access_Enumeration

Article
12/13/2022

Short description

Describes the automatic enumeration of list collection items when using the member-access operator.

Long description

Starting in PowerShell 3.0, the member-access enumeration feature improves the convenience of using the member-access operator (.) on list collection objects. When you use the member-access operator to access a member that does not exist on a collection, PowerShell automatically enumerates the items in the collection and attempts to access the specified member on each item.

Member-access enumeration helps you write simpler and shorter code. Instead of piping a collection object to ForEach-Object or using the ForEach() intrinsic method to access members on each item in the collection, you can use the member-access operator on the collection object.

These commands are functionally identical with the last one demonstrating use of the member-access operator:

Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName }
(Get-Service -Name event*).ForEach({ $_.DisplayName })
(Get-Service -Name event*).DisplayName

Windows Event Log
COM+ Event System

Windows Event Log
COM+ Event System

Windows Event Log
COM+ Event System

Note

You can use the member-access operator to get the values of a property on items in a collection but you can't use it to set them directly. For more information, see about_Arrays.

When you use the member-access operator on any object and the specified member exists on that object, the member is invoked. For property members, the operator returns the value of that property. For method members, the operator calls that method on the object.

When you use the member-access operator on a list collection object that doesn't have the specified member, PowerShell automatically enumerates the items in that collection and uses the member-access operator on each enumerated item.

You can check if an object is a list collection by seeing whether its type implements the IList interface:

$List = @('a', 'b')
$Hash = @{ a = 'b' }
$List.GetType().ImplementedInterfaces.Name -contains 'IList'
$Hash.GetType().ImplementedInterfaces.Name -contains 'IList'

True

False

During member-access enumeration for a property, the operator returns the value of the property for each item that has that property. If no items have the specified property, the operator returns $null.

During member-access enumeration for a method, the operator attempts to call the method on each item in the collection. If any item in the collection does not have the specified method, the operator returns the MethodNotFound exception.

Warning

During member-access enumeration for a method, the method is called on each item in the collection. If the method you are calling makes changes, the changes are made for every item in the collection. If an error occurs during enumeration, the method is called only on the items enumerated before the error. For additional safety, consider manually enumerating the items and explicitly handling any errors.

The following examples detail the behavior of the member-access operator under all possible scenarios.

Accessing members of a non-list object

When you use the member-access operator on an object that is not a list collection and that has the member, the command returns the value of the property or output of the method for that object.

$MyString = 'abc'
$MyString.Length
$MyString.ToUpper()

3

ABC

When you use the member-access operator on a non-list object that does not have the member, the command returns $null if you specify a property or a MethodNotFound error if you specify a method.

$MyString = 'abc'
$null -eq $MyString.DoesNotExist
$MyString.DoesNotExist()

True

InvalidOperation:
Line |
   3 |  $MyString.DoesNotExist()
     |  ~~~~~~~~~~~~~~~~~~~~~~~~
     | Method invocation failed because [System.String] does not contain a method named 'DoesNotExist'.

Accessing members of a list collection object

When you use the member-access operator on a collection object that has the member, it always returns the property value or method result for the collection object.

Accessing members that exist on the collection but not its items

In this example, the specified members exist on the collection but not the items in it.

[System.Collections.Generic.List[string]]$Collection = @('a', 'b')
$Collection.IsReadOnly
$Collection.Add('c')
$Collection

False

a
b
c

Accessing members that exist on the collection and its items

For this example, the specified members exist on both the collection and the items in it. Compare the results of the commands using the member-access operator on the collection to the results from using the member-access operator on the collection items in ForEach-Object. On the collection, the operator returns the property value or method result for the collection object and not the items in it.

[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
$Collection.Count
$Collection | ForEach-Object -Process { $_.Count }
$Collection.ToString()
$Collection | ForEach-Object -Process { $_.ToString() }

3

1
1
1

System.Collections.Generic.List`1[System.String]

a
b
c

Note

Collections that implement the System.Collections.IDictionary interface, such as HashTable and OrderedDictionary, have a different behavior. When you use the member-access operator on a dictionary that has a key with the same name as a property, it returns the key's value instead of the property's.

You can access the dictionary object's property value with the psbase intrinsic member. For example, if the key name is keys and you want to return the collection of the HashTable keys, use this syntax:

$hashtable.PSBase.Keys

Accessing members that exist on all items in a collection but not itself

When you use the member-access operator on a collection object that does not have the member but the items in it do, PowerShell enumerates the items in the collection and returns the property value or method result for each item.

[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
$Collection.Length
$Collection.ToUpper()

1
1
1

A
B
C

Accessing members that exist on neither the collection nor its items

When you use the member-access operator on a collection object that does not have the member and neither do the items in it, the command returns $null if you specify a property or a MethodNotFound error if you specify a method.

[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c')
$null -eq $Collection.DoesNotExist
$Collection.DoesNotExist()

True

InvalidOperation:
Line |
   3 |  $Collection.DoesNotExist()
     |  ~~~~~~~~~~~~~~~~~~~~~~~~~~
     | Method invocation failed because [System.String] does not contain a method named 'DoesNotExist'.

Because the collection object does not have the member, PowerShell enumerated the items in the collection. Notice that the MethodNotFound error specifies that System.String does not contain the method instead of System.Collections.Generic.List.

Accessing methods that exist only on some items in a collection

When you use the member-access operator to access a method on a collection object that does not have the method and only some of the items in the collection have it, the command returns a MethodNotFound error for the first item in the collection that does not have the method. Even though the method gets called on some items, the command only returns the error.

@('a', 1, 'c').ToUpper()

InvalidOperation: Method invocation failed because [System.Int32] does not contain a method named 'ToUpper'.

Accessing properties that exist only on some items in a collection

When you use the member-access operator to access a property on a collection object that does not have the property and only some of the items in the collection have it, the command returns the property value for each item in the collection that has the property.

$CapitalizedProperty = @{
    MemberType = 'ScriptProperty'
    Name       = 'Capitalized'
    Value      = { $this.ToUpper() }
    PassThru   = $true
}
[System.Collections.Generic.List[object]]$MixedCollection = @(
    'a'
    ('b' | Add-Member @CapitalizedProperty)
    ('c' | Add-Member @CapitalizedProperty)
    'd'
)
$MixedCollection.Capitalized

B
C