From 9228cfef8253d83e17f8035da8351d8c38fa4e49 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 24 Apr 2025 15:47:34 -0500 Subject: [PATCH] Add notes about CIM/CDXML bugs with PipelineVariable --- .../About/about_CommonParameters.md | 60 ++++++++++++++- .../About/about_CommonParameters.md | 73 ++++++++++++++++++- .../About/about_CommonParameters.md | 73 ++++++++++++++++++- .../About/about_CommonParameters.md | 73 ++++++++++++++++++- 4 files changed, 275 insertions(+), 4 deletions(-) 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/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.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.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,