diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md index ee9f96ee06ef..6351bd9161c7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,7 +1,7 @@ --- description: Describes the parameters that can be used with any cmdlet. Locale: en-US -ms.date: 07/02/2024 +ms.date: 04/24/2025 no-loc: [Debug, Verbose, Confirm] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_commonparameters?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -471,6 +471,64 @@ At line:1 char:1 + FullyQualifiedErrorId : VariableNotFound,Microsoft.PowerShell.Commands.GetVariableCommand ``` +> [!CAUTION] +> There are two known issues with using the **PipelineVariable** parameter in a +> pipeline that includes CimCmdlets or CDXML cmdlets. In the following +> examples, `Get-Partition` is a CDXML function and `Get-CimInstance` is a +> CimCmdlet. + +1. CDXML functions use `[CmdletBinding()]`, which allows the + **PipelineVariable** parameter. + + ```powershell + Get-Partition -pv pvar + ``` + + However, when you use **PipelineVariable** in Windows PowerShell v5.1, you + receive the following error. + + ```Output + Get-Partition : Cannot retrieve the dynamic parameters for the cmdlet. + Object reference not set to an instance of an object. + + At line:1 char:1 + + get-partition -PipelineVariable pvar + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + CategoryInfo : InvalidArgument: (:) [Get-Partition], ParameterBindingException + + FullyQualifiedErrorId : GetDynamicParametersException,Get-Partition + ``` + +1. When the preceding command is _not_ a CDXML command and the downstream + contains either command type, the **PipelineVariable** remains as the last + accumulated object. + + ```powershell + Get-CimInstance Win32_DiskDrive -pv pvar | + ForEach-Object { + Write-Host "Before: $($pvar.Index)" + [pscustomobject]@{ DiskNumber = $_.Index } + } | + Get-Partition | + ForEach-Object { + Write-Host "After: $($pvar.Index)" + } + ``` + + Notice that the value of `$pvar` set to the last object in the pipeline for + the second `ForEach-Object` command. + + ```Output + Before: 1 + Before: 2 + Before: 0 + After: 0 + After: 0 + After: 0 + After: 0 + After: 0 + After: 0 + ``` + ### -ProgressAction Determines how PowerShell responds to progress updates generated by a script, diff --git a/reference/5.1/Microsoft.PowerShell.Core/ForEach-Object.md b/reference/5.1/Microsoft.PowerShell.Core/ForEach-Object.md index 2f302762ca56..5382c04d609a 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/ForEach-Object.md +++ b/reference/5.1/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/23/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/foreach-object?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: ForEach-Object @@ -36,7 +36,7 @@ input objects can be piped to the cmdlet or specified using the **InputObject** Starting in Windows PowerShell 3.0, there are two different ways to construct a `ForEach-Object` command. -- **Script block**. You can use a script block to specify the operation. Within the script block, +- **Script block syntax**. You can use a script block to specify the operation. Within the script block, use the `$_` variable to represent the current object. The script block is the value of the **Process** parameter. The script block can contain any PowerShell script. @@ -52,15 +52,18 @@ command. > The script blocks run in the caller's scope. Therefore, the blocks have access to variables in > that scope and can create new variables that persist in that scope after the cmdlet completes. -- **Operation statement**. You can also write an operation statement, which is much more like - natural language. You can use the operation statement to specify a property value or call a - method. Operation statements were introduced in Windows PowerShell 3.0. +- **Simplified syntax**. Using the simplified syntax, you specify a property or method name of the + object in the pipeline. `ForEach-Object` returns the value of the property or method for each + object in the pipeline. For example, the following command also gets the value of the **ProcessName** property of each process on the computer. `Get-Process | ForEach-Object ProcessName` + The simplified syntax was introduced in Windows PowerShell 3.0. For more information, see + [about_Simplified_Syntax](About/about_Simplified_Syntax.md). + ## EXAMPLES ### Example 1: Divide integers in an array @@ -82,8 +85,9 @@ This example takes an array of three integers and divides each one of them by 10 This example processes the files and directories in the PowerShell installation directory `$PSHOME`. ```powershell -Get-ChildItem $PSHOME | - ForEach-Object -Process {if (!$_.PSIsContainer) {$_.Name; $_.Length / 1024; " " }} +Get-ChildItem $PSHOME | ForEach-Object -Process { + if (!$_.PSIsContainer) {$_.Name; $_.Length / 1024; " " } +} ``` If the object isn't a directory, the script block gets the name of the file, divides the value of diff --git a/reference/5.1/Microsoft.PowerShell.Core/Where-Object.md b/reference/5.1/Microsoft.PowerShell.Core/Where-Object.md index 35ce5bc2884c..bc02ad8a736a 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Where-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/23/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/where-object?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Where-Object @@ -241,32 +241,38 @@ particular version of Windows. Starting in Windows PowerShell 3.0, there are two different ways to construct a `Where-Object` command. -- **Script block**. You can use a script block to specify the property name, a comparison operator, +- **Script block syntax**. You can use a script block to specify the property name, a comparison operator, and a property value. `Where-Object` returns all objects for which the script block statement is true. - For example, the following command gets processes in the `Normal` priority class, that is, - processes where the value of the **PriorityClass** property equals `Normal`. + For example, the following command gets processes where the value of the **PriorityClass** + property equals `Normal`. `Get-Process | Where-Object {$_.PriorityClass -eq "Normal"}` All PowerShell comparison operators are valid in the script block format. For more information, see [about_Comparison_Operators](./About/about_Comparison_Operators.md). -- **Comparison statement**. You can also write a comparison statement, which is much more like - natural language. Comparison statements were introduced in Windows PowerShell 3.0. +- **Simplified syntax**. To enable the simiplified syntax, `Where-Object` includes 31 switch + parameters that represent the comparison operators. The simplified syntax is easier to read and + write than the script block syntax. You can combine one of the switch parameters with the + **Property** and **Value** parameters to create a command that filters objects based on the + values of their properties. For example, the following commands also get processes that have a priority class of `Normal`. These commands are equivalent and you can use them interchangeably. - `Get-Process | Where-Object -Property PriorityClass -EQ -Value "Normal"` + `Get-Process | Where-Object -Property PriorityClass -Value Normal -EQ` - `Get-Process | Where-Object PriorityClass -EQ "Normal"` + `Get-Process | Where-Object PriorityClass -EQ Normal` - Starting in Windows PowerShell 3.0, `Where-Object` adds comparison operators as parameters in a - `Where-Object` command. Unless specified, all operators are case-insensitive. Before Windows - PowerShell 3.0, the comparison operators in the PowerShell language were only usable in script - blocks. + As shown in the example, the parameter names **Property** and **Value** are optional. The + **Property** parameter is a positional parameter mapped to position `0`. The **Value** parameter + is a positional parameter mapped to position `1`. The switch parameter, used to specify the + comparison, can be used in any position. + + The simplfied syntax was introduced in Windows PowerShell 3.0. For more information, see + [about_Simplified_Syntax](About/about_Simplified_Syntax.md). When you provide a single **Property** to `Where-Object`, the cmdlet treats the value of the property as a boolean expression. When the value of the property's **Length** isn't zero, the @@ -1181,4 +1187,4 @@ You can read more about these methods here [about_Arrays](./About/about_Arrays.m [Tee-Object](../Microsoft.PowerShell.Utility/Tee-Object.md) -[about_Booleans](about/about_Booleans.md) +[about_Booleans](./About/about_Booleans.md) diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_CommonParameters.md index 44f74191abca..806155e57eb4 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,7 +1,7 @@ --- description: Describes the parameters that can be used with any cmdlet. Locale: en-US -ms.date: 07/02/2024 +ms.date: 04/24/2025 no-loc: [Debug, Verbose, Confirm] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_commonparameters?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -459,6 +459,77 @@ Name Value temp ``` +> [!CAUTION] +> There are two known issues with using the **PipelineVariable** parameter in a +> pipeline that includes CimCmdlets or CDXML cmdlets. In the following +> examples, `Get-Partition` is a CDXML function and `Get-CimInstance` is a +> CimCmdlet. + +1. When the first command is a CDXML function and downstream contains either a + CimCmdlet cmdlet or CDXML function, **PipelineVariable** is reset to + `$null`. + + ```powershell + Get-Partition -pv pvar | + ForEach-Object { + Write-Host "Before: $($pvar.PartitionNumber)" + [pscustomobject]@{Filter = "Index = $($_.DiskNumber)"} + } | + Get-CimInstance Win32_DiskDrive | + ForEach-Object { + Write-Host "After: $($pvar.PartitionNumber)" + } + ``` + + Notice that the value of `$pvar` set to `$null` in the pipeline for the + second `ForEach-Object` command. + + ```Output + Before: 1 + Before: 1 + Before: 2 + Before: 3 + Before: 4 + Before: 1 + After: + After: + After: + After: + After: + After: + ``` + +1. When the preceding command is _not_ a CDXML command and the downstream + contains either command type, the **PipelineVariable** remains as the last + accumulated object. + + ```powershell + Get-CimInstance Win32_DiskDrive -pv pvar | + ForEach-Object { + Write-Host "Before: $($pvar.Index)" + [pscustomobject]@{ DiskNumber = $_.Index } + } | + Get-Partition | + ForEach-Object { + Write-Host "After: $($pvar.Index)" + } + ``` + + Notice that the value of `$pvar` set to the last object in the pipeline for + the second `ForEach-Object` command. + + ```Output + Before: 1 + Before: 2 + Before: 0 + After: 0 + After: 0 + After: 0 + After: 0 + After: 0 + After: 0 + ``` + ### -ProgressAction Determines how PowerShell responds to progress updates generated by a script, diff --git a/reference/7.4/Microsoft.PowerShell.Core/ForEach-Object.md b/reference/7.4/Microsoft.PowerShell.Core/ForEach-Object.md index b8df403dd280..6bce11d0ce56 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/13/2025 +ms.date: 04/23/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 @@ -45,7 +45,7 @@ input objects can be piped to the cmdlet or specified using the **InputObject** Starting in Windows PowerShell 3.0, there are two different ways to construct a `ForEach-Object` command. -- **Script block**. You can use a script block to specify the operation. Within the script block, +- **Script block syntax**. You can use a script block to specify the operation. Within the script block, use the `$_` variable to represent the current object. The script block is the value of the **Process** parameter. The script block can contain any PowerShell script. @@ -61,15 +61,18 @@ command. > The script blocks run in the caller's scope. Therefore, the blocks have access to variables in > that scope and can create new variables that persist in that scope after the cmdlet completes. -- **Operation statement**. You can also write an operation statement, which is much more like - natural language. You can use the operation statement to specify a property value or call a - method. Operation statements were introduced in Windows PowerShell 3.0. +- **Simplified syntax**. Using the simplified syntax, you specify a property or method name of the + object in the pipeline. `ForEach-Object` returns the value of the property or method for each + object in the pipeline. For example, the following command also gets the value of the **ProcessName** property of each process on the computer. `Get-Process | ForEach-Object ProcessName` + The simplified syntax was introduced in Windows PowerShell 3.0. For more information, see + [about_Simplified_Syntax](About/about_Simplified_Syntax.md). + - **Parallel running script block**. Beginning with PowerShell 7.0, a third parameter set is available that runs each script block in parallel. The **ThrottleLimit** parameter limits the number of parallel scripts running at a time. As before, use the `$_` variable to represent the @@ -109,8 +112,9 @@ This example takes an array of three integers and divides each one of them by 10 This example processes the files and directories in the PowerShell installation directory `$PSHOME`. ```powershell -Get-ChildItem $PSHOME | - ForEach-Object -Process {if (!$_.PSIsContainer) {$_.Name; $_.Length / 1024; " " }} +Get-ChildItem $PSHOME | ForEach-Object -Process { + if (!$_.PSIsContainer) {$_.Name; $_.Length / 1024; " " } +} ``` If the object isn't a directory, the script block gets the name of the file, divides the value of diff --git a/reference/7.4/Microsoft.PowerShell.Core/Where-Object.md b/reference/7.4/Microsoft.PowerShell.Core/Where-Object.md index de3d34975f8c..c8ec9da98b2a 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/7.4/Microsoft.PowerShell.Core/Where-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/23/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/where-object?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Where-Object @@ -248,32 +248,38 @@ particular version of Windows. Starting in Windows PowerShell 3.0, there are two different ways to construct a `Where-Object` command. -- **Script block**. You can use a script block to specify the property name, a comparison operator, +- **Script block syntax**. You can use a script block to specify the property name, a comparison operator, and a property value. `Where-Object` returns all objects for which the script block statement is true. - For example, the following command gets processes in the `Normal` priority class, that is, - processes where the value of the **PriorityClass** property equals `Normal`. + For example, the following command gets processes where the value of the **PriorityClass** + property equals `Normal`. `Get-Process | Where-Object {$_.PriorityClass -eq "Normal"}` All PowerShell comparison operators are valid in the script block format. For more information, see [about_Comparison_Operators](./About/about_Comparison_Operators.md). -- **Comparison statement**. You can also write a comparison statement, which is much more like - natural language. Comparison statements were introduced in Windows PowerShell 3.0. +- **Simplified syntax**. To enable the simiplified syntax, `Where-Object` includes 31 switch + parameters that represent the comparison operators. The simplified syntax is easier to read and + write than the script block syntax. You can combine one of the switch parameters with the + **Property** and **Value** parameters to create a command that filters objects based on the + values of their properties. For example, the following commands also get processes that have a priority class of `Normal`. These commands are equivalent and you can use them interchangeably. - `Get-Process | Where-Object -Property PriorityClass -EQ -Value "Normal"` + `Get-Process | Where-Object -Property PriorityClass -Value Normal -EQ` - `Get-Process | Where-Object PriorityClass -EQ "Normal"` + `Get-Process | Where-Object PriorityClass -EQ Normal` - Starting in Windows PowerShell 3.0, `Where-Object` adds comparison operators as parameters in a - `Where-Object` command. Unless specified, all operators are case-insensitive. Before Windows - PowerShell 3.0, the comparison operators in the PowerShell language were only usable in script - blocks. + As shown in the example, the parameter names **Property** and **Value** are optional. The + **Property** parameter is a positional parameter mapped to position `0`. The **Value** parameter + is a positional parameter mapped to position `1`. The switch parameter, used to specify the + comparison, can be used in any position. + + The simplfied syntax was introduced in Windows PowerShell 3.0. For more information, see + [about_Simplified_Syntax](About/about_Simplified_Syntax.md). When you provide a single **Property** to `Where-Object`, the cmdlet treats the value of the property as a boolean expression. When the value of the property's **Length** isn't zero, the @@ -1208,4 +1214,4 @@ You can read more about these methods here [about_Arrays](./About/about_Arrays.m [Tee-Object](../Microsoft.PowerShell.Utility/Tee-Object.md) -[about_Booleans](about/about_Booleans.md) +[about_Booleans](./About/about_Booleans.md) diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_CommonParameters.md index 4773de4f922a..4ed3b86ce476 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,7 +1,7 @@ --- description: Describes the parameters that can be used with any cmdlet. Locale: en-US -ms.date: 07/02/2024 +ms.date: 04/24/2025 no-loc: [Debug, Verbose, Confirm] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_commonparameters?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -459,6 +459,77 @@ Name Value temp ``` +> [!CAUTION] +> There are two known issues with using the **PipelineVariable** parameter in a +> pipeline that includes CimCmdlets or CDXML cmdlets. In the following +> examples, `Get-Partition` is a CDXML function and `Get-CimInstance` is a +> CimCmdlet. + +1. When the first command is a CDXML function and downstream contains either a + CimCmdlet cmdlet or CDXML function, **PipelineVariable** is reset to + `$null`. + + ```powershell + Get-Partition -pv pvar | + ForEach-Object { + Write-Host "Before: $($pvar.PartitionNumber)" + [pscustomobject]@{Filter = "Index = $($_.DiskNumber)"} + } | + Get-CimInstance Win32_DiskDrive | + ForEach-Object { + Write-Host "After: $($pvar.PartitionNumber)" + } + ``` + + Notice that the value of `$pvar` set to `$null` in the pipeline for the + second `ForEach-Object` command. + + ```Output + Before: 1 + Before: 1 + Before: 2 + Before: 3 + Before: 4 + Before: 1 + After: + After: + After: + After: + After: + After: + ``` + +1. When the preceding command is _not_ a CDXML command and the downstream + contains either command type, the **PipelineVariable** remains as the last + accumulated object. + + ```powershell + Get-CimInstance Win32_DiskDrive -pv pvar | + ForEach-Object { + Write-Host "Before: $($pvar.Index)" + [pscustomobject]@{ DiskNumber = $_.Index } + } | + Get-Partition | + ForEach-Object { + Write-Host "After: $($pvar.Index)" + } + ``` + + Notice that the value of `$pvar` set to the last object in the pipeline for + the second `ForEach-Object` command. + + ```Output + Before: 1 + Before: 2 + Before: 0 + After: 0 + After: 0 + After: 0 + After: 0 + After: 0 + After: 0 + ``` + ### -ProgressAction Determines how PowerShell responds to progress updates generated by a script, diff --git a/reference/7.5/Microsoft.PowerShell.Core/ForEach-Object.md b/reference/7.5/Microsoft.PowerShell.Core/ForEach-Object.md index 5eda12fd016b..a1f22f73ff90 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/13/2025 +ms.date: 04/23/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 @@ -45,7 +45,7 @@ input objects can be piped to the cmdlet or specified using the **InputObject** Starting in Windows PowerShell 3.0, there are two different ways to construct a `ForEach-Object` command. -- **Script block**. You can use a script block to specify the operation. Within the script block, +- **Script block syntax**. You can use a script block to specify the operation. Within the script block, use the `$_` variable to represent the current object. The script block is the value of the **Process** parameter. The script block can contain any PowerShell script. @@ -61,15 +61,18 @@ command. > The script blocks run in the caller's scope. Therefore, the blocks have access to variables in > that scope and can create new variables that persist in that scope after the cmdlet completes. -- **Operation statement**. You can also write an operation statement, which is much more like - natural language. You can use the operation statement to specify a property value or call a - method. Operation statements were introduced in Windows PowerShell 3.0. +- **Simplified syntax**. Using the simplified syntax, you specify a property or method name of the + object in the pipeline. `ForEach-Object` returns the value of the property or method for each + object in the pipeline. For example, the following command also gets the value of the **ProcessName** property of each process on the computer. `Get-Process | ForEach-Object ProcessName` + The simplified syntax was introduced in Windows PowerShell 3.0. For more information, see + [about_Simplified_Syntax](About/about_Simplified_Syntax.md). + - **Parallel running script block**. Beginning with PowerShell 7.0, a third parameter set is available that runs each script block in parallel. The **ThrottleLimit** parameter limits the number of parallel scripts running at a time. As before, use the `$_` variable to represent the @@ -109,8 +112,9 @@ This example takes an array of three integers and divides each one of them by 10 This example processes the files and directories in the PowerShell installation directory `$PSHOME`. ```powershell -Get-ChildItem $PSHOME | - ForEach-Object -Process {if (!$_.PSIsContainer) {$_.Name; $_.Length / 1024; " " }} +Get-ChildItem $PSHOME | ForEach-Object -Process { + if (!$_.PSIsContainer) {$_.Name; $_.Length / 1024; " " } +} ``` If the object isn't a directory, the script block gets the name of the file, divides the value of diff --git a/reference/7.5/Microsoft.PowerShell.Core/Where-Object.md b/reference/7.5/Microsoft.PowerShell.Core/Where-Object.md index ba65a734b356..80154c9422fa 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Where-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/23/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/where-object?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: Where-Object @@ -248,32 +248,38 @@ particular version of Windows. Starting in Windows PowerShell 3.0, there are two different ways to construct a `Where-Object` command. -- **Script block**. You can use a script block to specify the property name, a comparison operator, +- **Script block syntax**. You can use a script block to specify the property name, a comparison operator, and a property value. `Where-Object` returns all objects for which the script block statement is true. - For example, the following command gets processes in the `Normal` priority class, that is, - processes where the value of the **PriorityClass** property equals `Normal`. + For example, the following command gets processes where the value of the **PriorityClass** + property equals `Normal`. `Get-Process | Where-Object {$_.PriorityClass -eq "Normal"}` All PowerShell comparison operators are valid in the script block format. For more information, - see [about_Comparison_Operators](About/about_Comparison_Operators.md). + see [about_Comparison_Operators](./About/about_Comparison_Operators.md). -- **Comparison statement**. You can also write a comparison statement, which is much more like - natural language. Comparison statements were introduced in Windows PowerShell 3.0. +- **Simplified syntax**. To enable the simiplified syntax, `Where-Object` includes 31 switch + parameters that represent the comparison operators. The simplified syntax is easier to read and + write than the script block syntax. You can combine one of the switch parameters with the + **Property** and **Value** parameters to create a command that filters objects based on the + values of their properties. For example, the following commands also get processes that have a priority class of `Normal`. These commands are equivalent and you can use them interchangeably. - `Get-Process | Where-Object -Property PriorityClass -EQ -Value "Normal"` + `Get-Process | Where-Object -Property PriorityClass -Value Normal -EQ` - `Get-Process | Where-Object PriorityClass -EQ "Normal"` + `Get-Process | Where-Object PriorityClass -EQ Normal` - Starting in Windows PowerShell 3.0, `Where-Object` adds comparison operators as parameters in a - `Where-Object` command. Unless specified, all operators are case-insensitive. Before Windows - PowerShell 3.0, the comparison operators in the PowerShell language were only usable in script - blocks. + As shown in the example, the parameter names **Property** and **Value** are optional. The + **Property** parameter is a positional parameter mapped to position `0`. The **Value** parameter + is a positional parameter mapped to position `1`. The switch parameter, used to specify the + comparison, can be used in any position. + + The simplfied syntax was introduced in Windows PowerShell 3.0. For more information, see + [about_Simplified_Syntax](About/about_Simplified_Syntax.md). When you provide a single **Property** to `Where-Object`, the cmdlet treats the value of the property as a boolean expression. When the value of the property's **Length** isn't zero, the @@ -285,7 +291,7 @@ The previous example is functionally equivalent to: - `('hi', '', 'there') | Where-Object { $_.Length -gt 0 }` For more information about how PowerShell evaluates booleans, see -[about_Booleans](About/about_Booleans.md). +[about_Booleans](about/about_Booleans.md). ## EXAMPLES @@ -400,9 +406,9 @@ The example uses the script block command format. Logical operators, such as `-a `Where-Object` command. - For more information about PowerShell logical operators, see - [about_Logical_Operators](About/about_Logical_Operators.md). + [about_Logical_Operators](./About/about_logical_operators.md). - For more information about the Updatable Help feature, see - [about_Updatable_Help](About/about_Updatable_Help.md). + [about_Updatable_Help](./About/about_Updatable_Help.md). ## PARAMETERS @@ -1188,7 +1194,7 @@ PowerShell includes the following aliases for `Where-Object`: Starting in Windows PowerShell 4.0, `Where` and `ForEach` methods were added for use with collections. -You can read more about these methods here [about_Arrays](About/about_Arrays.md) +You can read more about these methods here [about_Arrays](./About/about_Arrays.md) ## RELATED LINKS @@ -1208,4 +1214,4 @@ You can read more about these methods here [about_Arrays](About/about_Arrays.md) [Tee-Object](../Microsoft.PowerShell.Utility/Tee-Object.md) -[about_Booleans](About/about_Booleans.md) +[about_Booleans](./About/about_Booleans.md) diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_CommonParameters.md index 2d3bc126c259..60fd5c1eb272 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,7 +1,7 @@ --- description: Describes the parameters that can be used with any cmdlet. Locale: en-US -ms.date: 07/02/2024 +ms.date: 04/24/2025 no-loc: [Debug, Verbose, Confirm] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_commonparameters?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -459,6 +459,77 @@ Name Value temp ``` +> [!CAUTION] +> There are two known issues with using the **PipelineVariable** parameter in a +> pipeline that includes CimCmdlets or CDXML cmdlets. In the following +> examples, `Get-Partition` is a CDXML function and `Get-CimInstance` is a +> CimCmdlet. + +1. When the first command is a CDXML function and downstream contains either a + CimCmdlet cmdlet or CDXML function, **PipelineVariable** is reset to + `$null`. + + ```powershell + Get-Partition -pv pvar | + ForEach-Object { + Write-Host "Before: $($pvar.PartitionNumber)" + [pscustomobject]@{Filter = "Index = $($_.DiskNumber)"} + } | + Get-CimInstance Win32_DiskDrive | + ForEach-Object { + Write-Host "After: $($pvar.PartitionNumber)" + } + ``` + + Notice that the value of `$pvar` set to `$null` in the pipeline for the + second `ForEach-Object` command. + + ```Output + Before: 1 + Before: 1 + Before: 2 + Before: 3 + Before: 4 + Before: 1 + After: + After: + After: + After: + After: + After: + ``` + +1. When the preceding command is _not_ a CDXML command and the downstream + contains either command type, the **PipelineVariable** remains as the last + accumulated object. + + ```powershell + Get-CimInstance Win32_DiskDrive -pv pvar | + ForEach-Object { + Write-Host "Before: $($pvar.Index)" + [pscustomobject]@{ DiskNumber = $_.Index } + } | + Get-Partition | + ForEach-Object { + Write-Host "After: $($pvar.Index)" + } + ``` + + Notice that the value of `$pvar` set to the last object in the pipeline for + the second `ForEach-Object` command. + + ```Output + Before: 1 + Before: 2 + Before: 0 + After: 0 + After: 0 + After: 0 + After: 0 + After: 0 + After: 0 + ``` + ### -ProgressAction Determines how PowerShell responds to progress updates generated by a script, diff --git a/reference/7.6/Microsoft.PowerShell.Core/ForEach-Object.md b/reference/7.6/Microsoft.PowerShell.Core/ForEach-Object.md index f07ed6c6555e..31718d347c8e 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/13/2025 +ms.date: 04/23/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 @@ -45,7 +45,7 @@ input objects can be piped to the cmdlet or specified using the **InputObject** Starting in Windows PowerShell 3.0, there are two different ways to construct a `ForEach-Object` command. -- **Script block**. You can use a script block to specify the operation. Within the script block, +- **Script block syntax**. You can use a script block to specify the operation. Within the script block, use the `$_` variable to represent the current object. The script block is the value of the **Process** parameter. The script block can contain any PowerShell script. @@ -61,15 +61,18 @@ command. > The script blocks run in the caller's scope. Therefore, the blocks have access to variables in > that scope and can create new variables that persist in that scope after the cmdlet completes. -- **Operation statement**. You can also write an operation statement, which is much more like - natural language. You can use the operation statement to specify a property value or call a - method. Operation statements were introduced in Windows PowerShell 3.0. +- **Simplified syntax**. Using the simplified syntax, you specify a property or method name of the + object in the pipeline. `ForEach-Object` returns the value of the property or method for each + object in the pipeline. For example, the following command also gets the value of the **ProcessName** property of each process on the computer. `Get-Process | ForEach-Object ProcessName` + The simplified syntax was introduced in Windows PowerShell 3.0. For more information, see + [about_Simplified_Syntax](About/about_Simplified_Syntax.md). + - **Parallel running script block**. Beginning with PowerShell 7.0, a third parameter set is available that runs each script block in parallel. The **ThrottleLimit** parameter limits the number of parallel scripts running at a time. As before, use the `$_` variable to represent the @@ -109,8 +112,9 @@ This example takes an array of three integers and divides each one of them by 10 This example processes the files and directories in the PowerShell installation directory `$PSHOME`. ```powershell -Get-ChildItem $PSHOME | - ForEach-Object -Process {if (!$_.PSIsContainer) {$_.Name; $_.Length / 1024; " " }} +Get-ChildItem $PSHOME | ForEach-Object -Process { + if (!$_.PSIsContainer) {$_.Name; $_.Length / 1024; " " } +} ``` If the object isn't a directory, the script block gets the name of the file, divides the value of diff --git a/reference/7.6/Microsoft.PowerShell.Core/Where-Object.md b/reference/7.6/Microsoft.PowerShell.Core/Where-Object.md index eabe5396f217..11d8c05558a6 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/7.6/Microsoft.PowerShell.Core/Where-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/23/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/where-object?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: Where-Object @@ -248,32 +248,38 @@ particular version of Windows. Starting in Windows PowerShell 3.0, there are two different ways to construct a `Where-Object` command. -- **Script block**. You can use a script block to specify the property name, a comparison operator, +- **Script block syntax**. You can use a script block to specify the property name, a comparison operator, and a property value. `Where-Object` returns all objects for which the script block statement is true. - For example, the following command gets processes in the `Normal` priority class, that is, - processes where the value of the **PriorityClass** property equals `Normal`. + For example, the following command gets processes where the value of the **PriorityClass** + property equals `Normal`. `Get-Process | Where-Object {$_.PriorityClass -eq "Normal"}` All PowerShell comparison operators are valid in the script block format. For more information, see [about_Comparison_Operators](./About/about_Comparison_Operators.md). -- **Comparison statement**. You can also write a comparison statement, which is much more like - natural language. Comparison statements were introduced in Windows PowerShell 3.0. +- **Simplified syntax**. To enable the simiplified syntax, `Where-Object` includes 31 switch + parameters that represent the comparison operators. The simplified syntax is easier to read and + write than the script block syntax. You can combine one of the switch parameters with the + **Property** and **Value** parameters to create a command that filters objects based on the + values of their properties. For example, the following commands also get processes that have a priority class of `Normal`. These commands are equivalent and you can use them interchangeably. - `Get-Process | Where-Object -Property PriorityClass -EQ -Value "Normal"` + `Get-Process | Where-Object -Property PriorityClass -Value Normal -EQ` - `Get-Process | Where-Object PriorityClass -EQ "Normal"` + `Get-Process | Where-Object PriorityClass -EQ Normal` - Starting in Windows PowerShell 3.0, `Where-Object` adds comparison operators as parameters in a - `Where-Object` command. Unless specified, all operators are case-insensitive. Before Windows - PowerShell 3.0, the comparison operators in the PowerShell language were only usable in script - blocks. + As shown in the example, the parameter names **Property** and **Value** are optional. The + **Property** parameter is a positional parameter mapped to position `0`. The **Value** parameter + is a positional parameter mapped to position `1`. The switch parameter, used to specify the + comparison, can be used in any position. + + The simplfied syntax was introduced in Windows PowerShell 3.0. For more information, see + [about_Simplified_Syntax](About/about_Simplified_Syntax.md). When you provide a single **Property** to `Where-Object`, the cmdlet treats the value of the property as a boolean expression. When the value of the property's **Length** isn't zero, the @@ -1208,4 +1214,4 @@ You can read more about these methods here [about_Arrays](./About/about_Arrays.m [Tee-Object](../Microsoft.PowerShell.Utility/Tee-Object.md) -[about_Booleans](about/about_Booleans.md) +[about_Booleans](./About/about_Booleans.md)