Fixes #12879 - Add note about Property wrapping in ForEach() method (#12882)

* Add note  about Property wrapping in ForEach() method

* Fix typos and expand description of behavior

Author: sdwheeler

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")

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
 
-
-

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")

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")