Powershell arguments by reference - powershell

Question

My understanding is that a complex object like a hash table is always passed by reference, while simple objects like strings or booleans are passed by value. I have been using this "fact" to do dependency injection with functions, and it has seemed to work until I need to pass the dependency on to a further function.
So I decided to do a simplified test to see where things are going wrong. And now even the dependency injection seems not to work. In this code, my expectation was that since I initially define $state as the return value from Primary in it's "Initialize" mode, I could then simply pass that on to further functions by reference, and when looking at $state at completion I would see all four times, as well as the id.
function Primary {
param (
[parameter(Mandatory=$true,
ParameterSetName = 'initialize')]
[String]$id,
[parameter(Mandatory=$true,
ParameterSetName = 'process')]
[Hashtable]$state
)
if ($id) {
Write-Host 'initialize Primary'
$primary = [Ordered]#{}
$primary.Add('id', $id)
$primary.Add('primaryInit', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
Secondary -state:$primary -init
} else {
Write-Host 'process Primary'
$primary = $true
$state.Add('primaryProcess', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
Secondary -state:$state
}
return $primary
}
function Secondary {
param (
[parameter(ParameterSetName = 'initialize')]
[Switch]$init,
[parameter(Mandatory=$true)]
[Hashtable]$state
)
if ($init) {
Write-Host 'initialize Secondary'
$state.Add('secondaryInit', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
} else {
Write-Host 'process Secondary'
$state.Add('secondaryProcess', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
}
}
CLS
$state = Primary -id:'Test'
Primary -state:$state
CLS
foreach ($key in $state.Keys) {
Write-Host "$key $($state.$key)"
}
Write-Host
No such luck, I only see the primaryInit time. And yet, in my much more complex program, it seems as if I AM getting $state passed by reference. So, I wonder what is different in this very simple example, that it's not behaving as intended? Or am I misunderstanding what is happening, and some more in my production code I am creating a behavior that I misunderstand to be innate behavior?
I also tried an even more simplified version, to remove the part calling functions from within functions.
function ByReference {
param (
[Hashtable]$state
)
$state.Add('now', (Get-Date))
}
$state = [Ordered]#{
id = 'test'
}
ByReference $state
foreach ($key in $state.Keys) {
Write-Host "$key $($state.$key)"
}
This also shows $state being passed by Value, such that the changes aren't seen when looking at the variable in Main.
EDIT: Based on #Daniel 's link, I revised to
function Primary {
param (
[parameter(Mandatory=$true,
ParameterSetName = 'initialize')]
[String]$id,
[parameter(Mandatory=$true,
ParameterSetName = 'process')]
[Ref]$state
)
if ($id) {
Write-Host 'initialize Primary'
$primary = [Ordered]#{}
$primary.Add('id', $id)
$primary.Add('primaryInit', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
Secondary -state:$primary -init
} else {
Write-Host 'process Primary'
$primary = $state
$state.Add('primaryProcess', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
Secondary -state:$state
}
return $primary
}
function Secondary {
param (
[parameter(ParameterSetName = 'initialize')]
[Switch]$init,
[parameter(Mandatory=$true)]
[Ref]$state
)
if ($init) {
Write-Host 'initialize Secondary'
$state.Add('secondaryInit', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
} else {
Write-Host 'process Secondary'
$state.Add('secondaryProcess', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
}
}
CLS
$state = Primary -id:'Test'
Primary -state:$state
CLS
foreach ($key in $state.Keys) {
Write-Host "$key $($state.$key)"
}
Write-Host
And this is still not showing anything but the very first time. That said, I can get this to work.
Function Test($data)
{
$data.Test = "New Text"
}
$var = #{}
Test -data $var
$var
Which got me thinking maybe this only works if you aren't using a param() block. So I tried removing the param block and using function Primary ([String]$id, [Ref]$state) {}. Still no joy.
The other thing I notice is that all the examples create the variable in main. I am creating the variable in the init mode of my method. Could it be that the variable needs to be global or script scope? I tried using scope modifiers when initially defining $primary but thiat isn't working either.
EDIT 2: So it seems the key is you must not type the byRef argument.
So this works.
function Test-Primary {
param (
[String]$id,
$state = [Ordered]#{}
)
if ($id) {
Write-Host 'initialize Primary'
$state.Add('id', $id)
$state.Add('primaryInit', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
Test-Secondary -state:$state -init
return $state
} else {
Write-Host 'process Primary'
$state.Add('primaryProcess', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
Test-Secondary -state:$state
}
}
function Test-Secondary {
param (
[Switch]$init,
$state
)
if ($init) {
Write-Host 'initialize Secondary'
$state.Add('secondaryInit', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
} else {
Write-Host 'process Secondary'
$state.Add('secondaryProcess', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
}
}
CLS
$state = Test-Primary -id:'Test'
Test-Primary -state:$state
CLS
foreach ($key in $state.Keys) {
Write-Host "$key $($state.$key)"
}
Write-Host
A little odd, as I would wish that you could either specifically type the parameter, so ensure you don't change type, but I guess that's just another reason to start using Classes. Functions are "sloppy" because they are intended for down and dirty stuff I guess.
EDIT: OK, progress, but it seems I am still trying to do something odd. I have come to the conclusion that, when doing these multi-"mode" functions where one mode returns a value and the other mode uses a passed by reference variable, you need a different name for the return value. Add to that I need for [Ref] both when calling the function and declaring the variable in the function. I then assumed that I could use [Ref] even with a hash table, as a way to remind myself that this is a by reference value. And then the need for .Value to actually deal with the variable got me to this.
function Test-Primary {
param (
[String]$id,
[Ref]$state
)
if ($id) {
Write-Host 'initialize Primary'
$testPrimary = [Ordered]#{}
$testPrimary.Add('id', $id)
$testPrimary.Add('primaryInit', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
Test-Secondary -state:([Ref]$testPrimary) -init
return $testPrimary
} else {
Write-Host 'process Primary'
$state.Value.Add('primaryProcess', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
Test-Secondary -state:$state
}
}
function Test-Secondary {
param (
[Switch]$init,
[Ref]$state
)
if ($init) {
Write-Host 'initialize Secondary'
$state.Value.Add('secondaryInit', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
} else {
Write-Host 'process Secondary'
$state.Value.Add('secondaryProcess', (Get-Date))
Start-Sleep -s:(Get-Random -Minimum 1 -Maximum 5)
}
}
CLS
$state = Test-Primary -id:'Test'
Test-Primary -state:([Ref]$state)
CLS
foreach ($key in $state.Keys) {
Write-Host "$key $($state.$key)"
}
Write-Host

Answer 1

As you figured out hash tables don't need to be passed by reference to change its properties. But to show you how [Ref] actually works, take a look at the following example:
function Test-RefParameter
{
[CmdletBinding()]
param
(
[Parameter(Mandatory = $true)]
[Ref] $Output
)
$Output.Value = "output from test"
}
$testVar = "before test"
Write-Information "Current value: '$testVar'" -InformationAction Continue
Test-RefParameter -Output ([Ref]$testVar)
Write-Information "Current value: '$testVar'" -InformationAction Continue
Which displays:
Current value: 'before test'
Current value: 'output from test'
So the key is to use .Value when assigning the value to the [Ref] parameter