Powershell "private" scope seems not useful at all
Private scope can be useful when writing a function that invokes a user-supplied callback. Consider this simple example:
filter Where-Name {
param(
[ScriptBlock]$Condition
)
$FirstName, $LastName = $_ -split ' '
if(&$Condition $FirstName $LastName) {
$_
}
}
Then, if someone calls it like this:
$FirstName = 'First2'
'First1 Last1', 'First2 Last2', 'First3 Last3' |
Where-Name {param($a, $b) $a -eq $FirstName}
they'll expect to see only the First2 Last2
row, but actually this will print all three rows.
This is because of a collision on the $FirstName
variable.
To prevent such collisions, you can declare variables in Where-Name
as private:
filter Where-Name {
param(
[ScriptBlock]$private:Condition
)
$private:FirstName, $private:LastName = $_ -split ' '
if(&$Condition $FirstName $LastName) {
$_
}
}
Now $FirstName
in Where-Name
does not hide $FirstName
in the outer scope when referenced from the $Condition
script block.
Note:
* This answer explains why the OP's code behaves the way it does (and that it behaves as designed); additionally, it provides some general information about variable scopes in PowerShell.
* For an important real-world use of scope private
, see PetSerAl's helpful answer.
Your first snippet prints:
variable a contains
variable a contains 2
Your second snippet prints:
variable a contains 1
variable a contains 2
In the first snippet, using scope private
causes the parent (script) scope's a
variable to be hidden from the child (function) scope, as designed, so the first output line shows that $a
has no value
(an undefined variable has value $null
, which evaluates to the empty string in a string context).
In the second snippet, by contrast, without the private
scope modifier, variable a
from the parent scope is visible to the child scope.
In PowerShell, functions execute in child scopes by default.
Therefore, in both snippets above, assigning to variable a
inside the function implicitly creates a local a
variable there, whose scope is limited to the enclosing function.
In other words:
- Assigning to
$a
in the function creates a function-local variable named$a
, which then shadows (hides) the script-level$a
variable (if it wasn't already hidden by having been declared as$private:a
) - though note that local in PowerShell means that child scopes do see its value; see next section. - On leaving the function,
$a
again has its original, script-level value.
General information about variable scopes in PowerShell
Unless a variable is explicitly hidden with scope
private
, descendant scopes can see that variable and read its value using the variable name without a scope qualifier (e.g.,$a
) or the need forGet-Variable -Scope
.- Note that while descendant scopes do not see the values of variables created with
$private:
by default, they can still refer to them with relative cross-scope access, usingGet-Variable -Scope
orSet-Variable -Scope
.
Non-relative scope modifiers ($script
,$global
,$local
) generally do not work - except if the reference happens in the same scope in which the private variable was created and the scope modifier happens to effectively target that same scope, which is always true for$local:privateVarName
, for instance.
- Note that while descendant scopes do not see the values of variables created with
Assigning to an unqualified variable, however, implicitly creates a new variable in the current (
local
) scope, which can shadow a variable of the same name in an ancestral scope.- That is,
$a = 2
is implicitly the same as$local:a = 2
.
- That is,
To explicitly get / modify a variable in an ancestral scope, use
Get-Variable / Set-Variable -Scope <n> <name>
, where<n>
represents the scope level, with0
representing the current scope,1
the parent scope, and so on.
Note thatGet-Variable
returns a[System.Management.Automation.PSVariable]
instance by default, so in order to get only the value, access its.Value
property, or use the-ValueOnly
switch, which only returns the value to begin with.In functions and trap handlers, before creating a local copy of a variable, you can alternatively modify a variable in the most immediate ancestral scope where it is defined as follows:
([ref] $var).Value = ...
- (If and once a local variable by the same name is created, the above will modify only the local variable, however.)
Variables in the script scope and the global scope can also be accessed - and modified - by using the
$script:
and$global:
scope modifiers; e.g.,$script:a
and$global:a
.
Note that$script:
refers to the (immediately) enclosing script file's top-level scope.Modules each have their own scope domain linked only to the global scope. That is, modules see outside variables only from the global scope, not from a caller in any other scope, such as from a script; this can cause unexpected behavior with preference variables, as discussed in this GitHub issue.
Declaring a variable with
Set-Variable -Option AllScope
allows it to be read and modified in any descendant scope without needing to qualify the name; to put it differently: only a single variable by that name exists then, which any scope can directly read and write using the unqualified variable name.Without a separate
-Scope
parameter,-Option AllScope
is applied to the variable in the current scope (e.g., the script scope at the script's top level, a function's local scope inside a function). Thus, to safely create a script-global variable that you can access unqualified for reading and writing, useSet-Variable -Scope Script -Option AllScope
.-Scope Global
is distinct from-Option AllScope
: while-Scope Global
creates a globally accessible variable, reading it may, and modifying it does, require the$global:
scope modifier. Also note that a global variable is session-global, so it persists even after the script that defined it has terminated.By combining
-Scope Global
with-Option AllScope
you effectively create a session-global singleton variable that can be read and written from any scope without qualifier; as stated, however, such a variable lives on even after your script exits.