Automatic Variables Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
- .github/instructions/powershell-automatic-variables.instructions.md
- src/System.Management.Automation/engine/InitialSessionState.cs
- src/System.Management.Automation/help/HelpCommentsParser.cs
- src/Microsoft.PowerShell.Commands.Utility/commands/utility/ConvertTo-Html.cs
- test/powershell/Modules/Microsoft.PowerShell.Utility/New-Variable.Tests.ps1
Automatic variables in PowerShell are specialized variables created and maintained by the engine itself to store state information, execution context, and user preferences. These variables provide essential data to scripts and cmdlets without requiring explicit manual assignment by the user.
These guidelines outline the architectural implementation of built-in variables, their categorization into preference and state variables, and the mechanisms for their initialization within the PowerShell session lifecycle. For information on defining new variables, see the Variable Command Guidelines.
Sources: src/System.Management.Automation/engine/InitialSessionState.cs:1159-1170, src/System.Management.Automation/engine/InitialSessionState.cs:1186-1282
Architectural Overview of Variable Initialization
The PowerShell engine manages automatic variables primarily through the InitialSessionState and SessionStateInternal classes. During the creation of a runspace, a collection of predefined SessionStateVariableEntry objects is instantiated and bound to the global scope.
Initialization Flow
The following diagram illustrates the lifecycle of variable binding during runspace initialization:
Initialization involves setting engine-specific tokens, platform identifiers, and execution preferences before any user scripts or profiles are executed. This ensures a consistent environment for the engine's core logic.
Sources: src/System.Management.Automation/engine/InitialSessionState.cs:1159-1175, src/System.Management.Automation/engine/InitialSessionState.cs:1506-1526
Preference Variables
Preference variables allow users to customize the behavior of PowerShell. These are initialized with default values that dictate how the engine handles errors, debugging, verbose output, and confirmation prompts.
Common Preference Variables
| Variable Name | Default Value | Description |
|---|---|---|
$ConfirmPreference | High | Determines when PowerShell prompts for confirmation. |
$DebugPreference | SilentlyContinue | Controls the display of debugging messages. |
$ErrorActionPreference | Continue | Dictates how the engine responds to non-terminating errors. |
$ProgressPreference | Continue | Controls the display of progress bars. |
$VerbosePreference | SilentlyContinue | Controls the display of verbose messages. |
$WarningPreference | Continue | Controls the display of warning messages. |
$InformationPreference | SilentlyContinue | Controls the display of information messages. |
Sources: src/System.Management.Automation/engine/InitialSessionState.cs:1197-1240
State and Context Variables
State variables store information about the current execution environment, platform, and session status. Many of these are set as ReadOnly or Constant to prevent accidental modification that could destabilize the engine.
Platform Identifiers
The engine defines boolean flags to identify the operating system and runtime environment:
$IsLinux: True if running on a Linux-based OS.$IsMacOS: True if running on macOS.$IsWindows: True if running on Windows.$IsCoreCLR: True if running on the .NET Core runtime.
Sources: src/System.Management.Automation/engine/InitialSessionState.cs:1270-1294
Special Execution Variables
PowerShell tracks internal state using specific tokens and objects:
| Variable Name | Description |
|---|---|
$PSStyle | A constant object (PSStyle.Instance) controlling ANSI terminal output rendering. |
$OutputEncoding | An Encoding object used for piping data to native commands. |
$StackTrace | Stores the stack trace of the last error. |
$MyInvocation | Contains information about the command that started the current script or function. |
Sources: src/System.Management.Automation/engine/InitialSessionState.cs:1162-1185, src/Microsoft.PowerShell.Commands.Utility/commands/utility/ConvertTo-Html.cs:517-520
Variable Scope and Options
Automatic variables utilize ScopedItemOptions to define their behavior regarding modification and visibility.
ScopedItemOptions Usage
- Constant: Variables like
$PSStylecannot be changed or deleted. - ReadOnly: Variables like platform identifiers (
$IsWindows) can only be modified by the engine, not by user scripts. - AllScope: Ensures the variable is visible in all child scopes created within the session.
- Private: Used in restricted sessions to hide internal variables from the user while keeping them accessible to engine-internal commands.
Sources: src/System.Management.Automation/engine/InitialSessionState.cs:228-245, test/powershell/Modules/Microsoft.PowerShell.Utility/New-Variable.Tests.ps1:123-162
Visibility Control in Restricted Sessions
In restricted or "NoLanguage" sessions, the engine modifies the visibility of built-in variables to minimize the attack surface. Disallowed entries are either removed or set to SessionStateEntryVisibility.Private.
Usage in Help and Metadata
Automatic variables are also used within the help system and cmdlet metadata to manage context. For instance, the .REMOTEHELPRUNSPACE directive in help comments allows help content to be forwarded to a specific PSSession stored in a variable.
Sources: src/System.Management.Automation/help/HelpCommentsParser.cs:461-463, src/System.Management.Automation/help/HelpCommentsParser.cs:569-571
Conclusion
Automatic variables serve as the backbone of the PowerShell execution environment, providing a standardized way to access session state and influence engine behavior via preferences. Their integration into the InitialSessionState ensures that every runspace starts with a predictable and configurable context, while scoping options provide the necessary security and stability for both full and restricted language modes.