From 49e015edb2c683e8c4a14d73b36bd03b20b686b3 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 24 Mar 2026 08:55:06 -0500 Subject: [PATCH 1/2] Add note about Property wrapping in ForEach() method --- .../About/about_Arrays.md | 43 ++++++++++++++++- .../About/about_Arrays.md | 47 +++++++++++++++++-- .../About/about_Arrays.md | 43 ++++++++++++++++- .../About/about_Arrays.md | 43 ++++++++++++++++- 4 files changed, 169 insertions(+), 7 deletions(-) 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 80eacd4a0ad9..b576de65167b 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,6 +583,47 @@ every item in the collection. Wednesday, June 20, 2018 9:21:57 AM ``` +> [!NOTE] +> The `ForEach()` method wraps properties into a collection before enumeration. +> This wrapping means that accessing the first element of the original +> collection requires two indices `[0][0]`. + +Consider the following example: + +```powershell +$c = [pscustomobject]@{ + Value = @(0..10) +} +$d = [pscustomobject]@{ + Value = @(11..21) +} +``` + +As you can see, both `$c` and `$d` have a property named **Value** that +contains an array of 11 integers. When you use the `ForEach()` method to access +the **Value** property of both objects, the result is a collection of two +arrays. To access the first element of the first array, you need to use two +indices. + +```powershell +PS> ($c, $d).ForEach('Value').Count # 2-element collection +2 +PS> ($c, $d).ForEach('Value')[0].Count # Each is an array with 11 elements +11 +PS> ($c, $d).ForEach('Value')[0][0] # First element of the first array +0 +PS> ($c, $d).ForEach('Value')[1][0] # First element of the second array +11 +``` + +This is different that using the `ForEach()` method using a scriptblock to +access the **Value** property of each object. + +```powershell +PS> ($c, $d).ForEach({$_.Value}).Count # 22-element collection +22 +``` + #### ForEach(string methodName) #### ForEach(string methodName, object[] arguments) 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 1305b9504f2e..af788caa42f2 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,6 +583,47 @@ every item in the collection. Wednesday, June 20, 2018 9:21:57 AM ``` +> [!NOTE] +> The `ForEach()` method wraps properties into a collection before enumeration. +> This wrapping means that accessing the first element of the original +> collection requires two indices `[0][0]`. + +Consider the following example: + +```powershell +$c = [pscustomobject]@{ + Value = @(0..10) +} +$d = [pscustomobject]@{ + Value = @(11..21) +} +``` + +As you can see, both `$c` and `$d` have a property named **Value** that +contains an array of 11 integers. When you use the `ForEach()` method to access +the **Value** property of both objects, the result is a collection of two +arrays. To access the first element of the first array, you need to use two +indices. + +```powershell +PS> ($c, $d).ForEach('Value').Count # 2-element collection +2 +PS> ($c, $d).ForEach('Value')[0].Count # Each is an array with 11 elements +11 +PS> ($c, $d).ForEach('Value')[0][0] # First element of the first array +0 +PS> ($c, $d).ForEach('Value')[1][0] # First element of the second array +11 +``` + +This is different that using the `ForEach()` method using a scriptblock to +access the **Value** property of each object. + +```powershell +PS> ($c, $d).ForEach({$_.Value}).Count # 22-element collection +22 +``` + #### ForEach(string methodName) #### ForEach(string methodName, object[] arguments) @@ -1124,5 +1165,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 baaf33dc56fb..b3b5c20b6efd 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,6 +583,47 @@ every item in the collection. Wednesday, June 20, 2018 9:21:57 AM ``` +> [!NOTE] +> The `ForEach()` method wraps properties into a collection before enumeration. +> This wrapping means that accessing the first element of the original +> collection requires two indices `[0][0]`. + +Consider the following example: + +```powershell +$c = [pscustomobject]@{ + Value = @(0..10) +} +$d = [pscustomobject]@{ + Value = @(11..21) +} +``` + +As you can see, both `$c` and `$d` have a property named **Value** that +contains an array of 11 integers. When you use the `ForEach()` method to access +the **Value** property of both objects, the result is a collection of two +arrays. To access the first element of the first array, you need to use two +indices. + +```powershell +PS> ($c, $d).ForEach('Value').Count # 2-element collection +2 +PS> ($c, $d).ForEach('Value')[0].Count # Each is an array with 11 elements +11 +PS> ($c, $d).ForEach('Value')[0][0] # First element of the first array +0 +PS> ($c, $d).ForEach('Value')[1][0] # First element of the second array +11 +``` + +This is different that using the `ForEach()` method using a scriptblock to +access the **Value** property of each object. + +```powershell +PS> ($c, $d).ForEach({$_.Value}).Count # 22-element collection +22 +``` + #### ForEach(string methodName) #### ForEach(string methodName, object[] arguments) 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 5c76e28654fe..455d85b7f171 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,6 +590,47 @@ every item in the collection. Wednesday, June 20, 2018 9:21:57 AM ``` +> [!NOTE] +> The `ForEach()` method wraps properties into a collection before enumeration. +> This wrapping means that accessing the first element of the original +> collection requires two indices `[0][0]`. + +Consider the following example: + +```powershell +$c = [pscustomobject]@{ + Value = @(0..10) +} +$d = [pscustomobject]@{ + Value = @(11..21) +} +``` + +As you can see, both `$c` and `$d` have a property named **Value** that +contains an array of 11 integers. When you use the `ForEach()` method to access +the **Value** property of both objects, the result is a collection of two +arrays. To access the first element of the first array, you need to use two +indices. + +```powershell +PS> ($c, $d).ForEach('Value').Count # 2-element collection +2 +PS> ($c, $d).ForEach('Value')[0].Count # Each is an array with 11 elements +11 +PS> ($c, $d).ForEach('Value')[0][0] # First element of the first array +0 +PS> ($c, $d).ForEach('Value')[1][0] # First element of the second array +11 +``` + +This is different that using the `ForEach()` method using a scriptblock to +access the **Value** property of each object. + +```powershell +PS> ($c, $d).ForEach({$_.Value}).Count # 22-element collection +22 +``` + #### ForEach(string methodName) #### ForEach(string methodName, object[] arguments) From aa8947c0fb31e1a4f8a834d76cc4752a061a00a1 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 24 Mar 2026 09:41:13 -0500 Subject: [PATCH 2/2] Fix typos and expand description of behavior --- .../About/about_Arrays.md | 62 ++++++++++++------- .../About/about_Arrays.md | 62 ++++++++++++------- .../About/about_Arrays.md | 62 ++++++++++++------- .../About/about_Arrays.md | 62 ++++++++++++------- 4 files changed, 152 insertions(+), 96 deletions(-) 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 b576de65167b..1e678aff659b 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -585,51 +585,65 @@ Wednesday, June 20, 2018 9:21:57 AM > [!NOTE] > The `ForEach()` method wraps properties into a collection before enumeration. -> This wrapping means that accessing the first element of the original -> collection requires two indices `[0][0]`. +> 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: +Consider the following example where the object `$myObject` has a property with +single value and a property containing an array of 11 integers. ```powershell -$c = [pscustomobject]@{ - Value = @(0..10) -} -$d = [pscustomobject]@{ - Value = @(11..21) +$myObject = [pscustomobject]@{ + singleValue = 'Hello' + arrayValue = @(0..10) } ``` -As you can see, both `$c` and `$d` have a property named **Value** that -contains an array of 11 integers. When you use the `ForEach()` method to access -the **Value** property of both objects, the result is a collection of two -arrays. To access the first element of the first array, you need to use two -indices. +When you use the `ForEach()` method to access a property of the object, the +property is wrapped in a collection. ```powershell -PS> ($c, $d).ForEach('Value').Count # 2-element collection -2 -PS> ($c, $d).ForEach('Value')[0].Count # Each is an array with 11 elements +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 -PS> ($c, $d).ForEach('Value')[0][0] # First element of the first array +# Access the first item in the array of 11 items +PS> $myObject.ForEach('Value')[0][0] 0 -PS> ($c, $d).ForEach('Value')[1][0] # First element of the second array -11 ``` -This is different that using the `ForEach()` method using a scriptblock to +This is different than using the `ForEach()` method using with a scriptblock to access the **Value** property of each object. ```powershell -PS> ($c, $d).ForEach({$_.Value}).Count # 22-element collection -22 +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 af788caa42f2..363d553eeef9 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -585,51 +585,65 @@ Wednesday, June 20, 2018 9:21:57 AM > [!NOTE] > The `ForEach()` method wraps properties into a collection before enumeration. -> This wrapping means that accessing the first element of the original -> collection requires two indices `[0][0]`. +> 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: +Consider the following example where the object `$myObject` has a property with +single value and a property containing an array of 11 integers. ```powershell -$c = [pscustomobject]@{ - Value = @(0..10) -} -$d = [pscustomobject]@{ - Value = @(11..21) +$myObject = [pscustomobject]@{ + singleValue = 'Hello' + arrayValue = @(0..10) } ``` -As you can see, both `$c` and `$d` have a property named **Value** that -contains an array of 11 integers. When you use the `ForEach()` method to access -the **Value** property of both objects, the result is a collection of two -arrays. To access the first element of the first array, you need to use two -indices. +When you use the `ForEach()` method to access a property of the object, the +property is wrapped in a collection. ```powershell -PS> ($c, $d).ForEach('Value').Count # 2-element collection -2 -PS> ($c, $d).ForEach('Value')[0].Count # Each is an array with 11 elements +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 -PS> ($c, $d).ForEach('Value')[0][0] # First element of the first array +# Access the first item in the array of 11 items +PS> $myObject.ForEach('Value')[0][0] 0 -PS> ($c, $d).ForEach('Value')[1][0] # First element of the second array -11 ``` -This is different that using the `ForEach()` method using a scriptblock to +This is different than using the `ForEach()` method using with a scriptblock to access the **Value** property of each object. ```powershell -PS> ($c, $d).ForEach({$_.Value}).Count # 22-element collection -22 +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.5/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Arrays.md index b3b5c20b6efd..e8e37855029b 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -585,51 +585,65 @@ Wednesday, June 20, 2018 9:21:57 AM > [!NOTE] > The `ForEach()` method wraps properties into a collection before enumeration. -> This wrapping means that accessing the first element of the original -> collection requires two indices `[0][0]`. +> 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: +Consider the following example where the object `$myObject` has a property with +single value and a property containing an array of 11 integers. ```powershell -$c = [pscustomobject]@{ - Value = @(0..10) -} -$d = [pscustomobject]@{ - Value = @(11..21) +$myObject = [pscustomobject]@{ + singleValue = 'Hello' + arrayValue = @(0..10) } ``` -As you can see, both `$c` and `$d` have a property named **Value** that -contains an array of 11 integers. When you use the `ForEach()` method to access -the **Value** property of both objects, the result is a collection of two -arrays. To access the first element of the first array, you need to use two -indices. +When you use the `ForEach()` method to access a property of the object, the +property is wrapped in a collection. ```powershell -PS> ($c, $d).ForEach('Value').Count # 2-element collection -2 -PS> ($c, $d).ForEach('Value')[0].Count # Each is an array with 11 elements +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 -PS> ($c, $d).ForEach('Value')[0][0] # First element of the first array +# Access the first item in the array of 11 items +PS> $myObject.ForEach('Value')[0][0] 0 -PS> ($c, $d).ForEach('Value')[1][0] # First element of the second array -11 ``` -This is different that using the `ForEach()` method using a scriptblock to +This is different than using the `ForEach()` method using with a scriptblock to access the **Value** property of each object. ```powershell -PS> ($c, $d).ForEach({$_.Value}).Count # 22-element collection -22 +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 455d85b7f171..e03a604f9df9 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -592,51 +592,65 @@ Wednesday, June 20, 2018 9:21:57 AM > [!NOTE] > The `ForEach()` method wraps properties into a collection before enumeration. -> This wrapping means that accessing the first element of the original -> collection requires two indices `[0][0]`. +> 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: +Consider the following example where the object `$myObject` has a property with +single value and a property containing an array of 11 integers. ```powershell -$c = [pscustomobject]@{ - Value = @(0..10) -} -$d = [pscustomobject]@{ - Value = @(11..21) +$myObject = [pscustomobject]@{ + singleValue = 'Hello' + arrayValue = @(0..10) } ``` -As you can see, both `$c` and `$d` have a property named **Value** that -contains an array of 11 integers. When you use the `ForEach()` method to access -the **Value** property of both objects, the result is a collection of two -arrays. To access the first element of the first array, you need to use two -indices. +When you use the `ForEach()` method to access a property of the object, the +property is wrapped in a collection. ```powershell -PS> ($c, $d).ForEach('Value').Count # 2-element collection -2 -PS> ($c, $d).ForEach('Value')[0].Count # Each is an array with 11 elements +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 -PS> ($c, $d).ForEach('Value')[0][0] # First element of the first array +# Access the first item in the array of 11 items +PS> $myObject.ForEach('Value')[0][0] 0 -PS> ($c, $d).ForEach('Value')[1][0] # First element of the second array -11 ``` -This is different that using the `ForEach()` method using a scriptblock to +This is different than using the `ForEach()` method using with a scriptblock to access the **Value** property of each object. ```powershell -PS> ($c, $d).ForEach({$_.Value}).Count # 22-element collection -22 +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")