Returning Objects Properly¶

PowerShell is an object‑oriented shell. This means functions should return objects, not formatted text. Returning objects allows callers to sort, filter, export, and pipe the results just like they would with built‑in cmdlets. This section explains how to return objects correctly, how output works inside functions, and how to avoid common mistakes.

1. PowerShell Returns Anything You Output¶

PowerShell functions return all values written to the output stream.

There is no special “return” statement required.

Example: implicit return¶

function Get-Square {
    param($n)
    $n * $n
}

Get-Square 5

Output:

25

Explanation:

• $n * $n produces a value.
• PowerShell sends that value to the output stream.
• The caller receives it as the function’s return value.

2. Returning Objects Instead of Strings¶

Returning strings limits what callers can do.

Returning objects gives callers full control.

Bad example (string output)¶

function Get-UserInfo {
    param($name, $age)
    "Name: $name, Age: $age"
}

This returns a plain string. You cannot sort or filter by properties.

Correct example (object output)¶

function Get-UserInfo {
    param($name, $age)

    [pscustomobject]@{
        Name = $name
        Age  = $age
    }
}

Now the function returns a structured object:

$user = Get-UserInfo -name "Alice" -age 30
$user.Name
$user.Age

This is how PowerShell cmdlets behave.

3. Returning Multiple Objects¶

If a function outputs multiple objects, PowerShell returns them as a collection.

Example¶

function Get-Numbers {
    1
    2
    3
}

$result = Get-Numbers
$result

Output:

1
2
3

$result becomes an array containing 1, 2, 3.

4. Using return Explicitly¶

The return keyword stops execution and outputs a value.

function Get-Value {
    return 42
    "This never runs"
}

Use return only when you need to exit early.

Otherwise, rely on implicit output.

5. Avoiding Unwanted Output¶

Anything written to the output stream becomes part of the return value.

This includes:

• Strings
• Numbers
• Objects
• Unintended output from commands

Bad example¶

function Get-Data {
    "Starting..."
    10
}

Output:

Starting...
10

The caller receives two objects, which is usually not intended.

Correct example¶

Use Write-Verbose, Write-Information, or Write-Host for messages.

function Get-Data {
    [CmdletBinding()]
    param()

    Write-Verbose "Starting..."
    10
}

Now:

Get-Data -Verbose

Output:

VERBOSE: Starting...
10

The function returns only 10.

6. Returning Custom Objects¶

Custom objects are the preferred way to return structured data.

Example: returning a custom object¶

function Get-ServerStatus {
    param($name)

    [pscustomobject]@{
        Server = $name
        Time   = (Get-Date)
        Status = "Online"
    }
}

This produces an object with three properties.

Callers can sort, filter, export, or pipe it:

Get-ServerStatus "web01" | Select-Object Server, Status

7. Returning Arrays and Collections¶

If you want to return a collection, output each item individually:

function Get-Evens {
    foreach ($n in 1..10) {
        if ($n % 2 -eq 0) {
            $n
        }
    }
}

Output:

2
4
6
8
10

The caller receives an array of even numbers.

8. Returning Nothing¶

To return nothing, output nothing.

Example¶

function Do-Nothing {
    # no output
}

Calling:

$result = Do-Nothing
$result

Produces no output.

9. Summary: How to Return Objects Properly¶

Returning objects properly is essential for writing functions that behave like real PowerShell cmdlets and integrate cleanly into pipelines.