Enhancing Your PowerShell Skills with Scope Management

Index

• Introduction
• What are scopes?
  • Global & script
  • Scope modifiers
• Using scopes in a module
• Using dot-sourcing
• Summary

Introduction

In PowerShell, we use variables to store information that we might use later on. Variables also make it easy to change values in multiple places by changing the value of the variable. We can store all kinds of data in variables.

However, when we move beyond just typing code in the console and start writing scripts, functions, and modules, we notice that variables start behaving a bit differently. We have entered the world of scopes. In this post, I will cover the basics of PowerShell variable scope and provide examples of how to use scoping in PowerShell scripts and modules.

What are scopes?

Scopes in PowerShell are a way to protect variables by defining where they live and where they can be accessed and changed. Understanding how these scopes work allows us to manipulate these protections effectively.

PowerShell has the following scopes available:

• Global: This scope is available when you open a PowerShell console or create a new runspace or session. All of PowerShell’s automatic and preference variables live in the global scope. Any variables, aliases, and functions defined in your PowerShell profile also live in the global scope.
• Script: This scope is created when you run a script. Variables defined in the script are only available within the script scope and not in the global or parent scope.
• Local: This is the current scope where a command or script is running. For example, variables defined in a script scope are considered to be in its local scope.
• Private: While not technically a scope, using private: can protect a variable’s visibility outside of the scope where the variable is defined.
• Function Scope: This scope is specific to the function in which the variable is defined. Variables are only accessible within that function.

Scopes work in a hierarchy, with the global scope being the parent scope. Variables defined in the global scope are automatically available to child scopes for viewing. However, variables defined in a child scope are not available to the parent scope.

PowerShell scoping follows a few basic rules:

• Nested Scopes: Scopes nest within each other. The outer scope is the parent scope, and any nested scopes are child scopes of that parent.
• Item Availability: An item is available in the scope where it is defined and to any child scopes unless explicitly made private.
• Item Modification: An item created in a scope can only be changed in the scope it was defined. Another item with the same name in a different scope may hide the original item, but it does not override or modify the original item.

Let’s take a look at how these rules translate in the real world.

Global & script

If we create a script (TestScriptScope.ps1) with the following content:

$UserName = "Bob"
$UserName

If we run this script, we see the name “Bob” on our screen, as expected. However, if we type in $UserName again in the console, we get no output. Why is that? The answer lies in scopes. We define $UserName in our script, and because the script scope is a child of the global scope (the scope we have in our console), $UserName is not available in the global scope.

$UserName

.\TestScriptScope.ps1
Bob

$UserName

But what about a reverse variant? We create a script (TestScriptScopeReverse.ps1) and use the following content:

$Message

If we define $Message = "This is a message from the Global-scope!" in our console session and then run our script, we see that the message we defined is shown on the screen. We defined the variable in the global scope (parent), making it available in the script scope (child). Also, notice that inside the script, we didn’t define $Message, so the value is purely from the global scope.

$Message = "This is a message from the Global-scope!"

.\TestScriptScopeReverse.ps1
This is a message from the Global-scope!

Scope modifiers

In the previous examples, we saw how a variable defined in the child script scope was not available to the global scope for reference. However, we can use scope modifiers to change the scope of the defined variable. A few scope modifiers include:

For example, I can use the $global: prefix on a variable inside a script to change the value of a variable that I have already defined in the global parent scope. We can test this by creating a script (ScopeModifierTest.ps1) with the following content:

$Global:Message = "And now it is another message."

In a this example, we define $Message with the value “This is a message from the Global-scope!”.

First, we take a look at that value, then we run our script (ScopeModifierTest.ps1), and finally, we check the value again. After running the script, the value of $Message that we set in the global scope is overwritten by the script.

$Message
This is a message from the Global-scope!

.\ScopeModifierTest.ps1

$Message
And now it is another message.

Using scopes in a module

A module is a set of files, or technically it could be just one file (a .psm1), in which we package cmdlets, functions, and other related components that have a similar function or purpose.

You can create a module yourself and may need to reference the same variable in different functions. By setting variables using the script scope in a module, the variables become shareable between the module’s functions. But first, let’s take a look at an example module where we don’t explicitly mention the script scope.

Function Get-HelloName {
    if ($name) {
        $greeting = "Hello, $name!"
    } else {
        $greeting = "Hello, World!"
    }
    
    $greeting
}
 
Function Set-HelloName {
    param(
        [Parameter(Mandatory)]
        [string]$HelloName
    )
    
    $name = $HelloName
}

Note that both functions reference the $name variable. However, since the variable is defined in separate functions, it is scoped only to that function. Setting the $name variable in the Set-HelloName function does not affect the $name variable in Get-HelloName. You can try this yourself by saving this code to a .psm1 file, importing it using the Import-Module command, and referencing the module filename.

## Import the module
Import-Module -Name .\HelloModule.psm1

## Run 'Get-HelloName' and get the set output
Get-HelloName
Hello, World!

## Run 'Set-HelloName' and set the Name to Universe'
Set-HelloName -HelloName "Universe"

## Run 'Get-HelloName' and get the same output as before
Get-HelloName
Hello, World!

If I wanted to scope the variable to be available to all functions in the module, I would add the $script: modifier to the $name variable. Below, I have added the updated contents of the module.

Function Get-HelloName {
    if ($script:name) {
        $greeting = "Hello, $script:name!"
    } else {
        $greeting = "Hello, World!"
    }
    
    $greeting
}
 
Function Set-HelloName {
    param(
        [Parameter(Mandatory)]
        [string]$HelloName
    )
    
    $script:name = $HelloName
}

If I re-import the module using the -Force parameter, I can now set the value of $name in one function and reference it in another.

Import-Module -Name .\HelloModule.psm1 -Force

## Run 'Get-HelloName' and get the set output
Get-HelloName
Hello, World!

## Run 'Set-HelloName' and set the Name to Universe'
Set-HelloName -HelloName "Universe"

## Run 'Get-HelloName' and get the same output as before
Get-HelloName
Hello, Universe!

Note how calling Set-HelloName shows the default message as the $script:name variable did not have a value. After calling the Set-HelloName function, the Get-HelloName function now displays a different value based on the name I passed. This behavior is expected as both functions are now referencing the same variable.

While this example module is simple, it could be very useful in a module where you want to share, for example, an API token between functions.

Using dot-sourcing

As shown in the examples above, scripts and functions have their own scope outside the global scope. Changes to variables are only affected in that scope unless you use a scope modifier to change the variable’s scope.

However, you can incorporate the scope of a script or function by using dot source notation. When the script runs in the current scope, any script variables are available in the current scope. You can use dot source notation by placing a dot/period (.) and a space before the script name.

To try this out, we create a script (TestDotSourcedScope.ps1) with the following content:

$TestOutput = "Let there be text!"

And we run our test:

$TestOutput

 . .\TestDotSourcedScope.ps1

Let there be text!

Initially, the value of $TestOutput in the global console scope is empty or $null, and the TestDotSourcedScope.ps1 file sets the value of $TestOutput. By using dot source notation, the script brings the variable value into the parent scope.

You can also use the call operator/ampersand (&) to run a script or function, and its scope will not be added to the current scope.

Summary

Understanding scoping in PowerShell is essential when writing scripts, modules, and functions. You might encounter scenarios where a variable has an unexpected value, which could be due to the variable inheriting from another scope. By using techniques such as module-level scoping and dot source notation, you can effectively manage variable scopes and build valuable PowerShell tools for your toolkit.