PowerShell Array Parameters [Complete Guide]

Sometimes, you might need to pass an array as a parameter to a function in PowerShell. In this tutorial, I will explain everything about PowerShell array parameters. We will explore how to use arrays as parameters in PowerShell functions with a few examples.

Table of Contents

PowerShell Array Parameters

In PowerShell, arrays are flexible—they can hold items of any type, including integers, strings, objects, or even other arrays.

To declare an array in PowerShell, you simply assign multiple values to a variable, separated by commas:

$myArray = 1, 2, 3, 4, 5

This line of code creates an array $myArray containing five integer elements.

Passing an Array to a Function in PowerShell

When you want to pass an array to a function in PowerShell, you don’t need to do anything special—just pass the array variable as you would any other parameter. Here’s an example of a function that accepts an array parameter:

function Show-ArrayContents {
    param([array]$numbers)
    foreach ($number in $numbers) {
        Write-Host $number
    }
}

$myArray = 1, 2, 3, 4, 5
Show-ArrayContents -numbers $myArray

In this example, the function Show-ArrayContents takes one parameter, $numbers, which is expected to be an array. The function then iterates over each item in the array and prints it to the host.

You can see the output in the screenshot below after I executed the PowerShell script using VS code.

Modifying PowerShell Arrays Within Functions

It’s important to understand that when you pass an array to a function, you are passing a reference to the original array. This means that if you modify the array within the function, those changes will be reflected outside the function as well. Here’s an example:

function Add-Element {
    param([array]$numbers)
    $numbers += 6
}

$myArray = 1, 2, 3, 4, 5
Add-Element -numbers $myArray
Write-Host $myArray

This will output 1 2 3 4 5 6 because the function Add-Element adds an element to the original array.

Returning Arrays from a PowerShell Function

Functions in PowerShell can also return arrays. This is useful when you need to generate a list of items based on some logic and then work with that list outside the function. Here’s an example:

function Get-MultiplesOfTwo {
    param([int]$maxNumber)
    $multiples = @()
    for ($i = 2; $i -le $maxNumber; $i += 2) {
        $multiples += $i
    }
    return $multiples
}

$multiplesOfTwo = Get-MultiplesOfTwo -maxNumber 10
Write-Host $multiplesOfTwo

This function returns an array of multiples of two up to the specified maximum number.

Advanced Array Parameters

PowerShell also allows you to define a parameter that can accept a single value or an array of values. This is done using the [object[]] type for the parameter. Here’s an example:

function Display-Messages {
    param([object[]]$messages)
    foreach ($message in $messages) {
        Write-Host $message
    }
}

Display-Messages -messages "Single message"
Display-Messages -messages "First message", "Second message"

In this case, Display-Messages can be called with either a single object or an array of objects.

Conclusion

In this PowerShell tutorial, I have explained everything in detail about PowerShell array parameters with examples.