Using Return Statement in PowerShell Functions and Scripts

30K

Those who dabbled in programming would be familiar with the return keyword. The primary use of return in PowerShell is to return the result of a function and/or exit the current scope. The scope can be a function, script, or script block. After the Return statement is invoked, PowerShell exits a function and returns control to the calling code. In this article, we’ll look at examples of how to use the Return statement in PowerShell scripts.

Return Behavior in PowerShell

The Return statement can be used in PowerShell to exit the current scope.

Example 1

To illustrate, the code below prints the string “The number is %n”, where %n is 1 to 5.

for ($i = 1; $i -le 5; $i++) {
"The number is $i"
}

But when you insert the return keyword after the result, the whole iteration is terminated after the first result.

for ($i = 1; $i -le 5; $i++) {
"The number is $i"
return
}

As you can see below, the for loop is terminated after the first result is displayed because of the return keyword that followed.

Example 2

Let’s look at another example. The code below prints the string “The number is %n” where %n is the numbers 1 to 5. The result is displayed twice in each iteration, once in green and once in magenta.

1..5 | ForEach-Object {
Write-Host "The number is $_" -ForegroundColor Green
Write-Host "The number is $_" -ForegroundColor Magenta
}

Note. The examples above use Write-Host only to demonstrate execution flow. In production scripts and reusable functions, you should generally return objects to the pipeline instead of displaying information directly to the console.

But when you insert the Return keyword, PowerShell exits the current script block invocation and skips any remaining commands in that iteration. Processing then continues with the next pipeline object.

1..5 | ForEach-Object {
Write-Host "The number is $_" -ForegroundColor Green
return
Write-Host "The number is $_" -ForegroundColor Magenta
}

When you use the Return statement in pipeline cmdlets (such as ForEach-Object, Where-Object, etc.), the return doesn’t exit the loop processing, but only moves to the next item in the pipeline:

Get-ADUser -filter *| foreach-object { if (!$_.enabled) { return $_.UserPrincipalName} }

Use break to exit traditional foreach loops. Inside ForEach-Object pipelines, consider using a language foreach loop if you need to terminate processing early.

Keep in mind that the behavior of the return keyword is consistent across Windows PowerShell 5.1 and PowerShell 7+. However, PowerShell 7 introduces improved pipeline performance and cross-platform support, and that’s why we recommend newer version for new automation projects.

Return vs Break vs Continue in Pipelines

Keep in mind that there is a one common source of confusion: return behaves differently in a PowerShell pipeline than in a language-level loop.

Note that in a traditional foreach loop, break immediately exits the loop:

foreach ($item in $items) {
if ($item -eq 5) {
break
}
}

However, in a ForEach-Object pipeline, return only exits the current script block invocation and processing continues with the next pipeline object:

$items | ForEach-Object {
if ($_ -eq 5) {
return
}

$_
}

As a result, return in ForEach-Object behaves more like continue than break.

In case you need to stop processing entirely, you should consider restructuring the code to use a language foreach loop instead of ForEach-Object.

This distinction is important when working with large collections because many folks incorrectly assume that return terminates the entire pipeline.

Return Value from Function in PowerShell Return

The most common use of the Returns operator is to return the results of a PowerShell function.

The return keyword syntax:

return [<expression>]

The [<expression>] can be any PowerShell object and data type, like Boolean, integer, string, or even a statement (such as return (24 + $abc)). Note that in PowerShell, any uncaptured output generated inside a function is automatically returned to the pipeline. The return keyword is not required to return values, but it can be used to explicitly exit the function and control which values are returned.

So, when is return helpful? The Return keyword is used to return only specific value(s) from a function and exit the function scope.

Return vs Write-Output vs Write-Host

Note that it is important to understand the difference between return, Write-Output, and Write-Host.

Let’s look at the following example:

function Test-Output {
Write-Host "Displayed on screen"
Write-Output "Sent to pipeline"
}

When you run the function $result = Test-Output, PowerShell displays:

Displayed on screen

and stores the following value in $result:

