Purpose of @ in Looping Arrays?

The operator you're looking for documentation on consists not only of the @ but the ( and ) too - together they make up @(), also known as the array subexpression operator.

It ensures that the output from whatever pipeline or expression you wrap in it will be an array.

To understand why this is useful, we need to understand that PowerShell tends to flatten arrays! Let's explore this concept with a simple test function:

function Test-PowerShellArray {
  param(
    $Count = 2
  )

  while($count--){
    Get-Random
  }
}

This function is going to output a number of random numbers - $Count numbers, to be exact:

PS ~> Test-PowerShellArray -Count 5
652133605
1739917433
1209198865
367214514
1018847444

Let's see what type of output we get when we ask for 5 numbers:

PS ~> $numbers = Test-PowerShellArray -Count 5
PS ~> $numbers.GetType()

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     Object[]                                 System.Array

Alright, so the resulting output that we've stored in $numbers is of type [Object[]] - this means we have an array which fits objects of type Object (any type in .NET's type system ultimately inherit from Object, so it really just means we have an array "of stuff", it could contain anything).

We can try again with a different count and get the same result:

PS ~> $numbers = Test-PowerShellArray -Count 100
PS ~> $numbers.GetType()

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     Object[]                                 System.Array

So far so good - we collected multiple output values from a function and ended up with an array, all is as expected.

But what happens when we only output 1 number from the function:

PS ~> $numbers = Test-PowerShellArray -Count 1
PS ~> $numbers.GetType()

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     Int32                                    System.ValueType

Say what? Now we're getting System.Int32 - which is the type of the individual integer values - PowerShell noticed that we only received 1 output value and went "Only 1? I'm not gonna wrap this in an array, you can have it as-is"

For this reason exactly, you might want to wrap output that you intend to loop over (or in other ways use that requires it to be an array):

PS ~> $numbers = Test-PowerShellArray -Count 1
PS ~> $numbers.GetType()

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     Int32                                    System.ValueType

PS ~> $numbers = @(Test-PowerShellArray -Count 1) # @(...) saves the day
PS ~> $numbers.GetType()

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     Object[]                                 System.Array

It's an alternative syntax for declaring static arrays, but there are some key details to understanding the differences in syntax between them.

@() is the array sub-expression operator. This works similarly to the group-expression operator () or sub-expression operator $() but forces whatever is returned to be an array, even if only 0 or 1 element is returned. This can be used inline wherever an array or collection type is expected. For more information on these operators, read up on the Special Operators in the documentation for PowerShell.

The 1, 2, 3, 4 is the list-expression syntax, and can be used anywhere an array is expected. It is functionally equivalent to @(1, 2, 3, 4) but with some differences in behavior than the array subexpression operator.

@( Invoke-SomeCmdletOrExpression ) will force the returned value to be an array, even if the expression returns only 0 or 1 element.

# Array sub-expression
$myArray = @( Get-Process msedge )

Note this doesn't have to be a single cmdlet call, it can be any expression, utilizing the pipeline how you see fit. For example:

# We have an array of fruit
$fruit = 'apple', 'banana', 'apricot', 'cherry', 'a tomato ;)'

# Fruit starting with A
$fruitStartingWithA = @( $fruit | Where-Object { $_ -match '^a' } )

$fruitStartingWithA should return the following:

apple
apricot
a tomato ;)

There's another way to force an array type and I see it often mentioned on Stack Overflow as a cool trick (which it is), but with little context around its behavior.

You can use a quirk of the list-expression syntax to force an array type, but there are two key differences between this and using the array sub-expression operator. Prefixing an expression or variable with a comma , will force an array to be returned, but the behavior changes between the two. Consider the following example:

# Essentially the same as @( $someVar )
$myArray1 = , $someVar

# This behaves differently, read below
$myArray2 = , ( Invoke-SomeCmdletOrExpression )

@() or prefixing a variable with , will flatten (another word often used here is unroll) the resulting elements into a single array. But with an expression you have to use the group-expression operator if you use the comma-prefix trick. Due to how the grouped expression is interpreted you will end up with an array consisting of one element.

It will not flatten any resulting elements in this case.

Consider the Get-Process example above. If you have three msedge processes running, $myArray.Count will show a count of 3, and you can access the individual processes using the array-index accessor $myArray[$i]. But if you do the same with $myArray2 in the second list-expression example above, $myArray2.Count will return a count of 1. This is essentially now a multi-dimensional array with a single element. To get the individual processes, you would now need to do $myArray2[0].Count to get the process count, and use the array-index accessor twice to get an individual process:

$myArray2 = , ( Get-Process msedge )

$myArray2.Count # ======> 1

# I have 32 Edge processes right now
$myArray2[0].Count # ===> 32

# Get only the first msedge process
$myArray[0][0] # =======> Handles  NPM(K)    PM(K)      WS(K)     CPU(s)     Id  SI ProcessName
               # =======> -------  ------    -----      -----     ------     --  -- -----------
               # =======>     430      19   101216     138968      74.52   3500   1 msedge

This can be unclear at first because printing $myArray2 to the output stream will show the same output result as $myArray from the first example, and $myArray1 in the second example.

In short, you want to avoid using the comma-prefix trick when you want to use an expression, and instead use the array sub-expression @() operator as this is what it is intended for.

Note: There will be times when you want to define a static array of arrays but you will be using list-expression syntax anyways, so the comma-prefix becomes redundant. The only counterpoint here is if you want to create an array with an array in the first element to add more arrays to it later, but you should be using a generic List[T] or an ArrayList instead of relying on one of the concatenation operators to expand an existing array (+ or += are almost always bad ideas on non-numeric types).

Here is some more information about arrays in PowerShell, as well as the Arrays specification for PowerShell itself.