Should we specify array type for OutputType and .OUTPUTS

PowerShell Help
1

Hello community, my first post here…

 

Consider following function:

<#
.DESCRIPTION
Documenting array output

.OUTPUTS
System.Int32[]
#>
function Test-ArrayOutputType
{
    [OutputType([System.Int32[]])]
    param ()

    return @(0, 1, 2)
}

 

I understand that entry array won’t be returned at once, the functionality of this sample function isn’t important at all.

I also understand what OutputType is and does and it’s meaning is also not relevant here.

 

My question is should we specify output as an array instead of just type name?

I have some feeling (according to MSDN documentation) that we should specify just the type, and not quantity, for example for the above function this would be considered a conventional way to specify outputs?

.OUTPUTS System.Int32

[OutputType([System.Int32])]

 

Which one of these 2 options to document outputs should we use to document code and if so, why?

Why would specifying array types be wrong and is there anything “wrong” if we do so?

2

I wouldn’t recommend specifying the output as an array unless it was some unique circumstance. If someone wants to force your function to return an array regardless of output, they can use the array subexpression when calling the function i.e. @(Test-ArrayOutputType).

For the most part, I rarely see the “return” keyword in PS functions, because generally functions in PS return objects at any point of execution and continue executing i.e.

function MyFunction ()
{
    "Hello"
    1 + 1
    @{name="MyFunction"}
}

If you call this function, you will find it returns an array of 3 different objects even though an array is not implicitly instantiated inside the function definition. If you pipe the function call to Get-Member, you will see the different object types. Now if you put the “return” keyword in front of one of the first 2 objects, the function will stop execution at that point and not return the rest of the objects. If however there is an object type your function must always return as an array, then I guess it would be ok to specify as such. i.e.

function MyFunction ()
{
    "Hello"
    1 + 1
    @{name="MyFunction"}
    @(1,2,3,4)
}

 

3

That was very useful answer!

I just couldn’t find confirmation to this, what was suspicious is that nowhere did I see output specified as an array, so it makes sense.

 

I know the return keyword stops executing something at some point, It’s my left over from other languages :slight_smile:

 

Btw. I can’t see anywhere to upvote you, but thanks!

4

OutputTyps attribute is not going to restrict the function in any terms. If its mentioned it will help in intellisense in the editors/console and of course as Mike mentioned, anytime any object can be returned.

and both can be used for better readability and documentation purpose.

Function test{
[OutputType([array])]
Param($r)
return "nothing"
}

(test).<hit tab and navigate> # you can see array methods coming up


Function test{
[OutputType([system.diagnostics.process])]
Param($r)
return "nothing"
}

(test).<hit tab and navigate> # you can see process methods coming up