Merge pull request #12027 from MicrosoftDocs/main

4/24/2025 PM Publish

Author: Taojunshen

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,

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

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)

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,

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

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)