How to return one and only one value from a PowerShell function?

Question

I've learned from this Stack Overflow question, that PowerShell return semantics are different, let's say, from C#'s return semantics. Quote from the aforementioned question:

PowerShell has really wacky return semantics - at least when viewed from a more traditional programming perspective. There are two main ideas to wrap your head around: All output is captured, and returned. The return keyword really just indicates a logical exit point.

Let's look at this example:

function Calculate
{
   echo "Calculate"
   return 11
}

$result = Calculate

If you echo $result you will realise that something is not right. You'd expect this:

11

But the reality, what you actually see, is different:

Calculate
11

So instead of getting back only the intended return value, you actually get back an array.

You could get rid of the echo statements and not polluting the return value, but if you call another function from your function, which echoes something, then you're in trouble again.

How can I write a PowerShell function that only returns one thing? If the built-in PowerShell functions do return only one value, why can't I do that?

The workaround that I'm using now and I'd love to get rid of:

function Calculate
{
   # Every function that returns has to echo something
   echo ""
   return 11
}

# The return values is the last value from the returning array
$result = (Calculate)[-1]

Answer 1

Several answers already given do not fully answer your question because they do not account for other cmdlets you might call--as you point out--that might "pollute" your output. The answer from @Laezylion is essentially correct but I believe bears further elaboration.

It is clear that you appreciate that your current workaround--forcing every function to return an array then taking the last element--is not a very robust solution. (In fact, I think it is safe to call that a kludge. :-) The correct approach--and a direct answer to your question--is clear... though at first glance it sounds like a tautology:

Question: How do you ensure a function returns only one thing?
Answer: By ensuring that it returns only one thing.

Let me elucidate. There are really two kinds of functions/cmdlets in PowerShell: (A) those that return data and (B) those that do not return data but may instead report progress or diagnostic messages. Problems arise, as you have seen, when you try to mix the two. And this may easily happen inadvertently. Thus, it is your responsibility, as the function author, to understand each function/cmdlet call within your function: specifically, does it return anything, be it a true return value or just diagnostic output? You are expecting output from type A functions, but you need to be wary of any type B functions. For any one that does return something you must either assign it to a variable, feed it into a pipeline, or... make it go away. (There are several ways to make it go away: pipe it to Out-Null, cast it to void, redirect it to $null, or assign it to $null. See Jason Archer’s Stack Overflow post that evaluates the performance of each of these flavors, suggesting you shy away from Out-Null.)

Yes, this approach takes more effort, but you get a more robust solution by doing so. For a bit more discussion on this very issue, these A/B functions, etc. see Question 1 on A Plethora of PowerShell Pitfalls recently published on Simple-Talk.com.

Answer 2

You can also just assign everything to null, and then return just the variable you want:

Function TestReturn {

    $Null = @(
        Write-Output "Hi there!"
        1 + 1
        $host
        $ReturnVar = 5
    )
    return $ReturnVar
}

Answer 3

Don't use echo to write information, use Write-Host, Write-Verbose or Write-Debug depending on the message.

Echo is an alias for Write-Output which will send it as an Object through the pipeline. Write-Host/Verbose/Debug however is only console-messages.

PS P:\> alias echo

CommandType Name                 ModuleName
----------- ----                 ----------
Alias       echo -> Write-Output               

Sample:

function test {
    Write-Host calc
    return 11
}

$t = test
"Objects returned: $($t.count)"
$t

#Output
calc
Objects returned: 1
11

Also, if you return the value on the last line in your function, then you don't need to use return. Writing the Object/value by itself is enough.

function test {
    Write-Host calc
    11
}

The difference is that return 11 would skip the lines after it you use it in the middle of a function.

function test {
    return 11
    12
}

test

#Output
11

Answer 4

Worth mentioning:

Any unmanaged command output inside your function will end up as a return value.

I use to get this trouble with a function managing XML content:

