Why does invoking a PowerShell script block with .Invoke() return a collection?

Question

It seems that invoking a PowerShell script block (by invoking the .Invoke() method) always produces a collection. Specifically, a collection of type

System.Collections.ObjectModel.Collection`1[[System.Management.Automation.PSObject, System.Management.Automation, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]

Even invoking an empty script block ({}.Invoke()) returns a collection. Invoking the same script block using the call operator (&) produces the normally expected return (either a scalar or [object[]]).

This turns out to be convenient if you need a collection instead of an array, but it seems kind of counterintuitive.

Does anyone know why it behaves this way?

I knew there are two different invocations, .Invoke() and .InvokeReturnAsIs() from reading the language spec. That's were I first noticed it.

I just don't understand the reasoning behind the naming convention and the way the mechanics of it appear to work. Looking at the documentation, what I would have thought would be the default invocation method is not what is used when the script block is invoked in PowerShell. It appears that .InvokeReturnAsIs() just returns a stream of objects, and then PowerShell wraps it into an object array if there's more than one object, as scalar if there's only one object, or creates a null object if there are none, as if there's an implicit pipeline there. Using .Invoke() returns a collection, always, and PowerShell leaves it as a collection.

Community · Accepted Answer · 2020-06-20 09:12:55Z

12

Looks to be the difference between these two methods:

Invoke - Invokes the script block with the specified arguments, returning the results as PSObject objects.

InvokeReturnAsIs - Runs the script block with the specified arguments. This method returns the raw (unwrapped) result objects so that it can be more efficient.

http://msdn.microsoft.com/en-us/library/system.management.automation.scriptblock_methods(v=vs.85).aspx

Invoke

$code = {"a"}
$code.Invoke().Gettype().FullName

Output:

System.Collections.ObjectModel.Collection`1[[System.Management.Automation.PSObject, System.Management.Automation, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]

InvokeReturnAsIs

$code.InvokeReturnAsIs().GetType().FullName

Output:

System.String

edited Jun 20, 2020 at 9:12

CommunityBot

11 silver badge

answered Jan 27, 2012 at 5:08

Andy Arismendi

53.1k17 gold badges113 silver badges130 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

mklement0 · Accepted Answer · 2017-06-21 22:06:08Z

8

My guess is that the team wanted to be consistent with the PowerShell.Invoke() API, which returns a Collection<PSObject>. This C# signature makes it easier for clients to consume 0, 1 or N returned values and not have to worry about checking for null and whether the returned object was wrapped or not.

From the .NET Design Guidelines:

DO NOT return null values from collection properties or from methods returning collections. Return an empty collection or an empty array instead.

You could say then why not just return object. Then I would have to against null or not and then I'd have to test to see if it implemented ICollection to determine if I had a scalar or collection. From a C# dev's point of view, this is a spew (pardon the rhyme). :-)

edited Jun 21, 2017 at 22:06

mklement0

452k68 gold badges728 silver badges988 bronze badges

answered Nov 23, 2013 at 4:58

Keith Hill

204k44 gold badges370 silver badges377 bronze badges

Comments

manojlds · Accepted Answer · 2012-01-27 05:10:59Z

1

Because that is what it is designed to do, and there is an alternate!

Invoke - Invokes the script block with the specified arguments, returning the results as (collection of) PSObject objects.

InvokeReturnAsIs - Runs the script block with the specified arguments. This method returns the raw (unwrapped) result objects so that it can be more efficient.

Also, {}.invoke() returns null, so I don't know where you got the impressions that even that returns a collection.

http://msdn.microsoft.com/en-us/library/system.management.automation.scriptblock.invokereturnasis(v=vs.85).aspx

answered Jan 27, 2012 at 5:10

manojlds

303k66 gold badges482 silver badges426 bronze badges

2 Comments

mjolinor Over a year ago

I got the idea that it ruturns as collection when I did this: ({}.invoke).gettype()

mklement0 Over a year ago

Get-Member -InputObject ({}.invoke()) shows that it too returns a collection; conversely, $null -eq {}.Invoke() returns $False. The collection returned is empty, which is why it produces no output in the console.

Collectives™ on Stack Overflow

Why does invoking a PowerShell script block with .Invoke() return a collection?

3 Answers 3

Comments

Comments

2 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

Comments

Comments

2 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related