about_Ref

Article
12/13/2022

Short description

Describes how to create and use a reference type variable. You can use reference type variables to permit a function to change the value of a variable that is passed to it.

Long description

You can pass variables to functions by reference or by value.

When you pass a variable by value, you are passing a copy of the data.

In the following example, the function changes the value of the variable passed to it. In PowerShell, integers are value types so they are passed by value. Therefore, the value of $var is unchanged outside the scope of the function.

Function Test($data)
{
    $data = 3
}

$var = 10
Test -data $var
$var

In the following example, a variable containing a Hashtable is passed to a function. Hashtable is an object type so by default it is passed to the function by reference.

When passing a variable by reference, the function can change the data and that change persists after the function executes.

Function Test($data)
{
    $data.Test = "New Text"
}

$var = @{}
Test -data $var
$var

Name                           Value
----                           -----
Test                           New Text

The function adds a new key-value pair that persists outside of the function's scope.

Writing functions to accept reference parameters

You can code your functions to take a parameter as a reference, regardless of the type of data passed. This requires that you specify the parameters type as System.Management.Automation.PSReference, or [ref].

When using references, you must use the Value property of the System.Management.Automation.PSReference type to access your data.

Function Test([ref]$data)
{
    $data.Value = 3
}

To pass a variable to a parameter that expects a reference, you must type cast your variable as a reference.

Note

The brackets and parenthesis are BOTH required.

$var = 10
Test -data ([ref]$var)
$var

Passing references to .NET methods

Some .NET methods may require you to pass a variable as a reference. When the method's definition uses the keywords in, out, or ref on a parameter, it expects a reference.

[int] | Get-Member -Static -Name TryParse

Name     MemberType Definition
----     ---------- ----------
TryParse Method     static bool TryParse(string s, [ref] int result)

The TryParse method attempts to parse a string as an integer. If the method succeeds, it returns $true, and the result is stored in the variable you passed by reference.

PS> $number = 0
PS> [int]::TryParse("15", ([ref]$number))
True
PS> $number
15

References and scopes

References allow the value of a variable in the parent scope to be changed within a child scope.

# Create a value type variable.
$i = 0
# Create a reference type variable.
$iRef = [ref]0
# Invoke a scriptblock to attempt to change both values.
&{$i++;$iRef.Value++}
# Output the results.
"`$i = $i;`$iRef = $($iRef.Value)"

$i = 0;$iRef = 1

Only the reference type's variable was changed.

Share via