diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md index 80eacd4a0ad..1e678aff659 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -1,7 +1,7 @@ --- description: Describes arrays, which are data structures designed to store collections of items. Locale: en-US -ms.date: 01/18/2026 +ms.date: 03/24/2026 no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -583,12 +583,67 @@ every item in the collection. Wednesday, June 20, 2018 9:21:57 AM ``` +> [!NOTE] +> The `ForEach()` method wraps properties into a collection before enumeration. +> Using `ForEach()` normally returns all items in both array. However, if you +> want to access elements of the wrapped collection, you need to use two +> indices. + +Consider the following example where the object `$myObject` has a property with +single value and a property containing an array of 11 integers. + +```powershell +$myObject = [pscustomobject]@{ + singleValue = 'Hello' + arrayValue = @(0..10) +} +``` + +When you use the `ForEach()` method to access a property of the object, the +property is wrapped in a collection. + +```powershell +PS> $myObject.ForEach('singleValue').GetType().Name +Collection`1 +PS> $myObject.ForEach('singleValue')[0].GetType().Name +String +PS> $myObject.ForEach('singleValue') # Enumerate the collection object +Hello +``` + +To access the an element of the array, you need to use two indices. + +```powershell +PS> $myObject.ForEach('arrayValue').GetType().Name +Collection`1 +# A single Collection item +PS> $myObject.ForEach('arrayValue').Count +1 +# First item in the collection is an array of 11 items +PS> $myObject.ForEach('Value')[0].Count +11 +# Access the first item in the array of 11 items +PS> $myObject.ForEach('Value')[0][0] +0 +``` + +This is different than using the `ForEach()` method using with a scriptblock to +access the **Value** property of each object. + +```powershell +PS> $myObject.ForEach({$_.Value}).Count # An array of 11 items +11 +``` + +Use the scriptblock syntax to avoid the wrapping behavior when you want to +access complex property types, such as arrays or nested objects. + #### ForEach(string methodName) #### ForEach(string methodName, object[] arguments) -Lastly, `ForEach()` methods can be used to execute a method on every item in -the collection. +You can use the `ForEach()` method to execute an object's method on every item +in the collection. ```powershell ("one", "two", "three").ForEach("ToUpper") diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Arrays.md index 1305b9504f2..363d553eeef 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -1,9 +1,9 @@ --- description: Describes arrays, which are data structures designed to store collections of items. Locale: en-US -ms.date: 01/18/2026 +ms.date: 03/24/2026 no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple] -online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-5.1&WT.mc_id=ps-gethelp +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Arrays --- @@ -583,12 +583,67 @@ every item in the collection. Wednesday, June 20, 2018 9:21:57 AM ``` +> [!NOTE] +> The `ForEach()` method wraps properties into a collection before enumeration. +> Using `ForEach()` normally returns all items in both array. However, if you +> want to access elements of the wrapped collection, you need to use two +> indices. + +Consider the following example where the object `$myObject` has a property with +single value and a property containing an array of 11 integers. + +```powershell +$myObject = [pscustomobject]@{ + singleValue = 'Hello' + arrayValue = @(0..10) +} +``` + +When you use the `ForEach()` method to access a property of the object, the +property is wrapped in a collection. + +```powershell +PS> $myObject.ForEach('singleValue').GetType().Name +Collection`1 +PS> $myObject.ForEach('singleValue')[0].GetType().Name +String +PS> $myObject.ForEach('singleValue') # Enumerate the collection object +Hello +``` + +To access the an element of the array, you need to use two indices. + +```powershell +PS> $myObject.ForEach('arrayValue').GetType().Name +Collection`1 +# A single Collection item +PS> $myObject.ForEach('arrayValue').Count +1 +# First item in the collection is an array of 11 items +PS> $myObject.ForEach('Value')[0].Count +11 +# Access the first item in the array of 11 items +PS> $myObject.ForEach('Value')[0][0] +0 +``` + +This is different than using the `ForEach()` method using with a scriptblock to +access the **Value** property of each object. + +```powershell +PS> $myObject.ForEach({$_.Value}).Count # An array of 11 items +11 +``` + +Use the scriptblock syntax to avoid the wrapping behavior when you want to +access complex property types, such as arrays or nested objects. + #### ForEach(string methodName) #### ForEach(string methodName, object[] arguments) -Lastly, `ForEach()` methods can be used to execute a method on every item in -the collection. +You can use the `ForEach()` method to execute an object's method on every item +in the collection. ```powershell ("one", "two", "three").ForEach("ToUpper") @@ -1124,5 +1179,3 @@ LastWriteTimeUtc Property datetime LastWriteTimeUtc {get;set;} [13]: about_While.md [14]: https://wikipedia.org/wiki/Row-_and_column-major_order - - diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Arrays.md index baaf33dc56f..e8e37855029 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -1,7 +1,7 @@ --- description: Describes arrays, which are data structures designed to store collections of items. Locale: en-US -ms.date: 01/18/2026 +ms.date: 03/24/2026 no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -583,12 +583,67 @@ every item in the collection. Wednesday, June 20, 2018 9:21:57 AM ``` +> [!NOTE] +> The `ForEach()` method wraps properties into a collection before enumeration. +> Using `ForEach()` normally returns all items in both array. However, if you +> want to access elements of the wrapped collection, you need to use two +> indices. + +Consider the following example where the object `$myObject` has a property with +single value and a property containing an array of 11 integers. + +```powershell +$myObject = [pscustomobject]@{ + singleValue = 'Hello' + arrayValue = @(0..10) +} +``` + +When you use the `ForEach()` method to access a property of the object, the +property is wrapped in a collection. + +```powershell +PS> $myObject.ForEach('singleValue').GetType().Name +Collection`1 +PS> $myObject.ForEach('singleValue')[0].GetType().Name +String +PS> $myObject.ForEach('singleValue') # Enumerate the collection object +Hello +``` + +To access the an element of the array, you need to use two indices. + +```powershell +PS> $myObject.ForEach('arrayValue').GetType().Name +Collection`1 +# A single Collection item +PS> $myObject.ForEach('arrayValue').Count +1 +# First item in the collection is an array of 11 items +PS> $myObject.ForEach('Value')[0].Count +11 +# Access the first item in the array of 11 items +PS> $myObject.ForEach('Value')[0][0] +0 +``` + +This is different than using the `ForEach()` method using with a scriptblock to +access the **Value** property of each object. + +```powershell +PS> $myObject.ForEach({$_.Value}).Count # An array of 11 items +11 +``` + +Use the scriptblock syntax to avoid the wrapping behavior when you want to +access complex property types, such as arrays or nested objects. + #### ForEach(string methodName) #### ForEach(string methodName, object[] arguments) -Lastly, `ForEach()` methods can be used to execute a method on every item in -the collection. +You can use the `ForEach()` method to execute an object's method on every item +in the collection. ```powershell ("one", "two", "three").ForEach("ToUpper") diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Arrays.md index 5c76e28654f..e03a604f9df 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -1,7 +1,7 @@ --- description: Describes arrays, which are data structures designed to store collections of items. Locale: en-US -ms.date: 01/18/2026 +ms.date: 03/24/2026 no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -590,12 +590,67 @@ every item in the collection. Wednesday, June 20, 2018 9:21:57 AM ``` +> [!NOTE] +> The `ForEach()` method wraps properties into a collection before enumeration. +> Using `ForEach()` normally returns all items in both array. However, if you +> want to access elements of the wrapped collection, you need to use two +> indices. + +Consider the following example where the object `$myObject` has a property with +single value and a property containing an array of 11 integers. + +```powershell +$myObject = [pscustomobject]@{ + singleValue = 'Hello' + arrayValue = @(0..10) +} +``` + +When you use the `ForEach()` method to access a property of the object, the +property is wrapped in a collection. + +```powershell +PS> $myObject.ForEach('singleValue').GetType().Name +Collection`1 +PS> $myObject.ForEach('singleValue')[0].GetType().Name +String +PS> $myObject.ForEach('singleValue') # Enumerate the collection object +Hello +``` + +To access the an element of the array, you need to use two indices. + +```powershell +PS> $myObject.ForEach('arrayValue').GetType().Name +Collection`1 +# A single Collection item +PS> $myObject.ForEach('arrayValue').Count +1 +# First item in the collection is an array of 11 items +PS> $myObject.ForEach('Value')[0].Count +11 +# Access the first item in the array of 11 items +PS> $myObject.ForEach('Value')[0][0] +0 +``` + +This is different than using the `ForEach()` method using with a scriptblock to +access the **Value** property of each object. + +```powershell +PS> $myObject.ForEach({$_.Value}).Count # An array of 11 items +11 +``` + +Use the scriptblock syntax to avoid the wrapping behavior when you want to +access complex property types, such as arrays or nested objects. + #### ForEach(string methodName) #### ForEach(string methodName, object[] arguments) -Lastly, `ForEach()` methods can be used to execute a method on every item in -the collection. +You can use the `ForEach()` method to execute an object's method on every item +in the collection. ```powershell ("one", "two", "three").ForEach("ToUpper")