On this page

Returning Objects Properly

Enrico Hochkoeppler Profile

By Enrico Hochkoeppler

Web Developer & TutoriaLibre Founder

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:


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:

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​

GoalCorrect ApproachReturn a single valueOutput the value directlyReturn multiple valuesOutput each value; PowerShell creates an arrayReturn structured dataUse [pscustomobject]Avoid polluting outputUse Write-Verbose, Write-Host, etc.Exit earlyUse return

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

Found this helpful? Share the knowledge...

... or support this project to keep it alive!

Buy Me a Coffee

Previous

Pipeline Input

Next

Error Handling & Debugging