Sent to pipeline

Note that the behavior of these commands is different:

Command	Purpose
Write-Host	Displays text directly in the console window.
Write-Output	Sends objects to the PowerShell pipeline.
return	Sends objects to the pipeline and exits the current scope.

For this reason, Write-Host should not be used to return data from a function. In case the result must be consumed by another command, stored in a variable, or passed through the pipeline, you should use Write-Output/return instead.

Example 1: Return a Calculated Value from a PowerShell Function

Let’s use return in a function called Get-Square:

Function Get-Square($number) {
    return $number * $number
    "This line will not be displayed"
}

In this example, the Return statement in function shows the result and exits the scope. The “This line will not be displayed” was not sent to the output.

Example 2: Return the Result of a Conditional Match

Returning a match from a condition is another practical example of a PowerShell function return. When you run a function that checks whether the value is a match against a collection, the return keyword can return the result and stop the search.

First, let’s try a function without the return keyword.

Function Find-Number {
param (
[int[]]$numCollection,
[int]$numToFind
)

foreach ($number in $numCollection) {
    if ($number -eq $numToFind) {
        $number
    }
}
}

This Find-Number function takes two parameters:

• $numCollection — an array of numbers to use as lookup values.
• $numToFind — the single number to find in the $numCollection array.

Now let’s invoke the function by running the command below.

Find-Number -numCollection 1,5,3,6,7,6 -numToFind 6

The command will look for the number 6 with the array of 1,5,3,6,7,6. According to the result below, the function found two instances of the number 6 in the collection, which is correct. According to the result below, the function found two instances of the number 6 in the collection.

But what if we want the function to terminate when it finds the first instance? Then we can use the return keyword instead. Let’s add the return keyword at the beginning of line 8:

Function Find-Number {
param (
[int[]]$numCollection,
[int]$numToFind
)

foreach ($number in $numCollection) {
if ($number -eq $numToFind) {
return $number
}
}
}

This time, the PowerShell function returns the first instance and terminates.

Example 3: Return Multiple Objects from a Function

You can also use the return keyword to explicitly return multiple objects from a function For example, the function below (returns two objects: Services (System.Service.ServiceController) and Processes (System.Diagnostics.Process).

Function GetServiceAndProcess {

return @(
    Get-Service -ErrorAction SilentlyContinue | Select-Object -First 5
    Get-Process -ErrorAction SilentlyContinue | Select-Object -First 5
)

}

Invoke the PowerShell function and save the results in the $result variable:

$result = GetServiceAndProcess

($result[0] | Get-Member)[0].TypeName

($result[1] | Get-Member)[0].TypeName

Or you could store the PowerShell function return result to separate variables like so:

$service, $process = GetServiceAndProcess
$service
$process

Using Return in PowerShell Scripts

You can also use the return keyword in PowerShell script files (.ps1), not only inside functions.

Let’s take a look at the following example:

Write-Host "Before return"
return
Write-Host "After return"

When the script runs, only the first line is displayed:

Before return

The return statement immediately exits the current script scope, and any remaining code is skipped.

You can also return a value from a script:

return "Script completed successfully"

When the script is invoked from another script/command, the returned value is sent to the pipeline just like function output.

Keep in mind that the behavior of return depends on the scope in which it is used:

Scope	Behavior
Function	Returns a value and exits the function.
Script (.ps1)	Exits the script and returns control to the caller.
Pipeline script block (ForEach-Object)	Exits the current script block invocation only.

Wrapping up

The PowerShell return keyword has two primary purposes: returning results and exiting the current scope. Depending on where you are using it (function, script, or pipeline script block), its behavior can be different. You need to understand these scope differences when writing production PowerShell automation.

Key rules to remember:

• Inside a function: return exits the function and sends value to pipeline
• In a pipeline (ForEach-Object): return acts like continue — use break in foreach loops to exit entirely
• Write-Host is for display only, you should never use it to return data from functions
• Any uncaptured output inside a function is automatically returned (return is optional but explicit)