| Service | Microsoft Docs article | Related commit history on GitHub | Change details |
|---|---|---|---|
| Microsoft.PowerShell.Core | About Arrays (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md | --- description: Describes arrays, which are data structures designed to store collections of items. Locale: en-US Previously updated : 06/25/2021 Last updated : 03/16/2022 no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple] online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 $a[-1] 4 ``` -## Member enumeration +## Member-access enumeration -You can use member enumeration to get property values from all members of a -collection. When you use the member access operator (`.`) with a member name on -a collection object, such as an array, if the collection object does not have a -member of that name, the items of the collection are enumerated and PowerShell -looks for that member on each item. This applies to both property and method -members. +Starting in PowerShell 3.0, when you use the member-access operator to access a +member that does not exist on a list collection, PowerShell automatically +enumerates the items in the collection and attempts to access the specified +member on each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). ++### Examples The following example creates two new files and stores the resulting objects in the array variable `$files`. Since the array object does not have the Friday, June 25, 2021 1:21:17 PM Friday, June 25, 2021 1:21:17 PM ``` -Member enumeration can be used to _get_ values from items in a collection, but -it cannot be used to _set_ values on items in a collection. For example: +Member-access enumeration enables you to _get_ values from items in a +collection, but not to _set_ values on items in a collection. For example: ```powershell $files.LastWriteTime = (Get-Date).AddDays(-1) LastWriteTimeUtc Property datetime LastWriteTimeUtc {get;set;} - [about_Assignment_Operators](about_Assignment_Operators.md) - [about_Hash_Tables](about_Hash_Tables.md)+- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) - [about_Operators](about_Operators.md) - [about_For](about_For.md) - [about_Foreach](about_Foreach.md) |
| Microsoft.PowerShell.Core | About Member Access Enumeration (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md | +--- +description: Describes the automatic enumeration of list collection items when using the member-access operator. +Locale: en-US Last updated : 03/16/2022+online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_member-access_enumeration?view=powershell-5.1&WT.mc_id=ps-gethelp +schema: 2.0.0 + Title: about Member-Access Enumeration +--- +# about_Member-Access_Enumeration ++## 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](about_Intrinsic_Members.md#methods) 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: ++```powershell +Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName } +(Get-Service -Name event*).ForEach({ $_.DisplayName }) +(Get-Service -Name event*).DisplayName +``` ++```Output +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](about_Arrays.md#member-access-enumeration). ++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: ++```powershell +$List = @('a', 'b') +$Hash = @{ a = 'b' } +$List.GetType().ImplementedInterfaces.Name -contains 'IList' +$Hash.GetType().ImplementedInterfaces.Name -contains 'IList' +``` ++```Output +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 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. ++```powershell +$MyString = 'abc' +$MyString.Length +$MyString.ToUpper() +``` ++```Output +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. ++```powershell +$MyString = 'abc' +$null -eq $MyString.DoesNotExist +$MyString.DoesNotExist() +``` ++```Output +True ++Method invocation failed because [System.String] does not contain a method +named 'DoesNotExist'. +At line:1 char:1 ++ $MyString.DoesNotExist()++ ~~~~~~~~~~~~~~~~~~~~~~+ + CategoryInfo : InvalidOperation: (:) [], RuntimeException + + FullyQualifiedErrorId : MethodNotFound +``` ++## 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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b') +$Collection.IsReadOnly +$Collection.Add('c') +$Collection +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$Collection.Count +$Collection | ForEach-Object -Process { $_.Count } +$Collection.ToString() +$Collection | ForEach-Object -Process { $_.ToString() } +``` ++```Output +3 ++1 +1 +1 ++System.Collections.Generic.List`1[System.String] ++a +b +c +``` ++### 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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$Collection.Length +$Collection.ToUpper() +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$null -eq $Collection.DoesNotExist +$Collection.DoesNotExist() +``` ++```Output +True ++Method invocation failed because [System.String] does not contain a method +named 'DoesNotExist'. +At line:1 char:1 ++ $Collection.DoesNotExist()++ ~~~~~~~~~~~~~~~~~~~~~~~~~~+ + CategoryInfo : InvalidOperation: (:) [], RuntimeException + + FullyQualifiedErrorId : MethodNotFound +``` ++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. ++```powershell +@('a', 1, 'c').ToUpper() +``` ++```Output +Method invocation failed because [System.Int32] does not contain a method +named 'ToUpper'. +At line:1 char:1 ++ @('a', 1, 'c').ToUpper()++ ~~~~~~~~~~~~~~~~~~~~~~~~+ + CategoryInfo : InvalidOperation: (:) [], RuntimeException + + FullyQualifiedErrorId : MethodNotFound +``` ++### 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. ++```powershell +$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 +``` ++```Output +B +C +``` ++## See Also ++- [about_Arrays](about_Arrays.md) +- [about_Methods](about_Methods.md) +- [about_Operators](about_Operators.md) +- [about_Properties](about_Properties.md) +- [about_Intrinsic_Members](about_Intrinsic_Members.md) |
| Microsoft.PowerShell.Core | About Methods (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Methods.md | --- description: Describes how to use methods to perform actions on objects in PowerShell. Locale: en-US Previously updated : 03/15/2021 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_methods?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Methods file to the `C:\Bin` directory, and to overwrite existing files. (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt", $true) ``` -## Methods of Scalar objects and Collections +## Member-access enumeration -The methods of one ("scalar") object of a particular type are often different -from the methods of a collection of objects of the same type. --For example, every process has a `Kill` method, but a collection of processes -does not have a Kill method. --Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that -result from the differing methods of scalar objects and collections. --If you submit a collection, but request a method that exists only on single -("scalar") objects, PowerShell invokes the method on every object in the -collection. --If the method exists on the individual objects and on the collection, only -the collection's method is invoked. --This feature also works on properties of scalar objects and collections. For -more information, see [about_Properties](about_Properties.md). +Starting in PowerShell 3.0, when you use the member-access operator (`.`) to +access a method that does not exist on a list collection, PowerShell +automatically enumerates the items in the collection and invokes the method on +each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). ### Examples Add-Type -TypeDefinition @' '@ ``` -In this example the less specific `object` overload of the **Bar** method was chosen. +In this example the less specific `object` overload of the **Bar** method was +chosen. ```powershell [Foo]::new().Bar(1) method. ## See also -[about_Objects](about_Objects.md) --[about_Properties](about_Properties.md) --[Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) +- [about_Objects](about_Objects.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Properties](about_Properties.md) +- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) |
| Microsoft.PowerShell.Core | About Operators (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md | --- description: Describes the operators that are supported by PowerShell. Locale: en-US Previously updated : 11/16/2021 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Operators You can also create ranges in reverse order. 5..-5 | ForEach-Object {Write-Output $_} ``` -### Member access operator `.` +### Member-access operator `.` Accesses the properties and methods of an object. The member name may be an expression. $myProcess.peakWorkingSet 'OS', 'Platform' | Foreach-Object { $PSVersionTable. $_ } ``` +Starting PowerShell 3.0, when you use the operator on a list collection object +that does not have the member, PowerShell automatically enumerates the items in +that collection and uses the operator on each of them. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). + ### Static member operator `::` Calls the static properties and methods of a .NET Framework class. To of the `Get-Member` cmdlet. The member name may be an expression. ## See also -[about_Arithmetic_Operators](about_Arithmetic_Operators.md) --[about_Assignment_Operators](about_Assignment_Operators.md) --[about_Comparison_Operators](about_Comparison_Operators.md) --[about_Logical_Operators](about_logical_operators.md) --[about_Operator_Precedence](about_operator_precedence.md) --[about_Type_Operators](about_Type_Operators.md) --[about_Split](about_Split.md) --[about_Join](about_Join.md) --[about_Redirection](about_Redirection.md) +- [about_Arithmetic_Operators](about_Arithmetic_Operators.md) +- [about_Assignment_Operators](about_Assignment_Operators.md) +- [about_Comparison_Operators](about_Comparison_Operators.md) +- [about_Logical_Operators](about_logical_operators.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Operator_Precedence](about_operator_precedence.md) +- [about_Type_Operators](about_Type_Operators.md) +- [about_Split](about_Split.md) +- [about_Join](about_Join.md) +- [about_Redirection](about_Redirection.md) |
| Microsoft.PowerShell.Core | About Properties (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Properties.md | --- description: Describes how to use object properties in PowerShell. Locale: en-US Previously updated : 12/01/2017 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_properties?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Properties property of the `System.DateTime` class. [System.DateTime]::UtcNow ``` -### Properties of scalar objects and collections +## Member-access enumeration -The properties of one ("scalar") object of a particular type are often -different from the properties of a collection of objects of the same type. -For example, every service has as **DisplayName** property, but a collection -of services does not have a **DisplayName** property. +Starting in PowerShell 3.0, when you use the member-access operator (`.`) to +access a property that does not exist on a list collection, PowerShell +automatically enumerates the items in the collection and returns the value of +the property on each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). -The following command gets the value of the **DisplayName** property of the -'Audiosrv' service. +### Examples -```powershell -(Get-Service Audiosrv).DisplayName -``` --```output -Windows Audio -``` --Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that -result from the differing properties of scalar objects and collections. The -same command returns the value of the **DisplayName** property of every service +This command returns the value of the **DisplayName** property of every service that `Get-Service` returns. ```powershell Application Information ... ``` -When you submit a collection, but request a property that exists only on -single ("scalar") objects, PowerShell returns the value of that property -for every object in the collection. - All collections have a **Count** property that returns how many objects are in the collection. the collection. 176 ``` -Beginning in PowerShell 3.0, if you request the Count or Length property of -zero objects or one object, PowerShell returns the correct value. +Starting in PowerShell 3.0, if you request the **Count** or **Length** property +of zero objects or one object, PowerShell returns the correct value. ```powershell (Get-Service Audiosrv).Count only the collection's property is returned. 2 ``` -This feature also works on methods of scalar objects and collections. For more -information, see [about_Methods](about_methods.md). - ## See also -[about_Methods](about_Methods.md) --[about_Objects](about_Objects.md) --[Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) --[Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object) --[Format-List](xref:Microsoft.PowerShell.Utility.Format-List) +- [about_Objects](about_Objects.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Methods](about_Methods.md) +- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) +- [Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object) +- [Format-List](xref:Microsoft.PowerShell.Utility.Format-List) |
| Microsoft.PowerShell.Core | About Arrays (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Arrays.md | --- description: Describes arrays, which are data structures designed to store collections of items. Locale: en-US Previously updated : 06/25/2021 Last updated : 03/16/2022 no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple] online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 faster, especially for large arrays. ## Arrays of zero or one -Beginning in Windows PowerShell 3.0, a collection of zero or one object has -the Count and Length property. Also, you can index into an array of one +Beginning in Windows PowerShell 3.0, a collection of zero or one object has the +**Count** and **Length** properties. Also, you can index into an array of one object. This feature helps you to avoid scripting errors that occur when a command that expects a collection gets fewer than two items. arrays of objects. For more information, see [System.Tuple](/dotnet/api/system.tuple). -## Member enumeration +## Member-access enumeration ++Starting in PowerShell 3.0, when you use the member-access operator to access a +member that does not exist on a list collection, PowerShell automatically +enumerates the items in the collection and attempts to access the specified +member on each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). -You can use member enumeration to get property values from all members of a -collection. When you use the member access operator (`.`) with a member name on -a collection object, such as an array, if the collection object does not have a -member of that name, the items of the collection are enumerated and PowerShell -looks for that member on each item. This applies to both property and method -members. +### Examples The following example creates two new files and stores the resulting objects in the array variable `$files`. Since the array object does not have the Friday, June 25, 2021 1:21:17 PM Friday, June 25, 2021 1:21:17 PM ``` -Member enumeration can be used to _get_ values from items in a collection, but -it cannot be used to _set_ values on items in a collection. For example: +Member-access enumeration enables you to _get_ values from items in a +collection, but not to _set_ values on items in a collection. For example: ```powershell $files.LastWriteTime = (Get-Date).AddDays(-1) LastWriteTimeUtc Property datetime LastWriteTimeUtc {get;set;} - [about_Assignment_Operators](about_Assignment_Operators.md) - [about_Hash_Tables](about_Hash_Tables.md)+- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) - [about_Operators](about_Operators.md) - [about_For](about_For.md) - [about_Foreach](about_Foreach.md) |
| Microsoft.PowerShell.Core | About Member Access Enumeration (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md | +--- +description: Describes the automatic enumeration of list collection items when using the member-access operator. +Locale: en-US Last updated : 03/16/2022+online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_member-access_enumeration?view=powershell-7&WT.mc_id=ps-gethelp +schema: 2.0.0 + Title: about Member-Access Enumeration +--- +# about_Member-Access_Enumeration ++## 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](about_Intrinsic_Members.md#methods) 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: ++```powershell +Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName } +(Get-Service -Name event*).ForEach({ $_.DisplayName }) +(Get-Service -Name event*).DisplayName +``` ++```Output +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](about_Arrays.md#member-access-enumeration). ++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: ++```powershell +$List = @('a', 'b') +$Hash = @{ a = 'b' } +$List.GetType().ImplementedInterfaces.Name -contains 'IList' +$Hash.GetType().ImplementedInterfaces.Name -contains 'IList' +``` ++```Output +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 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. ++```powershell +$MyString = 'abc' +$MyString.Length +$MyString.ToUpper() +``` ++```Output +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. ++```powershell +$MyString = 'abc' +$null -eq $MyString.DoesNotExist +$MyString.DoesNotExist() +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b') +$Collection.IsReadOnly +$Collection.Add('c') +$Collection +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$Collection.Count +$Collection | ForEach-Object -Process { $_.Count } +$Collection.ToString() +$Collection | ForEach-Object -Process { $_.ToString() } +``` ++```Output +3 ++1 +1 +1 ++System.Collections.Generic.List`1[System.String] ++a +b +c +``` ++### 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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$Collection.Length +$Collection.ToUpper() +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$null -eq $Collection.DoesNotExist +$Collection.DoesNotExist() +``` ++```Output +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. ++```powershell +@('a', 1, 'c').ToUpper() +``` ++```Output +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. ++```powershell +$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 +``` ++```Output +B +C +``` ++## See Also ++- [about_Arrays](about_Arrays.md) +- [about_Methods](about_Methods.md) +- [about_Operators](about_Operators.md) +- [about_Properties](about_Properties.md) +- [about_Intrinsic_Members](about_Intrinsic_Members.md) |
| Microsoft.PowerShell.Core | About Methods (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Methods.md | --- description: Describes how to use methods to perform actions on objects in PowerShell. Locale: en-US Previously updated : 03/15/2021 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_methods?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Methods file to the `C:\Bin` directory, and to overwrite existing files. (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt", $true) ``` -## Methods of Scalar objects and Collections +## Member-access enumeration -The methods of one ("scalar") object of a particular type are often different -from the methods of a collection of objects of the same type. --For example, every process has a `Kill` method, but a collection of processes -does not have a Kill method. --Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that -result from the differing methods of scalar objects and collections. --If you submit a collection, but request a method that exists only on single -("scalar") objects, PowerShell invokes the method on every object in the -collection. --If the method exists on the individual objects and on the collection, only -the collection's method is invoked. --This feature also works on properties of scalar objects and collections. For -more information, see [about_Properties](about_Properties.md). +Starting in PowerShell 3.0, when you use the member-access operator (`.`) to +access a method that does not exist on a list collection, PowerShell +automatically enumerates the items in the collection and invokes the method on +each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). ### Examples Add-Type -TypeDefinition @' '@ ``` -In this example the less specific `object` overload of the **Bar** method was chosen. +In this example the less specific `object` overload of the **Bar** method was +chosen. ```powershell [Foo]::new().Bar(1) method. ## See also -[about_Objects](about_Objects.md) --[about_Properties](about_Properties.md) --[Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) +- [about_Objects](about_Objects.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Properties](about_Properties.md) +- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) |
| Microsoft.PowerShell.Core | About Operators (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Operators.md | --- description: Describes the operators that are supported by PowerShell. Locale: en-US Previously updated : 11/16/2021 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Operators B A ``` -### Member access operator `.` +### Member-access operator `.` Accesses the properties and methods of an object. The member name may be an expression. $myProcess.peakWorkingSet 'OS', 'Platform' | Foreach-Object { $PSVersionTable. $_ } ``` +Starting PowerShell 3.0, when you use the operator on a list collection object +that does not have the member, PowerShell automatically enumerates the items in +that collection and uses the operator on each of them. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). + ### Static member operator `::` Calls the static properties and methods of a .NET Framework class. To ${a}?[0] ## See also -[about_Arithmetic_Operators](about_Arithmetic_Operators.md) --[about_Assignment_Operators](about_Assignment_Operators.md) --[about_Comparison_Operators](about_Comparison_Operators.md) --[about_Logical_Operators](about_logical_operators.md) --[about_Operator_Precedence](about_operator_precedence.md) --[about_Type_Operators](about_Type_Operators.md) --[about_Pipeline_Chain_Operators](about_Pipeline_Chain_Operators.md) --[about_Split](about_Split.md) --[about_Join](about_Join.md) --[about_Redirection](about_Redirection.md) +- [about_Arithmetic_Operators](about_Arithmetic_Operators.md) +- [about_Assignment_Operators](about_Assignment_Operators.md +- [about_Comparison_Operators](about_Comparison_Operators.md +- [about_Logical_Operators](about_logical_operators.md +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md +- [about_Operator_Precedence](about_operator_precedence.md +- [about_Type_Operators](about_Type_Operators.md +- [about_Pipeline_Chain_Operators](about_Pipeline_Chain_Operators.md +- [about_Split](about_Split.md +- [about_Join](about_Join.md +- [about_Redirection](about_Redirection.md |
| Microsoft.PowerShell.Core | About Properties (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Properties.md | --- description: Describes how to use object properties in PowerShell. Locale: en-US Previously updated : 12/01/2017 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_properties?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Properties property of the `System.DateTime` class. [System.DateTime]::UtcNow ``` -### Properties of scalar objects and collections +## Member-access enumeration -The properties of one ("scalar") object of a particular type are often -different from the properties of a collection of objects of the same type. -For example, every service has as **DisplayName** property, but a collection -of services does not have a **DisplayName** property. +Starting in PowerShell 3.0, when you use the member-access operator (`.`) to +access a property that does not exist on a list collection, PowerShell +automatically enumerates the items in the collection and returns the value of +the property on each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). -The following command gets the value of the **DisplayName** property of the -'Audiosrv' service. +### Examples -```powershell -(Get-Service Audiosrv).DisplayName -``` --```output -Windows Audio -``` --Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that -result from the differing properties of scalar objects and collections. The -same command returns the value of the **DisplayName** property of every service +This command returns the value of the **DisplayName** property of every service that `Get-Service` returns. ```powershell Application Information ... ``` -When you submit a collection, but request a property that exists only on -single ("scalar") objects, PowerShell returns the value of that property -for every object in the collection. - All collections have a **Count** property that returns how many objects are in the collection. the collection. 176 ``` -Beginning in PowerShell 3.0, if you request the Count or Length property of -zero objects or one object, PowerShell returns the correct value. +Starting in PowerShell 3.0, if you request the **Count** or **Length** property +of zero objects or one object, PowerShell returns the correct value. ```powershell (Get-Service Audiosrv).Count only the collection's property is returned. 2 ``` -This feature also works on methods of scalar objects and collections. For more -information, see [about_Methods](about_methods.md). - ## See also -[about_Methods](about_Methods.md) --[about_Objects](about_Objects.md) --[Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) --[Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object) --[Format-List](xref:Microsoft.PowerShell.Utility.Format-List) +- [about_Objects](about_Objects.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Methods](about_Methods.md) +- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) +- [Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object) +- [Format-List](xref:Microsoft.PowerShell.Utility.Format-List) |
| Microsoft.PowerShell.Core | About Arrays (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Arrays.md | --- description: Describes arrays, which are data structures designed to store collections of items. Locale: en-US Previously updated : 06/25/2021 Last updated : 03/16/2022 no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple] online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 faster, especially for large arrays. ## Arrays of zero or one -Beginning in Windows PowerShell 3.0, a collection of zero or one object has -the Count and Length property. Also, you can index into an array of one +Beginning in Windows PowerShell 3.0, a collection of zero or one object has the +**Count** and **Length** properties. Also, you can index into an array of one object. This feature helps you to avoid scripting errors that occur when a command that expects a collection gets fewer than two items. arrays of objects. For more information, see [System.Tuple](/dotnet/api/system.tuple). -## Member enumeration +## Member-access enumeration ++Starting in PowerShell 3.0, when you use the member-access operator to access a +member that does not exist on a list collection, PowerShell automatically +enumerates the items in the collection and attempts to access the specified +member on each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). -You can use member enumeration to get property values from all members of a -collection. When you use the member access operator (`.`) with a member name on -a collection object, such as an array, if the collection object does not have a -member of that name, the items of the collection are enumerated and PowerShell -looks for that member on each item. This applies to both property and method -members. +### Examples The following example creates two new files and stores the resulting objects in the array variable `$files`. Since the array object does not have the Friday, June 25, 2021 1:21:17 PM Friday, June 25, 2021 1:21:17 PM ``` -Member enumeration can be used to _get_ values from items in a collection, but -it cannot be used to _set_ values on items in a collection. For example: +Member-access enumeration enables you to _get_ values from items in a +collection, but not to _set_ values on items in a collection. For example: ```powershell $files.LastWriteTime = (Get-Date).AddDays(-1) LastWriteTimeUtc Property datetime LastWriteTimeUtc {get;set;} - [about_Assignment_Operators](about_Assignment_Operators.md) - [about_Hash_Tables](about_Hash_Tables.md)+- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) - [about_Operators](about_Operators.md) - [about_For](about_For.md) - [about_Foreach](about_Foreach.md) |
| Microsoft.PowerShell.Core | About Member Access Enumeration (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md | +--- +description: Describes the automatic enumeration of list collection items when using the member-access operator. +Locale: en-US Last updated : 03/16/2022+online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_member-access_enumeration?view=powershell-7.1&WT.mc_id=ps-gethelp +schema: 2.0.0 + Title: about Member-Access Enumeration +--- +# about_Member-Access_Enumeration ++## 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](about_Intrinsic_Members.md#methods) 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: ++```powershell +Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName } +(Get-Service -Name event*).ForEach({ $_.DisplayName }) +(Get-Service -Name event*).DisplayName +``` ++```Output +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](about_Arrays.md#member-access-enumeration). ++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: ++```powershell +$List = @('a', 'b') +$Hash = @{ a = 'b' } +$List.GetType().ImplementedInterfaces.Name -contains 'IList' +$Hash.GetType().ImplementedInterfaces.Name -contains 'IList' +``` ++```Output +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 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. ++```powershell +$MyString = 'abc' +$MyString.Length +$MyString.ToUpper() +``` ++```Output +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. ++```powershell +$MyString = 'abc' +$null -eq $MyString.DoesNotExist +$MyString.DoesNotExist() +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b') +$Collection.IsReadOnly +$Collection.Add('c') +$Collection +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$Collection.Count +$Collection | ForEach-Object -Process { $_.Count } +$Collection.ToString() +$Collection | ForEach-Object -Process { $_.ToString() } +``` ++```Output +3 ++1 +1 +1 ++System.Collections.Generic.List`1[System.String] ++a +b +c +``` ++### 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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$Collection.Length +$Collection.ToUpper() +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$null -eq $Collection.DoesNotExist +$Collection.DoesNotExist() +``` ++```Output +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. ++```powershell +@('a', 1, 'c').ToUpper() +``` ++```Output +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. ++```powershell +$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 +``` ++```Output +B +C +``` ++## See Also ++- [about_Arrays](about_Arrays.md) +- [about_Methods](about_Methods.md) +- [about_Operators](about_Operators.md) +- [about_Properties](about_Properties.md) +- [about_Intrinsic_Members](about_Intrinsic_Members.md) |
| Microsoft.PowerShell.Core | About Methods (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Methods.md | --- description: Describes how to use methods to perform actions on objects in PowerShell. Locale: en-US Previously updated : 04/08/2020 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_methods?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Methods file to the `C:\Bin` directory, and to overwrite existing files. (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt", $true) ``` -## Methods of Scalar objects and Collections +## Member-access enumeration -The methods of one ("scalar") object of a particular type are often different -from the methods of a collection of objects of the same type. --For example, every process has a `Kill` method, but a collection of processes -does not have a Kill method. --Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that -result from the differing methods of scalar objects and collections. --If you submit a collection, but request a method that exists only on single -("scalar") objects, PowerShell invokes the method on every object in the -collection. --If the method exists on the individual objects and on the collection, only -the collection's method is invoked. --This feature also works on properties of scalar objects and collections. For -more information, see [about_Properties](about_Properties.md). +Starting in PowerShell 3.0, when you use the member-access operator (`.`) to +access a method that does not exist on a list collection, PowerShell +automatically enumerates the items in the collection and invokes the method on +each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). ### Examples Add-Type -TypeDefinition @' '@ ``` -In this example the less specific `object` overload of the **Bar** method was chosen. +In this example the less specific `object` overload of the **Bar** method was +chosen. ```powershell [Foo]::new().Bar(1) method. ## See also -[about_Objects](about_Objects.md) --[about_Properties](about_Properties.md) --[Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) +- [about_Objects](about_Objects.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Properties](about_Properties.md) +- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) |
| Microsoft.PowerShell.Core | About Operators (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Operators.md | --- description: Describes the operators that are supported by PowerShell. Locale: en-US Previously updated : 11/16/2021 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Operators B A ``` -### Member access operator `.` +### Member-access operator `.` Accesses the properties and methods of an object. The member name may be an expression. $myProcess.peakWorkingSet 'OS', 'Platform' | Foreach-Object { $PSVersionTable. $_ } ``` +Starting PowerShell 3.0, when you use the operator on a list collection object +that does not have the member, PowerShell automatically enumerates the items in +that collection and uses the operator on each of them. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). + ### Static member operator `::` Calls the static properties and methods of a .NET Framework class. To ${a}?[0] ## See also -[about_Arithmetic_Operators](about_Arithmetic_Operators.md) --[about_Assignment_Operators](about_Assignment_Operators.md) --[about_Comparison_Operators](about_Comparison_Operators.md) --[about_Logical_Operators](about_logical_operators.md) --[about_Operator_Precedence](about_operator_precedence.md) --[about_Type_Operators](about_Type_Operators.md) --[about_Pipeline_Chain_Operators](about_Pipeline_Chain_Operators.md) --[about_Split](about_Split.md) --[about_Join](about_Join.md) --[about_Redirection](about_Redirection.md) +- [about_Arithmetic_Operators](about_Arithmetic_Operators.md) +- [about_Assignment_Operators](about_Assignment_Operators.md) +- [about_Comparison_Operators](about_Comparison_Operators.md) +- [about_Logical_Operators](about_logical_operators.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Operator_Precedence](about_operator_precedence.md) +- [about_Type_Operators](about_Type_Operators.md) +- [about_Pipeline_Chain_Operators](about_Pipeline_Chain_Operators.md) +- [about_Split](about_Split.md) +- [about_Join](about_Join.md) +- [about_Redirection](about_Redirection.md) |
| Microsoft.PowerShell.Core | About Properties (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Properties.md | --- description: Describes how to use object properties in PowerShell. Locale: en-US Previously updated : 12/01/2017 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_properties?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Properties property of the `System.DateTime` class. [System.DateTime]::UtcNow ``` -### Properties of scalar objects and collections +## Member-access enumeration -The properties of one ("scalar") object of a particular type are often -different from the properties of a collection of objects of the same type. -For example, every service has as **DisplayName** property, but a collection -of services does not have a **DisplayName** property. +Starting in PowerShell 3.0, when you use the member-access operator (`.`) to +access a property that does not exist on a list collection, PowerShell +automatically enumerates the items in the collection and returns the value of +the property on each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). -The following command gets the value of the **DisplayName** property of the -'Audiosrv' service. +### Examples -```powershell -(Get-Service Audiosrv).DisplayName -``` --```output -Windows Audio -``` --Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that -result from the differing properties of scalar objects and collections. The -same command returns the value of the **DisplayName** property of every service +This command returns the value of the **DisplayName** property of every service that `Get-Service` returns. ```powershell Application Information ... ``` -When you submit a collection, but request a property that exists only on -single ("scalar") objects, PowerShell returns the value of that property -for every object in the collection. - All collections have a **Count** property that returns how many objects are in the collection. the collection. 176 ``` -Beginning in PowerShell 3.0, if you request the Count or Length property of -zero objects or one object, PowerShell returns the correct value. +Starting in PowerShell 3.0, if you request the **Count** or **Length** property +of zero objects or one object, PowerShell returns the correct value. ```powershell (Get-Service Audiosrv).Count only the collection's property is returned. 2 ``` -This feature also works on methods of scalar objects and collections. For more -information, see [about_Methods](about_methods.md). - ## See also -[about_Methods](about_Methods.md) --[about_Objects](about_Objects.md) --[Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) --[Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object) --[Format-List](xref:Microsoft.PowerShell.Utility.Format-List) -+- [about_Objects](about_Objects.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Methods](about_Methods.md) +- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) +- [Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object) +- [Format-List](xref:Microsoft.PowerShell.Utility.Format-List) |
| Microsoft.PowerShell.Core | About Arrays (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Arrays.md | --- description: Describes arrays, which are data structures designed to store collections of items. Locale: en-US Previously updated : 06/25/2021 Last updated : 03/16/2022 no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple] online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 faster, especially for large arrays. ## Arrays of zero or one -Beginning in Windows PowerShell 3.0, a collection of zero or one object has -the Count and Length property. Also, you can index into an array of one +Beginning in Windows PowerShell 3.0, a collection of zero or one object has the +**Count** and **Length** properties. Also, you can index into an array of one object. This feature helps you to avoid scripting errors that occur when a command that expects a collection gets fewer than two items. arrays of objects. For more information, see [System.Tuple](/dotnet/api/system.tuple). -## Member enumeration +## Member-access enumeration ++Starting in PowerShell 3.0, when you use the member-access operator to access a +member that does not exist on a list collection, PowerShell automatically +enumerates the items in the collection and attempts to access the specified +member on each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). -You can use member enumeration to get property values from all members of a -collection. When you use the member access operator (`.`) with a member name on -a collection object, such as an array, if the collection object does not have a -member of that name, the items of the collection are enumerated and PowerShell -looks for that member on each item. This applies to both property and method -members. +### Examples The following example creates two new files and stores the resulting objects in the array variable `$files`. Since the array object does not have the Friday, June 25, 2021 1:21:17 PM Friday, June 25, 2021 1:21:17 PM ``` -Member enumeration can be used to _get_ values from items in a collection, but -it cannot be used to _set_ values on items in a collection. For example: +Member-access enumeration enables you to _get_ values from items in a +collection, but not to _set_ values on items in a collection. For example: ```powershell $files.LastWriteTime = (Get-Date).AddDays(-1) LastWriteTimeUtc Property datetime LastWriteTimeUtc {get;set;} - [about_Assignment_Operators](about_Assignment_Operators.md) - [about_Hash_Tables](about_Hash_Tables.md)+- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) - [about_Operators](about_Operators.md) - [about_For](about_For.md) - [about_Foreach](about_Foreach.md) |
| Microsoft.PowerShell.Core | About Member Access Enumeration (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md | +--- +description: Describes the automatic enumeration of list collection items when using the member-access operator. +Locale: en-US Last updated : 03/16/2022+online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_member-access_enumeration?view=powershell-7.2&WT.mc_id=ps-gethelp +schema: 2.0.0 + Title: about Member-Access Enumeration +--- +# about_Member-Access_Enumeration ++## 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](about_Intrinsic_Members.md#methods) 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: ++```powershell +Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName } +(Get-Service -Name event*).ForEach({ $_.DisplayName }) +(Get-Service -Name event*).DisplayName +``` ++```Output +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](about_Arrays.md#member-access-enumeration). ++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: ++```powershell +$List = @('a', 'b') +$Hash = @{ a = 'b' } +$List.GetType().ImplementedInterfaces.Name -contains 'IList' +$Hash.GetType().ImplementedInterfaces.Name -contains 'IList' +``` ++```Output +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 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. ++```powershell +$MyString = 'abc' +$MyString.Length +$MyString.ToUpper() +``` ++```Output +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. ++```powershell +$MyString = 'abc' +$null -eq $MyString.DoesNotExist +$MyString.DoesNotExist() +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b') +$Collection.IsReadOnly +$Collection.Add('c') +$Collection +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$Collection.Count +$Collection | ForEach-Object -Process { $_.Count } +$Collection.ToString() +$Collection | ForEach-Object -Process { $_.ToString() } +``` ++```Output +3 ++1 +1 +1 ++System.Collections.Generic.List`1[System.String] ++a +b +c +``` ++### 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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$Collection.Length +$Collection.ToUpper() +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$null -eq $Collection.DoesNotExist +$Collection.DoesNotExist() +``` ++```Output +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. ++```powershell +@('a', 1, 'c').ToUpper() +``` ++```Output +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. ++```powershell +$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 +``` ++```Output +B +C +``` ++## See Also ++- [about_Arrays](about_Arrays.md) +- [about_Methods](about_Methods.md) +- [about_Operators](about_Operators.md) +- [about_Properties](about_Properties.md) +- [about_Intrinsic_Members](about_Intrinsic_Members.md) |
| Microsoft.PowerShell.Core | About Methods (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Methods.md | --- description: Describes how to use methods to perform actions on objects in PowerShell. Locale: en-US Previously updated : 03/15/2021 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_methods?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Methods file to the `C:\Bin` directory, and to overwrite existing files. (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt", $true) ``` -## Methods of Scalar objects and Collections +## Member-access enumeration -The methods of one ("scalar") object of a particular type are often different -from the methods of a collection of objects of the same type. --For example, every process has a `Kill` method, but a collection of processes -does not have a Kill method. --Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that -result from the differing methods of scalar objects and collections. --If you submit a collection, but request a method that exists only on single -("scalar") objects, PowerShell invokes the method on every object in the -collection. --If the method exists on the individual objects and on the collection, only -the collection's method is invoked. --This feature also works on properties of scalar objects and collections. For -more information, see [about_Properties](about_Properties.md). +Starting in PowerShell 3.0, when you use the member-access operator (`.`) to +access a method that does not exist on a list collection, PowerShell +automatically enumerates the items in the collection and invokes the method on +each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). ### Examples Add-Type -TypeDefinition @' '@ ``` -In this example the less specific `object` overload of the **Bar** method was chosen. +In this example the less specific `object` overload of the **Bar** method was +chosen. ```powershell [Foo]::new().Bar(1) method. ## See also -[about_Objects](about_Objects.md) --[about_Properties](about_Properties.md) --[Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) +- [about_Objects](about_Objects.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Properties](about_Properties.md) +- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) |
| Microsoft.PowerShell.Core | About Operators (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md | --- description: Describes the operators that are supported by PowerShell. Locale: en-US Previously updated : 11/16/2021 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Operators B A ``` -### Member access operator `.` +### Member-access operator `.` Accesses the properties and methods of an object. The member name may be an expression. $myProcess.peakWorkingSet 'OS', 'Platform' | Foreach-Object { $PSVersionTable. $_ } ``` +Starting PowerShell 3.0, when you use the operator on a list collection object +that does not have the member, PowerShell automatically enumerates the items in +that collection and uses the operator on each of them. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). + ### Static member operator `::` Calls the static properties and methods of a .NET Framework class. To ${a}?[0] [about_Logical_Operators](about_logical_operators.md) +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) + [about_Operator_Precedence](about_operator_precedence.md) [about_Type_Operators](about_Type_Operators.md) |
| Microsoft.PowerShell.Core | About Properties (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Properties.md | --- description: Describes how to use object properties in PowerShell. Locale: en-US Previously updated : 12/01/2017 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_properties?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Properties property of the `System.DateTime` class. [System.DateTime]::UtcNow ``` -### Properties of scalar objects and collections +## Member-access enumeration -The properties of one ("scalar") object of a particular type are often -different from the properties of a collection of objects of the same type. -For example, every service has as **DisplayName** property, but a collection -of services does not have a **DisplayName** property. +Starting in PowerShell 3.0, when you use the member-access operator (`.`) to +access a property that does not exist on a list collection, PowerShell +automatically enumerates the items in the collection and returns the value of +the property on each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). -The following command gets the value of the **DisplayName** property of the -'Audiosrv' service. +### Examples -```powershell -(Get-Service Audiosrv).DisplayName -``` --```output -Windows Audio -``` --Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that -result from the differing properties of scalar objects and collections. The -same command returns the value of the **DisplayName** property of every service +This command returns the value of the **DisplayName** property of every service that `Get-Service` returns. ```powershell Application Information ... ``` -When you submit a collection, but request a property that exists only on -single ("scalar") objects, PowerShell returns the value of that property -for every object in the collection. - All collections have a **Count** property that returns how many objects are in the collection. the collection. 176 ``` -Beginning in PowerShell 3.0, if you request the Count or Length property of -zero objects or one object, PowerShell returns the correct value. +Starting in PowerShell 3.0, if you request the **Count** or **Length** property +of zero objects or one object, PowerShell returns the correct value. ```powershell (Get-Service Audiosrv).Count only the collection's property is returned. 2 ``` -This feature also works on methods of scalar objects and collections. For more -information, see [about_Methods](about_methods.md). - ## See also -[about_Methods](about_Methods.md) --[about_Objects](about_Objects.md) --[Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) --[Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object) --[Format-List](xref:Microsoft.PowerShell.Utility.Format-List) -+- [about_Objects](about_Objects.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Methods](about_Methods.md) +- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) +- [Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object) +- [Format-List](xref:Microsoft.PowerShell.Utility.Format-List) |
| Microsoft.PowerShell.Core | About Arrays (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/Microsoft.PowerShell.Core/About/about_Arrays.md | --- description: Describes arrays, which are data structures designed to store collections of items. Locale: en-US Previously updated : 06/25/2021 Last updated : 03/16/2022 no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple] online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 faster, especially for large arrays. ## Arrays of zero or one -Beginning in Windows PowerShell 3.0, a collection of zero or one object has -the Count and Length property. Also, you can index into an array of one +Beginning in Windows PowerShell 3.0, a collection of zero or one object has the +**Count** and **Length** properties. Also, you can index into an array of one object. This feature helps you to avoid scripting errors that occur when a command that expects a collection gets fewer than two items. arrays of objects. For more information, see [System.Tuple](/dotnet/api/system.tuple). -## Member enumeration +## Member-access enumeration ++Starting in PowerShell 3.0, when you use the member-access operator to access a +member that does not exist on a list collection, PowerShell automatically +enumerates the items in the collection and attempts to access the specified +member on each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). -You can use member enumeration to get property values from all members of a -collection. When you use the member access operator (`.`) with a member name on -a collection object, such as an array, if the collection object does not have a -member of that name, the items of the collection are enumerated and PowerShell -looks for that member on each item. This applies to both property and method -members. +### Examples The following example creates two new files and stores the resulting objects in the array variable `$files`. Since the array object does not have the Friday, June 25, 2021 1:21:17 PM Friday, June 25, 2021 1:21:17 PM ``` -Member enumeration can be used to _get_ values from items in a collection, but -it cannot be used to _set_ values on items in a collection. For example: +Member-access enumeration enables you to _get_ values from items in a +collection, but not to _set_ values on items in a collection. For example: ```powershell $files.LastWriteTime = (Get-Date).AddDays(-1) LastWriteTimeUtc Property datetime LastWriteTimeUtc {get;set;} - [about_Assignment_Operators](about_Assignment_Operators.md) - [about_Hash_Tables](about_Hash_Tables.md)+- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) - [about_Operators](about_Operators.md) - [about_For](about_For.md) - [about_Foreach](about_Foreach.md) |
| Microsoft.PowerShell.Core | About Member Access Enumeration (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/Microsoft.PowerShell.Core/About/about_Member-Access_Enumeration.md | +--- +description: Describes the automatic enumeration of list collection items when using the member-access operator. +Locale: en-US Last updated : 03/16/2022+online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_member-access_enumeration?view=powershell-7.3&WT.mc_id=ps-gethelp +schema: 2.0.0 + Title: about Member-Access Enumeration +--- +# about_Member-Access_Enumeration ++## 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](about_Intrinsic_Members.md#methods) 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: ++```powershell +Get-Service -Name event* | ForEach-Object -Process { $_.DisplayName } +(Get-Service -Name event*).ForEach({ $_.DisplayName }) +(Get-Service -Name event*).DisplayName +``` ++```Output +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](about_Arrays.md#member-access-enumeration). ++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: ++```powershell +$List = @('a', 'b') +$Hash = @{ a = 'b' } +$List.GetType().ImplementedInterfaces.Name -contains 'IList' +$Hash.GetType().ImplementedInterfaces.Name -contains 'IList' +``` ++```Output +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 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. ++```powershell +$MyString = 'abc' +$MyString.Length +$MyString.ToUpper() +``` ++```Output +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. ++```powershell +$MyString = 'abc' +$null -eq $MyString.DoesNotExist +$MyString.DoesNotExist() +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b') +$Collection.IsReadOnly +$Collection.Add('c') +$Collection +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$Collection.Count +$Collection | ForEach-Object -Process { $_.Count } +$Collection.ToString() +$Collection | ForEach-Object -Process { $_.ToString() } +``` ++```Output +3 ++1 +1 +1 ++System.Collections.Generic.List`1[System.String] ++a +b +c +``` ++### 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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$Collection.Length +$Collection.ToUpper() +``` ++```Output +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. ++```powershell +[System.Collections.Generic.List[string]]$Collection = @('a', 'b', 'c') +$null -eq $Collection.DoesNotExist +$Collection.DoesNotExist() +``` ++```Output +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. ++```powershell +@('a', 1, 'c').ToUpper() +``` ++```Output +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. ++```powershell +$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 +``` ++```Output +B +C +``` ++## See Also ++- [about_Arrays](about_Arrays.md) +- [about_Methods](about_Methods.md) +- [about_Operators](about_Operators.md) +- [about_Properties](about_Properties.md) +- [about_Intrinsic_Members](about_Intrinsic_Members.md) |
| Microsoft.PowerShell.Core | About Methods (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/Microsoft.PowerShell.Core/About/about_Methods.md | --- description: Describes how to use methods to perform actions on objects in PowerShell. Locale: en-US Previously updated : 03/15/2021 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_methods?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Methods file to the `C:\Bin` directory, and to overwrite existing files. (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt", $true) ``` -## Methods of Scalar objects and Collections +## Member-access enumeration -The methods of one ("scalar") object of a particular type are often different -from the methods of a collection of objects of the same type. --For example, every process has a `Kill` method, but a collection of processes -does not have a Kill method. --Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that -result from the differing methods of scalar objects and collections. --If you submit a collection, but request a method that exists only on single -("scalar") objects, PowerShell invokes the method on every object in the -collection. --If the method exists on the individual objects and on the collection, only -the collection's method is invoked. --This feature also works on properties of scalar objects and collections. For -more information, see [about_Properties](about_Properties.md). +Starting in PowerShell 3.0, when you use the member-access operator (`.`) to +access a method that does not exist on a list collection, PowerShell +automatically enumerates the items in the collection and invokes the method on +each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). ### Examples Add-Type -TypeDefinition @' '@ ``` -In this example the less specific `object` overload of the **Bar** method was chosen. +In this example the less specific `object` overload of the **Bar** method was +chosen. ```powershell [Foo]::new().Bar(1) method. ## See also -[about_Objects](about_Objects.md) --[about_Properties](about_Properties.md) --[Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) +- [about_Objects](about_Objects.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Properties](about_Properties.md) +- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) |
| Microsoft.PowerShell.Core | About Operators (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/Microsoft.PowerShell.Core/About/about_Operators.md | --- description: Describes the operators that are supported by PowerShell. Locale: en-US Previously updated : 11/16/2021 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Operators B A ``` -### Member access operator `.` +### Member-access operator `.` Accesses the properties and methods of an object. The member name may be an expression. $myProcess.peakWorkingSet 'OS', 'Platform' | Foreach-Object { $PSVersionTable. $_ } ``` +Starting PowerShell 3.0, when you use the operator on a list collection object +that does not have the member, PowerShell automatically enumerates the items in +that collection and uses the operator on each of them. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). + ### Static member operator `::` Calls the static properties and methods of a .NET Framework class. To ${a}?[0] ## See also -[about_Arithmetic_Operators](about_Arithmetic_Operators.md) --[about_Assignment_Operators](about_Assignment_Operators.md) --[about_Comparison_Operators](about_Comparison_Operators.md) --[about_Logical_Operators](about_logical_operators.md) --[about_Operator_Precedence](about_operator_precedence.md) --[about_Type_Operators](about_Type_Operators.md) --[about_Pipeline_Chain_Operators](about_Pipeline_Chain_Operators.md) --[about_Split](about_Split.md) --[about_Join](about_Join.md) --[about_Redirection](about_Redirection.md) +- [about_Arithmetic_Operators](about_Arithmetic_Operators.md) +- [about_Assignment_Operators](about_Assignment_Operators.md) +- [about_Comparison_Operators](about_Comparison_Operators.md) +- [about_Logical_Operators](about_logical_operators.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Operator_Precedence](about_operator_precedence.md) +- [about_Type_Operators](about_Type_Operators.md) +- [about_Pipeline_Chain_Operators](about_Pipeline_Chain_Operators.md) +- [about_Split](about_Split.md) +- [about_Join](about_Join.md) +- [about_Redirection](about_Redirection.md) |
| Microsoft.PowerShell.Core | About Properties (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/Microsoft.PowerShell.Core/About/about_Properties.md | --- description: Describes how to use object properties in PowerShell. Locale: en-US Previously updated : 12/01/2017 Last updated : 03/16/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_properties?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Properties property of the `System.DateTime` class. [System.DateTime]::UtcNow ``` -### Properties of scalar objects and collections +## Member-access enumeration -The properties of one ("scalar") object of a particular type are often -different from the properties of a collection of objects of the same type. -For example, every service has as **DisplayName** property, but a collection -of services does not have a **DisplayName** property. +Starting in PowerShell 3.0, when you use the member-access operator (`.`) to +access a property that does not exist on a list collection, PowerShell +automatically enumerates the items in the collection and returns the value of +the property on each item. For more information, see +[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md). -The following command gets the value of the **DisplayName** property of the -'Audiosrv' service. +### Examples -```powershell -(Get-Service Audiosrv).DisplayName -``` --```output -Windows Audio -``` --Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that -result from the differing properties of scalar objects and collections. The -same command returns the value of the **DisplayName** property of every service +This command returns the value of the **DisplayName** property of every service that `Get-Service` returns. ```powershell Application Information ... ``` -When you submit a collection, but request a property that exists only on -single ("scalar") objects, PowerShell returns the value of that property -for every object in the collection. - All collections have a **Count** property that returns how many objects are in the collection. the collection. 176 ``` -Beginning in PowerShell 3.0, if you request the Count or Length property of -zero objects or one object, PowerShell returns the correct value. +Starting in PowerShell 3.0, if you request the **Count** or **Length** property +of zero objects or one object, PowerShell returns the correct value. ```powershell (Get-Service Audiosrv).Count only the collection's property is returned. 2 ``` -This feature also works on methods of scalar objects and collections. For more -information, see [about_Methods](about_methods.md). - ## See also -[about_Methods](about_Methods.md) --[about_Objects](about_Objects.md) --[Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) --[Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object) --[Format-List](xref:Microsoft.PowerShell.Utility.Format-List) -+- [about_Objects](about_Objects.md) +- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md) +- [about_Methods](about_Methods.md) +- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member) +- [Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object) +- [Format-List](xref:Microsoft.PowerShell.Utility.Format-List) |
| learn | Glossary | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/Glossary.md | Title: PowerShell Glossary | host application | A program that loads the PowerShell engine into its process and uses it to perform operations. | | input processing method | A method that a cmdlet can use to process the records it receives as input. The input processing methods include the BeginProcessing method, the ProcessRecord method, the EndProcessing method, and the StopProcessing method. | | manifest module | A PowerShell module that has a manifest and whose RootModule key is empty. |+| member-access enumeration | A PowerShell convenience feature to automatically enumerate items in a collection list object when using the member-access operator (`.`) on the list object. | | module | A self-contained reusable unit that allows you to partition, organize, and abstract your PowerShell code. A module can contain cmdlets, providers, functions, variables, and other types of resources that can be imported as a single unit. | | module manifest | A PowerShell data file (`.psd1`) that describes the contents of a module and that controls how a module is processed. | | module session state | The session state that contains the public and private data of a PowerShell module. The private data in this session state is not available to the user of a PowerShell session. | |
| module | Index | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/module/index.md | ms. ms.product: powershell quickFilterColumn1: powershell-7.1,windowsserver2019-ps-quickFilterColumn2: azps-7.3.0,win-mdop2-ps +quickFilterColumn2: azps-7.3.2,win-mdop2-ps quickFilterColumn3: sqlserver-ps,systemcenter-ps-2019 Title: PowerShell Module Browser --- |