关于自动变量
简短说明
描述存储 PowerShell 的状态信息的变量。 这些变量由 PowerShell 创建和维护。
长说明
从概念上讲,这些变量被视为只读的。 即使 可以 将其写入,但为了向后兼容, 不应 将其写入。
下面是 PowerShell 中的自动变量列表:
$$
包含会话收到的最后一行中的最后一个标记。
$?
包含最后一个命令的执行状态。 如果最后一个命令成功,则包含 True ;如果失败,则包含 False 。
对于在管道中的多个阶段运行的 cmdlet 和高级函数(例如在 和 end
块this.WriteError()
中process
),调用 或 $PSCmdlet.WriteError()
在任何时间点分别设置为 $?
False,就像 和 $PSCmdlet.ThrowTerminatingError()
一样this.ThrowTerminatingError()
。
cmdlet Write-Error
在执行后始终立即将其设置为 $?
False ,但对于调用它的函数,该 cmdlet 不会设置为 $?
False :
function Test-WriteError
{
Write-Error "Bad"
$? # $false
}
Test-WriteError
$? # $true
对于后一个目的, $PSCmdlet.WriteError()
应改用 。
对于本机命令 (可执行文件) ,$?
当 为 0 时$LASTEXITCODE
设置为 True,如果 为任何其他值,则$LASTEXITCODE
设置为 False。
注意
在 PowerShell 7(在括号 (...)
内包含 语句)之前,子表达式语法 $(...)
或数组表达式 @(...)
始终重置 $?
为 True,以便显示为 (Write-Error)
$?
True。
PowerShell 7 中已对此进行了更改,因此,这将 $?
始终反映这些表达式中最后一个命令运行的实际成功。
$^
包含会话收到的最后一行中的第一个标记。
$_
与 $PSItem
相同。 包含管道对象中的当前 对象。 可以在对管道中的每个对象或所选对象执行操作的命令中使用此变量。
$args
包含传递给函数、脚本或脚本块的未声明参数的值数组。 创建函数时,可以使用 关键字 (keyword) 或在函数名称后添加逗号分隔的参数列表来声明param
参数。
在事件操作中 $Args
, 变量包含表示正在处理的事件的事件参数的对象。 此变量仅在事件注册命令的 块中 Action
填充。
还可以在返回的 PSEventArgs 对象的 Get-Event
SourceArgs 属性中找到此变量的值。
$ConsoleFileName
包含会话中最近使用的控制台文件 (.psc1
) 的路径。 使用 PSConsoleFile 参数启动 PowerShell 时,或使用 Export-Console
cmdlet 将管理单元名称导出到控制台文件时,将填充此变量。
使用不带参数的 Export-Console
cmdlet 时,它会自动更新会话中最近使用的控制台文件。 可以使用此自动变量来确定将更新的文件。
$Error
包含表示最新错误的错误对象的数组。
最近的错误是数组 $Error[0]
中的第一个错误对象。
若要防止将错误添加到数组中$Error
,请使用值为 Ignore 的 ErrorAction 通用参数。 有关详细信息,请参阅 about_CommonParameters。
$Event
包含一个 PSEventArgs 对象,该对象表示正在处理的事件。 此变量仅在事件注册命令的 块中 Action
填充,例如 Register-ObjectEvent
。 此变量的值与 cmdlet 返回的对象 Get-Event
相同。 因此,可以在脚本块中使用变量的属性Event
,例如 $Event.TimeGenerated
。Action
$EventArgs
包含一个 对象,该对象表示从正在处理的事件的 EventArgs 派生的第一个事件参数。 此变量仅在事件注册命令的 块中 Action
填充。
还可以在返回的 PSEventArgs 对象的 Get-Event
SourceEventArgs 属性中找到此变量的值。
$EventSubscriber
包含一个 PSEventSubscriber 对象,该对象表示正在处理的事件的事件订阅者。 此变量仅在事件注册命令的 块中 Action
填充。 此变量的值与 cmdlet 返回的对象 Get-EventSubscriber
相同。
$ExecutionContext
包含一个 EngineIntrinsics 对象,该对象表示 PowerShell 主机的执行上下文。 可以使用此变量查找 cmdlet 可用的执行对象。
$false
包含 False。 可以使用此变量在命令和脚本中表示 False ,而不是使用字符串“false”。 如果字符串转换为非空字符串或非零整数,则可以将其解释为 True 。
$foreach
包含枚举器 (非 ForEach 循环) 生成的值。 变量 $ForEach
仅在 ForEach
循环运行时存在;循环完成后会将其删除。
枚举器包含可用于检索循环值和更改当前循环迭代的属性和方法。 有关详细信息,请参阅 使用枚举器。
$HOME
包含用户主目录的完整路径。 此变量等效 "$env:homedrive$env:homepath"
于 Windows 环境变量,通常 C:\Users\<UserName>
为 。
$Host
包含一个 对象,该对象表示 PowerShell 的当前主机应用程序。 可以使用此变量在命令中表示当前主机,或者显示或更改主机的属性,例如 $Host.version
、 $Host.CurrentCulture
或 $host.ui.rawui.setbackgroundcolor("Red")
。
$input
包含枚举器,该枚举器枚举传递给函数的所有输入。 变量 $input
仅适用于函数和脚本块 (这些) 未命名函数。
在没有 、
Process
或End
块的Begin
函数中,$input
变量枚举函数的所有输入的集合。在 块中
Begin
$input
, 变量不包含任何数据。在 块中
Process
$input
, 变量包含当前在管道中的 对象。在 块中
End
$input
, 变量枚举函数的所有输入的集合。注意
不能在同一函数或脚本块的 Process 块和 End 块内使用
$input
变量。
由于 $input
是枚举器,因此访问它的任何属性都会导致 $input
不再可用。 可以存储在 $input
另一个变量中以重复使用属性 $input
。
枚举器包含可用于检索循环值和更改当前循环迭代的属性和方法。 有关详细信息,请参阅 使用枚举器。
$IsCoreCLR
包含 $True
当前会话是否在 .NET Core 运行时 (CoreCLR) 上运行。 否则包含 $False
。
$IsLinux
包含 $True
当前会话是否在 Linux 操作系统上运行。
否则包含 $False
。
$IsMacOS
包含 $True
当前会话是否在 MacOS 操作系统上运行。
否则包含 $False
。
$IsWindows
包含 $TRUE
当前会话是否在 Windows 操作系统上运行。 否则包含 $FALSE
。
$LastExitCode
包含运行的最后一个基于 Windows 的程序的退出代码。
$Matches
变量 Matches
适用于 -match
和 -notmatch
运算符。
将标量输入提交到 -match
或 -notmatch
运算符,并且其中一个检测到匹配时,它们将返回一个布尔值,并使用匹配的任何字符串值的哈希表填充 $Matches
自动变量。 将 $Matches
正则表达式与 运算符一起使用 -match
时,还可以使用捕获填充哈希表。
有关 运算符的详细信息 -match
,请参阅 about_Comparison_Operators。 有关正则表达式的详细信息,请参阅 about_Regular_Expressions。
$MyInvocation
包含有关当前命令的信息,例如名称、参数、参数值,以及有关如何启动、调用或调用命令的信息,例如调用当前命令的脚本的名称。
$MyInvocation
仅为脚本、函数和脚本块填充 。 可以使用当前脚本中返回的 System.Management.Automation.InvocationInfo 对象 $MyInvocation
中的信息,例如脚本 ($MyInvocation.MyCommand.Path
) 的路径和文件名,或者) (函数 $MyInvocation.MyCommand.Name
的名称来标识当前命令。 这对于查找当前脚本的名称特别有用。
从 PowerShell 3.0 开始, MyInvocation
具有以下新属性。
属性 | 说明 |
---|---|
PSScriptRoot | 包含调用的脚本的完整路径 |
当前命令。 此属性的值为 | |
仅在调用方为脚本时填充。 | |
PSCommandPath | 包含脚本的完整路径和文件名 |
调用当前命令的 。 此值的值 | |
仅当调用方为 时,才会填充 属性 | |
脚本。 |
$PSScriptRoot
与 和 $PSCommandPath
自动变量不同,自动变量的 $MyInvocation
PSScriptRoot 和 PSCommandPath 属性包含有关调用程序或调用脚本的信息,而不是当前脚本的信息。
$NestedPromptLevel
包含当前提示级别。 值为 0 表示原始提示级别。 值在进入嵌套级别时递增,退出时该值递减。
例如,使用 方法时,PowerShell 会提供嵌套的 $Host.EnterNestedPrompt
命令提示符。 在 PowerShell 调试器中到达断点时,PowerShell 还会显示嵌套的命令提示符。
输入嵌套提示时,PowerShell 会暂停当前命令,保存执行上下文,并递增变量的值 $NestedPromptLevel
。 若要创建其他嵌套命令提示符 (最多 128 个级别) 或返回到原始命令提示符,请完成命令,或键入 exit
。
变量 $NestedPromptLevel
有助于跟踪提示级别。 可以创建包含此值的替代 PowerShell 命令提示符,使其始终可见。
$null
$null
是包含 null 或空值的自动变量。 可以使用此变量来表示命令和脚本中不存在或未定义的值。
PowerShell 将 $null
视为具有值的对象,即作为显式占位符,因此可以使用 $null
来表示一系列值中的空值。
例如,当 包含在集合中时 $null
,它将计为 对象之一。
$a = "one", $null, "three"
$a.count
3
如果通过管道将 $null
变量传递给 ForEach-Object
cmdlet,它将为 $null
生成值,就像为其他对象生成值一样
"one", $null, "three" | ForEach-Object { "Hello " + $_}
Hello one
Hello
Hello three
因此,不能使用 $null
表示 无参数值。 参数值 将 $null
替代默认参数值。
但是,由于 PowerShell 将 $null
变量视为占位符,因此可以在如下所示的脚本中使用它,如果 $null
忽略 ,则不起作用。
$calendar = @($null, $null, "Meeting", $null, $null, "Team Lunch", $null)
$days = "Sunday","Monday","Tuesday","Wednesday","Thursday",
"Friday","Saturday"
$currentDay = 0
foreach($day in $calendar)
{
if($day -ne $null)
{
"Appointment on $($days[$currentDay]): $day"
}
$currentDay++
}
Appointment on Tuesday: Meeting
Appointment on Friday: Team lunch
$PID
包含承载当前 PowerShell 会话的进程的进程标识符 (PID) 。
$PROFILE
包含当前用户和当前主机应用程序的 PowerShell 配置文件的完整路径。 可以使用此变量在命令中表示配置文件。 例如,可以在命令中使用它来确定是否已创建配置文件:
Test-Path $PROFILE
或者,可以在命令中使用它来创建配置文件:
New-Item -ItemType file -Path $PROFILE -Force
可以在命令中使用它在 notepad.exe中打开配置文件:
notepad.exe $PROFILE
$PSBoundParameters
包含传递给脚本或函数的参数及其当前值的字典。 此变量仅在声明参数的范围(如脚本或函数)中具有值。 可以使用它来显示或更改参数的当前值,或者将参数值传递给另一个脚本或函数。
在此示例中, Test2 函数将 $PSBoundParameters
传递给 Test1 函数。 $PSBoundParameters
以键和值格式显示。
function Test1 {
param($a, $b)
# Display the parameters in dictionary format.
$PSBoundParameters
}
function Test2 {
param($a, $b)
# Run the Test1 function with $a and $b.
Test1 @PSBoundParameters
}
Test2 -a Power -b Shell
Key Value
--- -----
a Power
b Shell
$PSCmdlet
包含一个 对象,该对象表示正在运行的 cmdlet 或高级函数。
可以在 cmdlet 或函数代码中使用 对象的属性和方法来响应使用条件。 例如, ParameterSetName 属性包含正在使用的参数集的名称, ShouldProcess 方法将 WhatIf 和 Confirm 参数动态添加到 cmdlet。
有关自动变量的详细信息 $PSCmdlet
,请参阅 about_Functions_CmdletBindingAttribute 和 about_Functions_Advanced。
$PSCommandPath
包含正在运行的脚本的完整路径和文件名。 此变量在所有脚本中都有效。
$PSCulture
包含操作系统中当前正在使用的区域性的名称。 区域性确定数字、货币和日期等项的显示格式,并存储在 System.Globalization.CultureInfo 对象中。 使用 Get-Culture
显示计算机的区域性。 $PSCulture
包含 Name 属性的值。
$PSDebugContext
调试时,此变量包含有关调试环境的信息。 否则,它包含 null 值。 因此,可以使用它来指示调试器是否具有控制权。 填充时,它包含具有断点和 InvocationInfo 属性的 PsDebugContext 对象。 InvocationInfo 属性具有多个有用的属性,包括 Location 属性。 Location 属性指示正在调试的脚本的路径。
$PSHOME
包含 PowerShell 安装目录的完整路径,通常位于 $env:windir\System32\PowerShell\v1.0
Windows 系统中。 可以在 PowerShell 文件的路径中使用此变量。 例如,以下命令在概念帮助主题中搜索单词 变量:
Select-String -Pattern Variable -Path $pshome\*.txt
$PSItem
与 $_
相同。 包含管道对象中的当前 对象。 可以在对管道中的每个对象或所选对象执行操作的命令中使用此变量。
$PSScriptRoot
包含从中运行脚本的目录。
在 PowerShell 2.0 中,此变量仅在) (.psm1
脚本模块中有效。
从 PowerShell 3.0 开始,它在所有脚本中都有效。
$PSSenderInfo
包含有关启动 PSSession 的用户的信息,包括用户标识和原始计算机的时区。 此变量仅在 PSSession 中可用。
变量 $PSSenderInfo
包含用户可配置的属性 ApplicationArguments,默认情况下,该属性仅 $PSVersionTable
包含来自原始会话的 。 若要将数据添加到 ApplicationArguments 属性,请使用 cmdlet 的 New-PSSessionOption
ApplicationArguments 参数。
$PSUICulture
包含操作系统中当前正在使用的用户界面 (UI) 区域性的名称。 UI 区域性确定哪些文本字符串用于用户界面元素,例如菜单和消息。 这是系统的 System.Globalization.CultureInfo.CurrentUICulture.Name 属性的值。 若要获取系统的 System.Globalization.CultureInfo 对象,请使用 Get-UICulture
cmdlet。
$PSVersionTable
包含一个只读哈希表,该表显示有关当前会话中运行的 PowerShell 版本的详细信息。 该表包含以下项:
属性 | 说明 |
---|---|
PSVersion | PowerShell 版本号 |
PSEdition | 此属性的值为“Desktop” |
PowerShell 4 和更低版本以及 PowerShell | |
5.1 功能齐全的 Windows 版本。 | |
此属性的值为“Core” | |
PowerShell 6 及更高版本以及 PowerShell | |
减少占用空间版本的 PowerShell 5.1 | |
例如 Windows Nano Server 或 Windows IoT。 | |
GitCommitId | GitHub 中源文件的提交 ID, |
OS | 操作系统的说明 |
PowerShell 正在运行。 | |
平台 | 操作系统正在运行的平台 |
如果 Linux 和 macOS 上的值为 Unix。 | |
请参见 $IsMacOs 和 $IsLinux 。 |
|
PSCompatibleVersions | 兼容的 PowerShell 版本 |
使用当前版本 | |
PSRemotingProtocolVersion | PowerShell 远程版本 |
管理协议。 | |
SerializationVersion | 序列化方法的版本 |
WSManStackVersion | WS-Management 堆栈的版本号 |
$PWD
包含一个 path 对象,该对象表示当前目录的完整路径。
$Sender
包含生成此事件的对象。 此变量仅在事件注册命令的 Action 块中填充。 还可以在返回的 PSEventArgs 对象的 Get-Event
Sender 属性中找到此变量的值。
$ShellId
包含当前 shell 的标识符。
$StackTrace
包含最新错误的堆栈跟踪。
$switch
包含枚举器,而不是语句的结果 Switch
值。 变量 $switch
仅在 Switch
语句运行时存在;该变量在语句完成执行时 switch
将其删除。 有关详细信息,请参阅 about_Switch。
枚举器包含可用于检索循环值和更改当前循环迭代的属性和方法。 有关详细信息,请参阅 使用枚举器。
$this
在定义脚本属性或脚本方法的脚本块中 $this
,变量引用正在扩展的对象。
在自定义类中 $this
,变量引用类对象本身,允许访问类中定义的属性和方法。
$true
包含 True。 可以使用此变量在命令和脚本中表示 True 。
使用枚举器
$input
、 $foreach
和 $switch
变量都是用于循环访问其包含代码块处理的值的枚举器。
枚举器包含可用于推进或重置迭代或检索迭代值的属性和方法。 直接操作枚举器不被视为最佳做法。
在接受管道输入的函数中,最佳做法是将 Parameters 与 ValueFromPipeline 或 ValueFromPipelineByPropertyName 属性一起使用。
有关详细信息,请参阅 about_Functions_Advanced_Parameters。
MoveNext
MoveNext 方法将枚举器推进到集合的下一个元素。 如果枚举器已成功高级,MoveNext 将返回 True;如果枚举器已通过集合的末尾,则返回 False。
注意
返回的 MoveNext 的布尔值将发送到输出流。
可以通过键入输出或将其管道输出。[void]
$input.MoveNext() | Out-Null
[void]$input.MoveNext()
重置
Reset 方法将枚举器设置为其初始位置,该位置位于集合中的第一个元素之前。
当前
Current 属性获取集合或管道中枚举器当前位置的元素。
在调用 MoveNext 之前,Current 属性将继续返回相同的属性。
示例
示例 1:使用 $input 变量
在下面的示例中,访问 $input
变量将清除变量,直到下一次执行进程块。 使用 Reset 方法将 $input
变量重置为当前管道值。
function Test
{
begin
{
$i = 0
}
process
{
"Iteration: $i"
$i++
"`tInput: $input"
"`tAccess Again: $input"
$input.Reset()
"`tAfter Reset: $input"
}
}
"one","two" | Test
Iteration: 0
Input: one
Access Again:
After Reset: one
Iteration: 1
Input: two
Access Again:
After Reset: two
即使你没有访问变量, $input
进程块也会自动推进变量。
$skip = $true
function Skip
{
begin
{
$i = 0
}
process
{
"Iteration: $i"
$i++
if ($skip)
{
"`tSkipping"
$skip = $false
}
else
{
"`tInput: $input"
}
}
}
"one","two" | Skip
Iteration: 0
Skipping
Iteration: 1
Input: two
示例 2:在进程块外部使用$input
在进程块外部, $input
变量表示通过管道传入函数的所有值。
- 访问变量会
$input
清除所有值。 - Reset 方法重置整个集合。
- 从不填充 Current 属性。
- MoveNext 方法返回 false,因为集合无法高级。
- 调用 MoveNext 会
$input
清除变量。
- 调用 MoveNext 会
Function All
{
"All Values: $input"
"Access Again: $input"
$input.Reset()
"After Reset: $input"
$input.MoveNext() | Out-Null
"After MoveNext: $input"
}
"one","two","three" | All
All Values: one two three
Access Again:
After Reset: one two three
After MoveNext:
示例 3:使用 $input。Current 属性
通过使用 Current 属性,无需使用 Reset 方法即可多次访问当前管道值。 进程块不会自动调用 MoveNext 方法。
除非显式调用 MoveNext,否则永远不会填充 Current 属性。 可以在进程块内多次访问 Current 属性,而无需清除其值。
function Current
{
begin
{
$i = 0
}
process
{
"Iteration: $i"
$i++
"`tBefore MoveNext: $($input.Current)"
$input.MoveNext() | Out-Null
"`tAfter MoveNext: $($input.Current)"
"`tAccess Again: $($input.Current)"
}
}
"one","two" | Current
Iteration: 0
Before MoveNext:
After MoveNext: one
Access Again: one
Iteration: 1
Before MoveNext:
After MoveNext: two
Access Again: two
示例 4:使用 $foreach 变量
$input
与 变量不同,$foreach
变量在直接访问时始终表示集合中的所有项。 使用 Current 属性访问当前集合元素,并使用 Reset 和 MoveNext 方法更改其值。
注意
循环的 foreach
每次迭代都会自动调用 MoveNext 方法。
以下循环仅执行两次。 在第二次迭代中,集合在迭代完成之前移动到第三个元素。 第二次迭代后,现在不再有要循环访问的值,循环将终止。
MoveNext 属性不会影响选择循环访问集合 ($Num
) 的变量。
$i = 0
foreach ($num in ("one","two","three"))
{
"Iteration: $i"
$i++
"`tNum: $num"
"`tCurrent: $($foreach.Current)"
if ($foreach.Current -eq "two")
{
"Before MoveNext (Current): $($foreach.Current)"
$foreach.MoveNext() | Out-Null
"After MoveNext (Current): $($foreach.Current)"
"Num has not changed: $num"
}
}
Iteration: 0
Num: one
Current: one
Iteration: 1
Num: two
Current: two
Before MoveNext (Current): two
After MoveNext (Current): three
Num has not changed: two
使用 Reset 方法重置集合中的当前元素。 下面的示例将两次循环访问前两 个 元素,因为调用了 Reset 方法。 在前两个循环之后, if
语句将失败,循环正常循环访问所有三个元素。
重要
这可能会导致无限循环。
$stopLoop = 0
foreach ($num in ("one","two", "three"))
{
("`t" * $stopLoop) + "Current: $($foreach.Current)"
if ($num -eq "two" -and $stopLoop -lt 2)
{
$foreach.Reset() | Out-Null
("`t" * $stopLoop) + "Reset Loop: $stopLoop"
$stopLoop++
}
}
Current: one
Current: two
Reset Loop: 0
Current: one
Current: two
Reset Loop: 1
Current: one
Current: two
Current: three
示例 5:使用 $switch 变量
变量 $switch
的规则与 变量完全相同 $foreach
。
下面的示例演示了所有枚举器概念。
注意
请注意,NotEvaluated 大小写永远不会执行,即使 MoveNext 方法后没有break
语句。
$values = "Start", "MoveNext", "NotEvaluated", "Reset", "End"
$stopInfinite = $false
switch ($values)
{
"MoveNext" {
"`tMoveNext"
$switch.MoveNext() | Out-Null
"`tAfter MoveNext: $($switch.Current)"
}
# This case is never evaluated.
"NotEvaluated" {
"`tAfterMoveNext: $($switch.Current)"
}
"Reset" {
if (!$stopInfinite)
{
"`tReset"
$switch.Reset()
$stopInfinite = $true
}
}
default {
"Default (Current): $($switch.Current)"
}
}
Default (Current): Start
MoveNext
After MoveNext: NotEvaluated
Reset
Default (Current): Start
MoveNext
After MoveNext: NotEvaluated
Default (Current): End
另请参阅
about_Functions_Advanced_Methods
about_Functions_Advanced_Parameters
about_Functions_OutputTypeAttribute