From 69808ee7cf8b45feefc15ef0ce29df6966f994b7 Mon Sep 17 00:00:00 2001 From: derkallevombau <35200962+derkallevombau@users.noreply.github.com> Date: Tue, 10 Mar 2026 04:39:33 +0100 Subject: [PATCH 1/2] Fix Test-Remainder invocation to pass three arguments, not two. You state: "The following example declares a Value parameter that's mandatory and a Remaining parameter that accepts **all the remaining parameter values** that are submitted to the function. You want to demonstrate this with this invocation: `Test-Remainder first one, two` But your "all the remaining parameter values" is merely one value: `one, two` is an array. Thus, if you removed `ValueFromRemainingArguments`, the same invocation would yield the same output, so your example **does not** demonstrate the benefit of `ValueFromRemainingArguments`. To fix it, three args have to be passed to the Cmdlet, not just two. --- .../About/about_Functions_Advanced_Parameters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index e59e7f5dc0bb..b8f1dc269bff 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -591,7 +591,7 @@ function Test-Remainder { "${i}: $($Remaining[$i])" } } -Test-Remainder first one, two +Test-Remainder first one two ``` ```Output From 47a3080faac87670497669a7a305718481b30cf4 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 10 Mar 2026 09:31:39 -0500 Subject: [PATCH 2/2] Improve Test-Remainder examples --- .../about_Functions_Advanced_Parameters.md | 28 ++++++------ .../about_Functions_Advanced_Parameters.md | 43 ++++++++++++++++--- .../about_Functions_Advanced_Parameters.md | 43 ++++++++++++++++--- .../about_Functions_Advanced_Parameters.md | 43 ++++++++++++++++--- 4 files changed, 123 insertions(+), 34 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index 472a84a9a228..88ec2b4f554b 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -1,7 +1,7 @@ --- description: Explains how to add parameters to advanced functions. Locale: en-US -ms.date: 01/18/2026 +ms.date: 03/10/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions_Advanced_Parameters @@ -576,40 +576,36 @@ The `ValueFromRemainingArguments` argument indicates that the parameter accepts all the parameter's values in the command that aren't assigned to other parameters of the function. -There's a known issue for using collections with -**ValueFromRemainingArguments** where the passed-in collection is treated as a +Collections passed to **ValueFromRemainingArguments** are always treated as a single element. -The following example demonstrates this known issue. The **Remaining** -parameter should contain **one** at **index 0** and **two** at **index 1**. -Instead, both elements are combined into a single entity. - ```powershell function Test-Remainder { param( [Parameter(Mandatory, Position=0)] [string]$Value, - [Parameter(Position=1, ValueFromRemainingArguments)] + [Parameter(ValueFromRemainingArguments, Position=1)] [string[]]$Remaining ) - "Found $($Remaining.Count) elements" + "Value = $Value" + "Found $($Remaining.Count) remaining values" for ($i = 0; $i -lt $Remaining.Count; $i++) { "${i}: $($Remaining[$i])" } } -Test-Remainder first one, two ``` -```Output -Found 1 elements -0: one two -``` +```powershell +PS> Test-Remainder first one two, three -> [!NOTE] -> This issue is resolved in PowerShell 6.2. +Value = first +Found 2 remaining values +0: one +1: two three +``` #### HelpMessage argument diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index c1ece0adc254..7673a43ce83b 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -1,7 +1,7 @@ --- description: Explains how to add parameters to advanced functions. Locale: en-US -ms.date: 01/18/2026 +ms.date: 03/10/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions_Advanced_Parameters @@ -581,23 +581,54 @@ function Test-Remainder { [Parameter(Mandatory, Position=0)] [string]$Value, - [Parameter(Position=1, ValueFromRemainingArguments)] + [Parameter(ValueFromRemainingArguments, Position=1)] [string[]]$Remaining ) - "Found $($Remaining.Count) elements" + "Value = $Value" + "Found $($Remaining.Count) remaining values" for ($i = 0; $i -lt $Remaining.Count; $i++) { "${i}: $($Remaining[$i])" } } -Test-Remainder first one, two ``` -```Output -Found 2 elements +```powershell +PS> Test-Remainder first one two three + +Value = first +Found 3 remaining values 0: one 1: two +2: three +``` + +Beginning in PowerShell 6.2, collections are handled differently when passed to +**ValueFromRemainingArguments**. If you only pass a collection, then each value +in the collection is treated as a separate item. + +```powershell +PS> Test-Remainder first one, two, three + +Value = first +Found 3 remaining values +0: one +1: two +2: three +``` + +When you pass multiple values where at least one isn't a collection, the +collection is treated as a single item. + +```powershell +PS> Test-Remainder first one, two three four + +Value = first +Found 3 remaining values +0: one two +1: three +2: four ``` #### HelpMessage argument diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index b8f1dc269bff..eb97af896607 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -1,7 +1,7 @@ --- description: Explains how to add parameters to advanced functions. Locale: en-US -ms.date: 01/18/2026 +ms.date: 03/10/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions_Advanced_Parameters @@ -581,23 +581,54 @@ function Test-Remainder { [Parameter(Mandatory, Position=0)] [string]$Value, - [Parameter(Position=1, ValueFromRemainingArguments)] + [Parameter(ValueFromRemainingArguments, Position=1)] [string[]]$Remaining ) - "Found $($Remaining.Count) elements" + "Value = $Value" + "Found $($Remaining.Count) remaining values" for ($i = 0; $i -lt $Remaining.Count; $i++) { "${i}: $($Remaining[$i])" } } -Test-Remainder first one two ``` -```Output -Found 2 elements +```powershell +PS> Test-Remainder first one two three + +Value = first +Found 3 remaining values 0: one 1: two +2: three +``` + +Beginning in PowerShell 6.2, collections are handled differently when passed to +**ValueFromRemainingArguments**. If you only pass a collection, then each value +in the collection is treated as a separate item. + +```powershell +PS> Test-Remainder first one, two, three + +Value = first +Found 3 remaining values +0: one +1: two +2: three +``` + +When you pass multiple values where at least one isn't a collection, the +collection is treated as a single item. + +```powershell +PS> Test-Remainder first one, two three four + +Value = first +Found 3 remaining values +0: one two +1: three +2: four ``` #### HelpMessage argument diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index c5be2dda1a13..328cc07c5bcb 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -1,7 +1,7 @@ --- description: Explains how to add parameters to advanced functions. Locale: en-US -ms.date: 01/18/2026 +ms.date: 03/10/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions_Advanced_Parameters @@ -581,23 +581,54 @@ function Test-Remainder { [Parameter(Mandatory, Position=0)] [string]$Value, - [Parameter(Position=1, ValueFromRemainingArguments)] + [Parameter(ValueFromRemainingArguments, Position=1)] [string[]]$Remaining ) - "Found $($Remaining.Count) elements" + "Value = $Value" + "Found $($Remaining.Count) remaining values" for ($i = 0; $i -lt $Remaining.Count; $i++) { "${i}: $($Remaining[$i])" } } -Test-Remainder first one, two ``` -```Output -Found 2 elements +```powershell +PS> Test-Remainder first one two three + +Value = first +Found 3 remaining values 0: one 1: two +2: three +``` + +Beginning in PowerShell 6.2, collections are handled differently when passed to +**ValueFromRemainingArguments**. If you only pass a collection, then each value +in the collection is treated as a separate item. + +```powershell +PS> Test-Remainder first one, two, three + +Value = first +Found 3 remaining values +0: one +1: two +2: three +``` + +When you pass multiple values where at least one isn't a collection, the +collection is treated as a single item. + +```powershell +PS> Test-Remainder first one, two three four + +Value = first +Found 3 remaining values +0: one two +1: three +2: four ``` #### HelpMessage argument