Why and how are these two $null values different?
To complement PetSerAl's great answer with a pragmatic summary:
Commands that happen to produce no output do not return
$null
, but the[System.Management.Automation.Internal.AutomationNull]::Value
singleton, which can be thought of as an "array-valued$null
" or, to coin a term, null enumeration. It is sometimes also called "AutomationNull", for its type name.- Note that, due to PowerShell's unwrapping of collections, even a command that explicitly outputs an empty collection object such as
@()
has no output (unless enumeration is explicitly prevented, such as withWrite-Output -NoEnumerate
).
- Note that, due to PowerShell's unwrapping of collections, even a command that explicitly outputs an empty collection object such as
In short, this special value behaves like
$null
in scalar contexts, and like an empty array in enumeration contexts, notably in the pipeline, as the examples below demonstrate.
Caveats:
Passing
[System.Management.Automation.Internal.AutomationNull]::Value
as a cmdlet / function parameter value invariably converts it to$null
.- See GitHub issue #9150.
In PSv3+, even an actual (scalar)
$null
is not enumerated in aforeach
loop; it is enumerated in a pipeline, however - see bottom.In PSv2-, saving a null enumeration in a variable quietly converted it to
$null
and$null
was enumerated in aforeach
loop as well (not just in a pipeline) - see bottom.
# A true $null value:
$trueNull = $null
# An operation with no output returns
# the [System.Management.Automation.Internal.AutomationNull]::Value singleton,
# which is treated like $null in a scalar expression context,
# but behaves like an empty array in a pipeline or array expression context.
$automationNull = & {} # calling (&) an empty script block ({}) produces no output
# In a *scalar expression*, [System.Management.Automation.Internal.AutomationNull]::Value
# is implicitly converted to $null, which is why all of the following commands
# return $true.
$null -eq $automationNull
$trueNull -eq $automationNull
$null -eq [System.Management.Automation.Internal.AutomationNull]::Value
& { param($param) $null -eq $param } $automationNull
# By contrast, in a *pipeline*, $null and
# [System.Management.Automation.Internal.AutomationNull]::Value
# are NOT the same:
# Actual $null *is* sent as data through the pipeline:
# The (implied) -Process block executes once.
$trueNull | % { 'input received' } # -> 'input received'
# [System.Management.Automation.Internal.AutomationNull]::Value is *not* sent
# as data through the pipeline, it behaves like an empty array:
# The (implied) -Process block does *not* execute (but -Begin and -End blocks would).
$automationNull | % { 'input received' } # -> NO output; effectively like: @() | % { 'input received' }
# Similarly, in an *array expression* context
# [System.Management.Automation.Internal.AutomationNull]::Value also behaves
# like an empty array:
(@() + $automationNull).Count # -> 0 - contrast with (@() + $trueNull).Count, which returns 1.
# CAVEAT: Passing [System.Management.Automation.Internal.AutomationNull]::Value to
# *any parameter* converts it to actual $null, whether that parameter is an
# array parameter or not.
# Passing [System.Management.Automation.Internal.AutomationNull]::Value is equivalent
# to passing true $null or omitting the parameter (by contrast,
# passing @() would result in an actual, empty array instance).
& { param([object[]] $param)
[Object].GetMethod('ReferenceEquals').Invoke($null, @($null, $param))
} $automationNull # -> $true; would be the same with $trueNull or no argument at all.
The [System.Management.Automation.Internal.AutomationNull]::Value
documentation states:
Any operation that returns no actual value should return
AutomationNull.Value
.
Any component that evaluates a Windows PowerShell expression should be prepared to deal with receiving and discarding this result. When received in an evaluation where a value is required, it should be replaced with
null
.
PSv2 vs. PSv3+, and general inconsistencies:
PSv2 offered no distinction between [System.Management.Automation.Internal.AutomationNull]::Value
and $null
for values stored in variables:
Using a no-output command directly in a
foreach
statement / pipeline did work as expected - nothing was sent through the pipeline / theforeach
loop wasn't entered:Get-ChildItem nosuchfiles* | ForEach-Object { 'hi' } foreach ($f in (Get-ChildItem nosuchfiles*)) { 'hi' }
By contrast, if a no-output commands was saved in a variable or an explicit
$null
was used, the behavior was different:# Store the output from a no-output command in a variable. $result = Get-ChildItem nosuchfiles* # PSv2-: quiet conversion to $null happens here # Enumerate the variable. $result | ForEach-Object { 'hi1' } foreach ($f in $result) { 'hi2' } # Enumerate a $null literal. $null | ForEach-Object { 'hi3' } foreach ($f in $null) { 'hi4' }
PSv2: all of the above commands output a string starting with
hi
, because$null
is sent through the pipeline / being enumerated byforeach
:
Unlike in PSv3+,[System.Management.Automation.Internal.AutomationNull]::Value
is converted to$null
on assigning to a variable, and$null
is always enumerated in PSv2.PSv3+: The behavior changed in PSv3, both for better and worse:
Better: Nothing is sent through the pipeline for the commands that enumerate
$result
: Theforeach
loop is not entered, because the[System.Management.Automation.Internal.AutomationNull]::Value
is preserved when assigning to a variable, unlike in PSv2.Possibly Worse:
foreach
no longer enumerates$null
(whether specified as a literal or stored in a variable), so thatforeach ($f in $null) { 'hi4' }
perhaps surprisingly produces no output.
On the plus side, the new behavior no longer enumerates uninitialized variables, which evaluate to$null
(unless prevented altogether withSet-StrictMode
).
Generally, however, not enumerating$null
would have been more justified in PSv2, given its inability to store the null-collection value in a variable.
In summary, the PSv3+ behavior:
takes away the ability to distinguish between
$null
and[System.Management.Automation.Internal.AutomationNull]::Value
in the context of aforeach
statementthereby introduces an inconsistency with pipeline behavior, where this distinction is respected.
For the sake of backward compatibility, the current behavior cannot be changed. This comment on GitHub proposes a way to resolve these inconsistencies for a (hypothetical) potential future PowerShell version that needn't be backward-compatible.
When you return a collection from a PowerShell function, by default PowerShell determines the data type of the return value as follows:
- If the collection has more than one element, the return result is an array. Note that the data type of the return result is System.Array even if the object being returned is a collection of a different type.
- If the collection has a single element, the return result is the value of that element, rather than a collection of one element, and the data type of the return result is the data type of that element.
- If the collection is empty, the return result is $null
$l_t = @()
assigns an empty array to $l_t.
$l_t2 = emptyArray
assigns $null to $l_t2, because the function emptyArray returns an empty collection, and therefore the return result is $null.
$l_t2 and $l_t3 are both null, and they behave the same way. Since you've pre-declared $l_t as an empty array, when you add either $l_t2 or $l_t3 to it, either with the += operator or the addToArray function, an element whose value is **$null* is added to the array.
If you want to force the function to preserve the data type of the collection object you're returning, use the comma operator:
PS> function emptyArray {,@()}
PS> $l_t2 = emptyArray
PS> $l_t2.GetType()
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True Object[] System.Array
PS> $l_t2.Count
0
Note: The empty parentheses after emtpyArray in the function declaration is superfluous. You only need parentheses after the function name if you're using them to declare parameters.
An interesting point to be aware of is that the comma operator doesn't necessarily make the return value an array.
Recall that as I mentioned in the first bullet point, by default the data type of the return result of a collection with more than one element is System.Array regardless of the actual data type of the collection. For example:
PS> $list = New-Object -TypeName System.Collections.Generic.List[int]
PS> $list.Add(1)
PS> $list.Add(2)
PS> $list.Count
2
PS> $list.GetType()
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True List`1 System.Object
Note that the data type of this collection is List`1, not System.Array.
However, if you return it from a function, within the function the data type of $list is List`1, but it's returned as a System.Array containing the same elements.
PS> function Get-List {$list = New-Object -TypeName System.Collections.Generic.List[int]; $list.Add(1); $list.Add(2); return $list}
PS> $l = Get-List
PS> $l.Count
2
PS> $l.GetType()
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True Object[] System.Array
If you want the return result to be a collection of the same data type as the one within the function that you're returning, the comma operator will accomplish that:
PS> function Get-List {$list = New-Object -TypeName System.Collections.Generic.List[int]; $list.Add(1); $list.Add(2); return ,$list}
PS> $l = Get-List
PS> $l.Count
2
PS> $l.GetType()
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True List`1 System.Object
This isn't limited to array-like collection objects. As far as I've seen, any time PowerShell changes the data type of the object you're returning, and you want the return value to preserve the object's original data type, you can do that by preceding the object being returned with a comma. I first encountered this issue when writing a function that queried a database and returned a DataTable object. The return result was an array of hashtables instead of a DataTable. Changing return $my_datatable_object
to return ,$my_datatable_object
made the function return an actual DataTable object.
In particular, is
$l_t2
really$null
or not?
$l_t2
is not $null
, but a [System.Management.Automation.Internal.AutomationNull]::Value
. It is a special instance of PSObject
. It is returned when a pipeline returns zero objects. That is how you can check it:
$a=&{} #shortest, I know, pipeline, that returns zero objects
$b=[System.Management.Automation.Internal.AutomationNull]::Value
$ReferenceEquals=[Object].GetMethod('ReferenceEquals')
$ReferenceEquals.Invoke($null,($a,$null)) #returns False
$ReferenceEquals.Invoke($null,($a,$b)) #returns True
I call ReferenceEquals
thru Reflection to prevent conversion from AutomationNull
to $null by PowerShell.
$l_t1 -eq $null
returns nothing
For me it returns an empty array, as I expect from it.
$l_t2.count
returns 0
It is a new feature of PowerShell v3:
You can now use Count or Length on any object, even if it didn’t have the property. If the object didn’t have a Count or Length property, it will will return 1 (or 0 for $null). Objects that have Count or Length properties will continue to work as they always have.
PS> $a = 42 PS> $a.Count 1
And why does
$l_t2
suddenly seem to become "more$null
" when it gets passed in the the functionaddToArray
as a parameter???????
It seems that PowerShell converts AutomationNull
to $null
in some cases, like calling .NET methods. In PowerShell v2, even when saving AutomationNull
to a variable it gets converted to $null
.