Scopes vs Session States (+ runspaces)

[ohads-MSFT]

Type of issue

Missing information

Feedback

The scope docs mention session state but don't explain what it is (or even reference docs to that effect):
https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_scopes?view=powershell-7.4

A quick search turned up the following docs (which are titled as to be specific for Windows PowerShell):
https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/windows-powershell-session-state?view=powershell-7.4
However, they refer to the session state as a configuration/data/information holder, which doesn't explain how session state can be "linked" to the global scope (to use the language of the above scope docs). Also, they refer to PowerShell runspaces which aren't documented at all as far as I can tell (I could only find this archived blog post: https://devblogs.microsoft.com/scripting/beginning-use-of-powershell-runspaces-part-1/).

Finally, the Import-Module docs (specifically for the Scope parameter) are possibly the most confusing of all:
https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/import-module?view=powershell-7.4
These docs repeatedly mix scopes and session states as if they were interchangeable (which would contradict the other docs). For example:

By default, when Import-Module cmdlet is called from the command prompt, script file, or scriptblock, all the commands are imported into the global session state. You can use the -Scope Local parameter to import module content into the script or scriptblock scope.

Page URL

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_scopes?view=powershell-7.4

Content source URL

https://github.com/MicrosoftDocs/PowerShell-Docs/blob/main/reference/7.4/Microsoft.PowerShell.Core/About/about_Scopes.md

Author

@sdwheeler

Document Id

42772fd1-35e3-2672-05b1-3e5cd9c31ecf

[sdwheeler]

@ohads-MSFT I think you are trying to make this more complicated than it is. However, I understand some of the confusion. You are not the first to ask for clarification. We need to be more precise with some of the descriptions.

One of the points of confusion is around the definition of a session. In the beginning (when most of the documentation was created), the lifetime of a session was the same as the lifetime of the PowerShell host process (powershell.exe). And the process had one Runspace.

Runspaces are an instance of the PowerShell engine that executes code.

• Have a session state (metadata about the state)
• Contain a hierarchy of scopes
  • Scopes contain variables, aliases, functions, etc.
  • Scopes don't contain code - the code is linked to a scope in the hierarchy
  • Modules create parallel scope containers linked to the scope in which they were imported
    • Variables, aliases, functions, etc. exported by the module are available starting at the scope-level in which they are imported
    • Variables, aliases, functions, etc. not exported are only available within the module scope container
    • Functions in the module scope can access items in the scope in which they were imported
    • Modules have their own session state
• When code running in a runspace references a scoped item, it searches the scope hierarchy it has access to looking for a name match. If it doesn't exist, a new item is created in the current scope. If it finds a match, the item is copied to the current scope.

Things get more complicated because a PowerShell host (pwsh.exe or powershell.exe) can have multiple runspaces. Each runspace has its own session state and scope containers. Session state and scopes can't be accessed across runspace instances.

This -Scope parameter of Import-Module controls which scope in the hierarchy that the imported module is linked to. By default modules are linked to the global scope of the runspace. Using -Scope Local links the module to the caller's current scope.

[mklement0]

Let me offer something I've written up for my own notes, which may be helpful to some:

• It aims to provide a top-down ontology of PowerShell's entities.
• It uses both official terminology and introduces a few custom terms that either have no official name yet or as alternatives to the existing names.
• It points out notable pitfalls.

---

PowerShell Ontology

• A runspace is a managed (i.e. .NET) thread that runs PowerShell cmdlets and source code via an instance of the PowerShell engine, the System.Management.Automation.PowerShell .NET class.

• A given process can host multiple runspaces simultaneously.

• Any .NET application can host runspaces, via the PowerShell SDK, available via NuGet packages.

• A stand-alone PowerShell installation comes with a terminal-based host application that provides an interactive shell as well as support for command line-based execution of PowerShell code; it is known as the PowerShell CLI (powershell.exe for Windows PowerShell, pwsh for PowerShell (Core) 7+)

• By default, an interactive shell session has only one runspace, but creation of (often transitory) additional ones is possible, most idiomatically and simply via ForEach-Object -Parallel and Start-ThreadJob in PowerShell 7+, but also via direct use of the SDK (which is the only built-in option in Windows PowerShell). Additionally, out-of-process runspaces may be communicated with, using background jobs and PowerShell remoting, involving XML-based cross-process serialization (CLIXML).

• Note:

  • The term session is somewhat ambiguous, as it can refer to a PowerShell CLI process as a whole vs. a single runspace:
  • In the stricter sense, session is synonymous with runspace; only the latter term is used below.

• Inside each runspace, code runs inside scopes:

  • Each scope is a container for variables, functions, aliases, PowerShell drives, and, on an opt-in basis, imported modules. Note that invoking a binary cmdlet never creates a new scope (but can choose to modify the caller's scope).

  • Note that certain aspects of a runspace are invariably process-global, namely environment variables and types loaded from on-disk .NET assemblies as well as those compiled ad hoc with Add-Type -TypeDefinition

    • However, PowerShell class and enum definitions, which are housed in in-memory assemblies, while technically available process-wide, are effectively hidden from non-descendent scopes and other runspaces (this can be worked around, but is only safe to do for classes that are decorated with the v7.4+ [NoRunspaceAffinity()] attribute)

  • By contrast, the working directory, generalized to the concept of a current location in PowerShell (using PowerShell's provider model that also supports drives that aren't file-system drives), is a per-runspace concept. This amounts to a common pitfall when calling non-PowerShell in-process APIs, notably .NET and COM APIs: the latter operate on the process-level working directory, which usually differs from PowerShell's; such APIs should therefore always be called with full paths.

  • The initial scope in which all code execution inside a runspace starts is the one and only global scope (whose elements can be referred to via the $global: scope specifier or a -Scope Global argument in select cmdlets).
    Its elements are seen runspace-wide, but can be shadowed by elements of the same name in nested scopes.

  • Scopes are organized into scope domains (scope stacks), officially known under the ambiguous name session states" - for a discussion of this term, see about_Scopes is missing an important concept: internal "session states" #4288

  • There are two types of scope domains:

    • The one and only global (default, non-module) scope domain in which all non-module code runs.

    • Module scope domains, one of which exists for each loaded module (including dynamic modules) and inside of which each module's commands run.

  • The effective root of all scope domains is the single global scope: it is the actual root of the global scope domain, whereas it is merely visible (linked) to the module scope domains, which each have their own root scope (using the SDK directly, it is possible to not link modules to the global scope, but that doesn't happen in normal use).

    • This distinction (actual root vs. linked-to) usually doesn't matter, but does if you try to access the global scope with a numbered -Scope argument, which won't work in modules (e.g., Get-Variable -Scope 1 HOME from a module's root scope fails; -Scope Global works as usual, however).

    • The upshot is:

      • The only scope that both non-module and module code share access to is the global one, they otherwise do not see each other's scopes. This has far-reaching consequences, discussed below.
      • Modules can use their root scope to store private state, and making elements visible to outside callers requires exporting them.

  • Stacks (hierarchies) of scopes inside a given scope domain come from invocation of commands implemented in PowerShell code getting run in a child scope by default, possibly recursively; together, these nested child scopes can be called descendent scopes and, conversely, a given scope may have nested parent scopes, which together can be called ancestral scopes.

  • Most scopes are transient, i.e. they exist only for the duration of a given call; the exceptions are the global scope - which exists for an entire session - and the root scopes of loaded modules - which exists for the remainder of the session, unless modules are explicitly unloaded (with Remove-Module).

  • Descendent scopes by default can use (call or read) elements from their ancestral scopes, but modifying or adding elements to ancestral scopes requires explicit cross-scope access, such as via scope specifiers (e.g. $global:foo) or the -Scope parameter of cmdlets such as Set-Variable, Set-Alias, New-PSDrive, or Import-Module.

    • A notable pitfall is that assigning to a variable defined in an ancestral scope without an explicit scope specifier implicitly creates a local variable of the same name, which then shadows its ancestral counterpart(s).

    • Another perhaps surprising aspect is that functions always run in a (child) scope of their scope-domain of origin, which may or may not be the same as the caller's; the ramifications are spelled out below.

  • Inside a given scope domain, (non-)creation of child scopes works as follows:

    • Invocation of functions and scripts - either by direct invocation or invocation via &, the call operator, creates a child scope of the caller's scope.

    • By contrast, invocation via ., the dot-sourcing operator, runs them directly in the caller's scope, allowing modifying / adding to its elements - implicitly, this invocation mechanism is used by PowerShell's profiles for defining elements directly in the global scope, as well as inside modules to module-globally load helper scripts at import time.

  • The logic is different in cross-scope-domain calls to functions (by contrast, a script file getting invoked is always considered to be in the caller's scope domain):

    • Direct innovation / via & creates a child scope in the invoked function's scope domain of origin. Notably, a non-module caller calling a module's function results in the latter always running in a child scope of its origin module's root scope.

    • Similarly, dot-sourcing (. ) runs directly in the current scope of the function's scope domain of origin (this invocation form rarely makes sense across scope domains; if a function from a module is dot-sourced, it runs directly in the module's root scope).

    • A notable and highly unfortunate consequence is that functions if they happen to be defined in modules typically do not see the current scope of an outside caller (unless they run directly in the global scope, which is not typical), and therefore also do not see the latter's preference variables (whereas binary cmdlets always do) - see Need straightforward way to honor the caller's preference-variable values / inherited common parameters in functions defined in script modules PowerShell/PowerShell#4568 for a discussion.

[flibustier7seas]

Hi @sdwheeler ,

You mentioned that:

One of the points of confusion is around the definition of a session. In the beginning (when most of the documentation was created), the lifetime of a session was the same as the lifetime of the PowerShell host process (powershell.exe). And the process had one Runspace.

The documentation also states that:

• Global: The scope that's in effect when PowerShell starts or when you
  create a new session or runspace.

This suggests that a session and a runspace are distinct entities, each with its own scope (and therefore its own session state).

Could you please clarify how a session differs from a runspace and how they are related now?

Thanks in advance!

[sdwheeler]

In this context, a "new session" is a new instance of the PowerShell process (powershell.exe or pwsh.exe) with its default (new) runspace.

As mklement0 described, it is possible to create additional runspaces within the current session (instance of PowerShell).