From 2a19cbf0612d4b2df89221bf097dec225fa8c35c Mon Sep 17 00:00:00 2001 From: surfingoldelephant <151538956+surfingoldelephant@users.noreply.github.com> Date: Sun, 13 Apr 2025 18:56:10 +0100 Subject: [PATCH] Update `ForEach-Object` example 17 to reflect current behavior (#11997) * Update ForEach-Object -Parallel example 17 In PS v7.2, ForEach-Object -Parallel was updated to support variable access in nested script block scenarios. Example 17 in the docs currently reflects the erroneous behavior exhibited in v7.1 and prior. This change updates the example to reflect the fixed behavior in v7.2. See PS issue #11817 for more information. * Fix schema violation --------- Co-authored-by: Sean Wheeler --- .../ForEach-Object.md | 39 +++++++------------ .../ForEach-Object.md | 39 +++++++------------ .../ForEach-Object.md | 39 +++++++------------ 3 files changed, 45 insertions(+), 72 deletions(-) diff --git a/reference/7.4/Microsoft.PowerShell.Core/ForEach-Object.md b/reference/7.4/Microsoft.PowerShell.Core/ForEach-Object.md index 4a1202ae5163..b8df403dd280 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/ForEach-Object.md +++ b/reference/7.4/Microsoft.PowerShell.Core/ForEach-Object.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 04/26/2024 +ms.date: 04/13/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/foreach-object?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: ForEach-Object @@ -455,27 +455,15 @@ Output: 5 > [PipelineVariable](About/about_CommonParameters.md) common parameter variables are _not_ > supported in `ForEach-Object -Parallel` scenarios even with the `Using:` scope modifier. -### Example 17: Passing variables in nested parallel script ScriptBlockSet +### Example 17: Passing variables in nested parallel scriptblocks -You can create a variable outside a `ForEach-Object -Parallel` scoped scriptblock and use -it inside the scriptblock with the `Using:` scope modifier. +You can create a variable outside a `ForEach-Object -Parallel` scoped scriptblock and use it inside +the scriptblock with the `Using:` scope modifier. Beginning in PowerShell 7.2, you can create a +variable inside a `ForEach-Object -Parallel` scoped scriptblock and use it inside a nested +scriptblock. ```powershell $test1 = 'TestA' -1..2 | ForEach-Object -Parallel { - $Using:test1 -} -``` - -```Output -TestA -TestA -``` - -```powershell -# You CANNOT create a variable inside a scoped scriptblock -# to be used in a nested foreach parallel scriptblock. -$test1 = 'TestA' 1..2 | ForEach-Object -Parallel { $Using:test1 $test2 = 'TestB' @@ -486,14 +474,17 @@ $test1 = 'TestA' ``` ```Output -Line | - 2 | 1..2 | ForEach-Object -Parallel { - | ~~~~~~~~~~~~~~~~~~~~~~~~~~ - | The value of the using variable '$Using:test2' can't be retrieved because it has - | not been set in the local session. +TestA +TestA +TestB +TestB +TestB +TestB ``` -The nested scriptblock can't access the `$test2` variable and an error is thrown. +> [!NOTE] +> In versions prior to PowerShell 7.2, the nested scriptblock can't access the `$test2` variable and +> an error is thrown. ### Example 18: Creating multiple jobs that run scripts in parallel diff --git a/reference/7.5/Microsoft.PowerShell.Core/ForEach-Object.md b/reference/7.5/Microsoft.PowerShell.Core/ForEach-Object.md index c996dd80d7f8..5eda12fd016b 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/ForEach-Object.md +++ b/reference/7.5/Microsoft.PowerShell.Core/ForEach-Object.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 04/26/2024 +ms.date: 04/13/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/foreach-object?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: ForEach-Object @@ -455,27 +455,15 @@ Output: 5 > [PipelineVariable](About/about_CommonParameters.md) common parameter variables are _not_ > supported in `ForEach-Object -Parallel` scenarios even with the `Using:` scope modifier. -### Example 17: Passing variables in nested parallel script ScriptBlockSet +### Example 17: Passing variables in nested parallel scriptblocks -You can create a variable outside a `ForEach-Object -Parallel` scoped scriptblock and use -it inside the scriptblock with the `Using:` scope modifier. +You can create a variable outside a `ForEach-Object -Parallel` scoped scriptblock and use it inside +the scriptblock with the `Using:` scope modifier. Beginning in PowerShell 7.2, you can create a +variable inside a `ForEach-Object -Parallel` scoped scriptblock and use it inside a nested +scriptblock. ```powershell $test1 = 'TestA' -1..2 | ForEach-Object -Parallel { - $Using:test1 -} -``` - -```Output -TestA -TestA -``` - -```powershell -# You CANNOT create a variable inside a scoped scriptblock -# to be used in a nested foreach parallel scriptblock. -$test1 = 'TestA' 1..2 | ForEach-Object -Parallel { $Using:test1 $test2 = 'TestB' @@ -486,14 +474,17 @@ $test1 = 'TestA' ``` ```Output -Line | - 2 | 1..2 | ForEach-Object -Parallel { - | ~~~~~~~~~~~~~~~~~~~~~~~~~~ - | The value of the using variable '$Using:test2' can't be retrieved because it has - | not been set in the local session. +TestA +TestA +TestB +TestB +TestB +TestB ``` -The nested scriptblock can't access the `$test2` variable and an error is thrown. +> [!NOTE] +> In versions prior to PowerShell 7.2, the nested scriptblock can't access the `$test2` variable and +> an error is thrown. ### Example 18: Creating multiple jobs that run scripts in parallel diff --git a/reference/7.6/Microsoft.PowerShell.Core/ForEach-Object.md b/reference/7.6/Microsoft.PowerShell.Core/ForEach-Object.md index 79a6c6e71d98..f07ed6c6555e 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/ForEach-Object.md +++ b/reference/7.6/Microsoft.PowerShell.Core/ForEach-Object.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 04/26/2024 +ms.date: 04/13/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/foreach-object?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: ForEach-Object @@ -455,27 +455,15 @@ Output: 5 > [PipelineVariable](About/about_CommonParameters.md) common parameter variables are _not_ > supported in `ForEach-Object -Parallel` scenarios even with the `Using:` scope modifier. -### Example 17: Passing variables in nested parallel script ScriptBlockSet +### Example 17: Passing variables in nested parallel scriptblocks -You can create a variable outside a `ForEach-Object -Parallel` scoped scriptblock and use -it inside the scriptblock with the `Using:` scope modifier. +You can create a variable outside a `ForEach-Object -Parallel` scoped scriptblock and use it inside +the scriptblock with the `Using:` scope modifier. Beginning in PowerShell 7.2, you can create a +variable inside a `ForEach-Object -Parallel` scoped scriptblock and use it inside a nested +scriptblock. ```powershell $test1 = 'TestA' -1..2 | ForEach-Object -Parallel { - $Using:test1 -} -``` - -```Output -TestA -TestA -``` - -```powershell -# You CANNOT create a variable inside a scoped scriptblock -# to be used in a nested foreach parallel scriptblock. -$test1 = 'TestA' 1..2 | ForEach-Object -Parallel { $Using:test1 $test2 = 'TestB' @@ -486,14 +474,17 @@ $test1 = 'TestA' ``` ```Output -Line | - 2 | 1..2 | ForEach-Object -Parallel { - | ~~~~~~~~~~~~~~~~~~~~~~~~~~ - | The value of the using variable '$Using:test2' can't be retrieved because it has - | not been set in the local session. +TestA +TestA +TestB +TestB +TestB +TestB ``` -The nested scriptblock can't access the `$test2` variable and an error is thrown. +> [!NOTE] +> In versions prior to PowerShell 7.2, the nested scriptblock can't access the `$test2` variable and +> an error is thrown. ### Example 18: Creating multiple jobs that run scripts in parallel