HOWTO · PowerShell

How to Return Several Items From a PowerShell Function

This tutorial will teach you to return multiple values from a PowerShell function.

On this page

A PowerShell function can emit several values through its success stream. For related values, return an array; for values looked up by keys, use a hashtable; and for a record with named properties, use [PSCustomObject]. The caller captures the emitted values by assigning the function call to a variable.

The return keyword exits the current function scope and can emit a value, but it is not required to emit output. It also does not package several expressions into one result: any success-stream output produced before the function exits is part of its output. Use one of the following shapes when you want the caller to receive a clear collection or record.

How PowerShell Functions Return Output

PowerShell functions send success-stream output to the caller. A command such as Write-Output emits values, and an expression left in the function also writes to that stream. The caller can capture that output with assignment, for example $result = Get-Data.

return $value emits $value and exits the function. It is useful when you want to finish at a particular point, but it is not a special container for multiple values. Avoid writing incidental success-stream output, such as a status string, when the caller expects only a data object; that extra output will also be captured.

Return Multiple Values as an Array

Use an array when the result is an ordered sequence of values that callers will process together. PowerShell writes array elements to the success stream; capture the call with @(...) when you want the variable to remain an array even if the function later returns only one item.

Run this example:

function Get-Colors {
    return @('red', 'green', 'blue')
}

$colors = @(Get-Colors)
foreach ($color in $colors) {
    Write-Output $color
}

The caller receives the three strings and can loop over them or pass the sequence to another command. An array preserves their order, but it does not give each value a descriptive name; use a keyed or property-based shape when callers need to identify values by role.

Return Named Values with a Hashtable

A hashtable groups values under unique keys. Choose it when the caller needs to retrieve values by a known key, especially when the set of keys is more useful than a positional sequence.

function Get-UserRecord {
    return @{
        Name    = 'Rohan'
        Age     = 21
        Address = 'UK'
    }
}

$user = Get-UserRecord
Write-Output "$($user['Name']) is $($user['Age']) and lives in $($user['Address'])."

The caller accesses an entry with $user['Name']; PowerShell also permits property-style access such as $user.Name. Prefer bracket notation when a key contains spaces or could be confused with a member name. A hashtable is convenient for key-based lookup, but its keys are not a declared record schema.

Return a Structured Object with [PSCustomObject]

Use [PSCustomObject] for one record with named properties. This gives the caller a single object whose fields can be accessed directly and whose property names communicate what each value means.

function Get-UserRecord {
    return [PSCustomObject]@{
        Name    = 'Rohan'
        Age     = 21
        Address = 'UK'
    }
}

$user = Get-UserRecord
Write-Output "Name: $($user.Name)"
Write-Output "Age: $($user.Age)"
Write-Output "Address: $($user.Address)"

Access fields as $user.Name or inspect them with commands such as Format-List. Iterating over $user does not iterate over its properties; it treats the record as an object. To process the fields themselves, access the properties explicitly, for example with $user.PSObject.Properties.

Choose the Right Return Shape

Choose an array for an ordered list that callers will loop over, sort, or pass through a pipeline. Choose a hashtable when callers need key-based lookup and a lightweight collection of key-value pairs is enough. Choose [PSCustomObject] when the output represents one record with named fields that callers will access or display.

Whichever shape you choose, keep the function’s success-stream output limited to the intended result. Capture the call once, then use array iteration, key lookup, or property access according to that result’s shape. This makes the function’s contract clear and prevents incidental messages from being mistaken for returned data.