Add PSForEach and PSWhere as aliases for the PowerShell intrinsic methods Where and Foreach (PowerShell#25511)

powercode · SIRMARGIN · commit 25ad50f19075 · 2025-12-11T03:33:02.000+02:00
diff --git a/src/System.Management.Automation/engine/CommandCompletion/CompletionCompleters.cs b/src/System.Management.Automation/engine/CommandCompletion/CompletionCompleters.cs
@@ -6455,7 +6455,9 @@ private static List<CompletionResult> CompleteCommentParameterValue(CompletionCo
             new List<Tuple<string, string>>
                 {
                     new Tuple<string, string>("Where", "Where({ expression } [, mode [, numberToReturn]])"),
-                    new Tuple<string, string>("ForEach", "ForEach(expression [, arguments...])")
+                    new Tuple<string, string>("ForEach", "ForEach(expression [, arguments...])"),
+                    new Tuple<string, string>("PSWhere", "PSWhere({ expression } [, mode [, numberToReturn]])"),
+                    new Tuple<string, string>("PSForEach", "PSForEach(expression [, arguments...])"),
                 };
 
         // List of DSC collection-value variables
diff --git a/src/System.Management.Automation/engine/runtime/Binding/Binders.cs b/src/System.Management.Automation/engine/runtime/Binding/Binders.cs
@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+using System.Buffers;
 using System.Collections;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
@@ -6533,6 +6534,14 @@ public override DynamicMetaObject FallbackInvoke(DynamicMetaObject target, Dynam
 
     internal sealed class PSInvokeMemberBinder : InvokeMemberBinder
     {
+        private static readonly SearchValues<string> s_whereSearchValues = SearchValues.Create(
+            ["Where", "PSWhere"],
+            StringComparison.OrdinalIgnoreCase);
+
+        private static readonly SearchValues<string> s_foreachSearchValues = SearchValues.Create(
+            ["ForEach", "PSForEach"],
+            StringComparison.OrdinalIgnoreCase);
+
         internal enum MethodInvocationType
         {
             Ordinary,
@@ -6681,12 +6690,14 @@ public override DynamicMetaObject FallbackInvokeMember(DynamicMetaObject target,
                         .WriteToDebugLog(this);
                     BindingRestrictions argRestrictions = args.Aggregate(BindingRestrictions.Empty, static (current, arg) => current.Merge(arg.PSGetMethodArgumentRestriction()));
 
-                    if (string.Equals(Name, "Where", StringComparison.OrdinalIgnoreCase))
+                    // We need to pass the empty enumerator to the ForEach/Where operators, so that they can return an empty collection.
+                    // The ForEach/Where operators will not be able to call the script block if the enumerator is empty.
+                    if (s_whereSearchValues.Contains(Name))
                     {
                         return InvokeWhereOnCollection(emptyEnumerator, args, argRestrictions).WriteToDebugLog(this);
                     }
 
-                    if (string.Equals(Name, "ForEach", StringComparison.OrdinalIgnoreCase))
+                    if (s_foreachSearchValues.Contains(Name))
                     {
                         return InvokeForEachOnCollection(emptyEnumerator, args, argRestrictions).WriteToDebugLog(this);
                     }
@@ -6866,12 +6877,12 @@ public override DynamicMetaObject FallbackInvokeMember(DynamicMetaObject target,
             if (!_static && !_nonEnumerating && target.Value != AutomationNull.Value)
             {
                 // Invoking Where and ForEach operators on collections.
-                if (string.Equals(Name, "Where", StringComparison.OrdinalIgnoreCase))
+                if (s_whereSearchValues.Contains(Name))
                 {
                     return InvokeWhereOnCollection(target, args, restrictions).WriteToDebugLog(this);
                 }
 
-                if (string.Equals(Name, "ForEach", StringComparison.OrdinalIgnoreCase))
+                if (s_foreachSearchValues.Contains(Name))
                 {
                     return InvokeForEachOnCollection(target, args, restrictions).WriteToDebugLog(this);
                 }
@@ -7490,7 +7501,7 @@ internal static object InvokeAdaptedMember(object obj, string methodName, object
             // As a last resort, we invoke 'Where' and 'ForEach' operators on singletons like
             //    ([pscustomobject]@{ foo = 'bar' }).Foreach({$_})
             //    ([pscustomobject]@{ foo = 'bar' }).Where({1})
-            if (string.Equals(methodName, "Where", StringComparison.OrdinalIgnoreCase))
+            if (s_whereSearchValues.Contains(methodName))
             {
                 var enumerator = (new object[] { obj }).GetEnumerator();
                 switch (args.Length)
@@ -7506,7 +7517,7 @@ internal static object InvokeAdaptedMember(object obj, string methodName, object
                 }
             }
 
-            if (string.Equals(methodName, "Foreach", StringComparison.OrdinalIgnoreCase))
+            if (s_foreachSearchValues.Contains(methodName))
             {
                 var enumerator = (new object[] { obj }).GetEnumerator();
                 object[] argsToPass;
diff --git a/test/powershell/engine/ETS/Adapter.Tests.ps1 b/test/powershell/engine/ETS/Adapter.Tests.ps1
@@ -200,6 +200,11 @@ Describe "Adapter Tests" -tags "CI" {
 
             # TODO: dynamic method calls
         }
+
+        It "Can use PSForEach as an alias for the Foreach magic method" {
+            $x = 5
+            $x.PSForEach({$_}) | Should -Be 5
+        }
     }
 
     Context "Where Magic Method Adapter Tests" {
@@ -240,6 +245,11 @@ Describe "Adapter Tests" -tags "CI" {
                 } -PassThru -Force
             $x.Where(5) | Should -Be 10
         }
+
+        It "Can use PSWhere as an alias for the Where magic method" {
+            $x = 5
+            $x.PSWhere{$true} | Should -Be 5
+        }
     }
 }
 

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`// Copyright (c) Microsoft Corporation.`
`2`	`2`	`// Licensed under the MIT License.`
`3`	`3`
	`4`	`+using System.Buffers;`
`4`	`5`	`using System.Collections;`
`5`	`6`	`using System.Collections.Concurrent;`
`6`	`7`	`using System.Collections.Generic;`
`@@ -6533,6 +6534,14 @@ public override DynamicMetaObject FallbackInvoke(DynamicMetaObject target, Dynam`
`6533`	`6534`
`6534`	`6535`	`internal sealed class PSInvokeMemberBinder : InvokeMemberBinder`
`6535`	`6536`	`{`
	`6537`	`+ private static readonly SearchValues<string> s_whereSearchValues = SearchValues.Create(`
	`6538`	`+ ["Where", "PSWhere"],`
	`6539`	`+ StringComparison.OrdinalIgnoreCase);`
	`6540`	`+`
	`6541`	`+ private static readonly SearchValues<string> s_foreachSearchValues = SearchValues.Create(`
	`6542`	`+ ["ForEach", "PSForEach"],`
	`6543`	`+ StringComparison.OrdinalIgnoreCase);`
	`6544`	`+`
`6536`	`6545`	`internal enum MethodInvocationType`
`6537`	`6546`	`{`
`6538`	`6547`	`Ordinary,`
`@@ -6681,12 +6690,14 @@ public override DynamicMetaObject FallbackInvokeMember(DynamicMetaObject target,`
`6681`	`6690`	`.WriteToDebugLog(this);`
`6682`	`6691`	`BindingRestrictions argRestrictions = args.Aggregate(BindingRestrictions.Empty, static (current, arg) => current.Merge(arg.PSGetMethodArgumentRestriction()));`
`6683`	`6692`
`6684`		`- if (string.Equals(Name, "Where", StringComparison.OrdinalIgnoreCase))`
	`6693`	`+ // We need to pass the empty enumerator to the ForEach/Where operators, so that they can return an empty collection.`
	`6694`	`+ // The ForEach/Where operators will not be able to call the script block if the enumerator is empty.`
	`6695`	`+ if (s_whereSearchValues.Contains(Name))`
`6685`	`6696`	`{`
`6686`	`6697`	`return InvokeWhereOnCollection(emptyEnumerator, args, argRestrictions).WriteToDebugLog(this);`
`6687`	`6698`	`}`
`6688`	`6699`
`6689`		`- if (string.Equals(Name, "ForEach", StringComparison.OrdinalIgnoreCase))`
	`6700`	`+ if (s_foreachSearchValues.Contains(Name))`
`6690`	`6701`	`{`
`6691`	`6702`	`return InvokeForEachOnCollection(emptyEnumerator, args, argRestrictions).WriteToDebugLog(this);`
`6692`	`6703`	`}`
`@@ -6866,12 +6877,12 @@ public override DynamicMetaObject FallbackInvokeMember(DynamicMetaObject target,`
`6866`	`6877`	`if (!_static && !_nonEnumerating && target.Value != AutomationNull.Value)`
`6867`	`6878`	`{`
`6868`	`6879`	`// Invoking Where and ForEach operators on collections.`
`6869`		`- if (string.Equals(Name, "Where", StringComparison.OrdinalIgnoreCase))`
	`6880`	`+ if (s_whereSearchValues.Contains(Name))`
`6870`	`6881`	`{`
`6871`	`6882`	`return InvokeWhereOnCollection(target, args, restrictions).WriteToDebugLog(this);`
`6872`	`6883`	`}`
`6873`	`6884`
`6874`		`- if (string.Equals(Name, "ForEach", StringComparison.OrdinalIgnoreCase))`
	`6885`	`+ if (s_foreachSearchValues.Contains(Name))`
`6875`	`6886`	`{`
`6876`	`6887`	`return InvokeForEachOnCollection(target, args, restrictions).WriteToDebugLog(this);`
`6877`	`6888`	`}`
`@@ -7490,7 +7501,7 @@ internal static object InvokeAdaptedMember(object obj, string methodName, object`
`7490`	`7501`	`// As a last resort, we invoke 'Where' and 'ForEach' operators on singletons like`
`7491`	`7502`	`// ([pscustomobject]@{ foo = 'bar' }).Foreach({$_})`
`7492`	`7503`	`// ([pscustomobject]@{ foo = 'bar' }).Where({1})`
`7493`		`- if (string.Equals(methodName, "Where", StringComparison.OrdinalIgnoreCase))`
	`7504`	`+ if (s_whereSearchValues.Contains(methodName))`
`7494`	`7505`	`{`
`7495`	`7506`	`var enumerator = (new object[] { obj }).GetEnumerator();`
`7496`	`7507`	`switch (args.Length)`
`@@ -7506,7 +7517,7 @@ internal static object InvokeAdaptedMember(object obj, string methodName, object`
`7506`	`7517`	`}`
`7507`	`7518`	`}`
`7508`	`7519`
`7509`		`- if (string.Equals(methodName, "Foreach", StringComparison.OrdinalIgnoreCase))`
	`7520`	`+ if (s_foreachSearchValues.Contains(methodName))`
`7510`	`7521`	`{`
`7511`	`7522`	`var enumerator = (new object[] { obj }).GetEnumerator();`
`7512`	`7523`	`object[] argsToPass;`
Original file line number	Diff line number	Diff line change
`@@ -200,6 +200,11 @@ Describe "Adapter Tests" -tags "CI" {`
`200`	`200`
`201`	`201`	`# TODO: dynamic method calls`
`202`	`202`	`}`
	`203`	`+`
	`204`	`+ It "Can use PSForEach as an alias for the Foreach magic method" {`
	`205`	`+ $x = 5`
	`206`	`+ $x.PSForEach({$_}) \| Should -Be 5`
	`207`	`+ }`
`203`	`208`	`}`
`204`	`209`
`205`	`210`	`Context "Where Magic Method Adapter Tests" {`
`@@ -240,6 +245,11 @@ Describe "Adapter Tests" -tags "CI" {`
`240`	`245`	`} -PassThru -Force`
`241`	`246`	`$x.Where(5) \| Should -Be 10`
`242`	`247`	`}`
	`248`	`+`
	`249`	`+ It "Can use PSWhere as an alias for the Where magic method" {`
	`250`	`+ $x = 5`
	`251`	`+ $x.PSWhere{$true} \| Should -Be 5`
	`252`	`+ }`
`243`	`253`	`}`
`244`	`254`	`}`
`245`	`255`