Function Add-Node(NodeName){
    $NewXmlNode = $Xml.createElement("Item")
    $Xml.Items.appendChild($NewXmlNode) | out-null
}

If you remove the Out-Null, the return of your function will be the Node basic properties... (You can also manage the exit code of the appendChild command ... it depends on the motivation) :)

Answer 5

@Michael Sorens's answer is useful, but it suggests a design strategy that seems rather onerous. I don't want to have to separate out data processing functions from functions that report progress or diagnostic messages. Reading his blogpost, I found a less hacky work-around to the OP's question. Here's the key sentence from the blog post:

A PowerShell function returns all uncaptured output.

So what if we capture our output?

function Calculate
{
   $junkOutput = echo "Calculate"
   return 11
}

$result = Calculate

Now $result just contains 11, as intended.

Answer 6

You could replace echo (alias of Write-Output) with Write-Host:

PS> function test{ Write-Host "foo";"bar"} 
PS> $a = test                                    
test                                          
PS >$a                                         
bar

Answer 7

echo is an alias for Write-Output which sends the object to the next command.

Using Write-Host should help:

PS:> function Calculate
>> {
>>    # Every function that returns has to echo something
>>    Write-Host "test"
>>    return 11
>> }
>>
PS:> $A = Calculate
test
PS:> $A
11

Answer 8

The use of parenthesis seems critical when calling a function that accepts parameters. This example fills a DataTable from SQL Server, and returns an [int] from the first row, fourth column. Note the parenthesis around the actual function call assigned to the variable [int]$tt1

    function InvokeSQL-GetOneCount { param( [string]$cn, [string]$prj )
        $sql = "SELECT * FROM [dbo].[dummytable] WHERE ProjectNumber = '$prj' ORDER BY FormID, PartID;"

        $handler = [System.Data.SqlClient.SqlInfoMessageEventHandler] { param($sender, $event) Handle-Message -message $event.Message -fcolor "yellow" -bcolor "black"; };
        $conn = new-Object System.Data.SqlClient.SqlConnection($cn)
        $conn.add_InfoMessage($handler); 
        $conn.FireInfoMessageEventOnUserErrors = $true;

        $cmd = New-Object System.Data.SqlClient.SqlCommand;
        $cmd.Connection = $conn;
        $cmd.CommandType = [System.Data.CommandType]::Text;
        $cmd.CommandText = $sql;
        $cmd.CommandTimeout = 0;

        $sa = New-Object System.Data.SqlClient.SqlDataAdapter($cmd);
        $dt = New-Object System.Data.DataTable("AllCounts");
        $sa.Fill($dt) | Out-Null;

        [int]$rval = $dt.Rows[0][3];

        $conn.Close();
        return $rval;
    }
    clear-host;
    [int]$tt1 = (InvokeSQL-GetOneCount -cn "Server=[your server];DataBase=[your catalog];Integrated Security=SSPI" -prj "MS1904");
    write-host $tt1;

Answer 9

I ended up using the following to make sure only one value is returned:

• write-host 'some console message'
• invoke-some-utility arg1 arg2 | write-host
• functionCall arg1 arg2 | out-null # suppress any output
• return theDesiredValue

Answer 10

PowerShell does pipes awkwardkly. To work around the return value problem and save the pipeline for real data, pass the function a value by reference, that is, an array. The array can be loaded with the value you wish to return. Here's a simple example:

# tp.ps1
#   test passed parameters
#   show that arrays are passed by reference, and can be used to provide
#   return values outside the pipeline
function doprint
{
    process { write-output "value now: $psitem" }
}

function recurse($thing,     $rtx)
{
    $thing++
    if($thing -lt 20) {
        if($thing -eq 15) { $rtx[0] = $thing }
        write-output $thing | doprint
        recurse $thing     $rtx
    }
}

j=0
$rtv=@(4)
recurse $j     $rtv
write-output $rtv[0]