關於自動變數
簡短描述
描述儲存 PowerShell 狀態資訊的變數。 PowerShell 會建立和維護這些變數。
完整描述
在概念上,這些變數會被視為唯讀。 即使 可以 寫入,但為了回溯相容性, 不應該 寫入。
以下是 PowerShell 中的自動變數清單:
$$
包含會話所接收最後一行的最後一個權杖。
$?
包含最後一個命令的執行狀態。 如果最後一個命令成功,則會包含 True ,如果失敗則為 False 。
對於在管線中多個階段執行的 Cmdlet 和進階函式,例如在 和 end
區塊中 process
,呼叫 或 $PSCmdlet.WriteError()
在任何時間點分別將 設定 $?
為False, this.WriteError()
如同 this.ThrowTerminatingError()
$PSCmdlet.ThrowTerminatingError()
和 。
Write-Error
Cmdlet 一律會在執行後立即設定 $?
為False,但不會針對呼叫它的函式設定 $?
為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
包含傳遞至函式、腳本或腳本區塊之未宣告參數的值陣列。 當您建立函式時,您可以使用 關鍵字來宣告參數 param
,或在函式名稱後面加上括弧中的逗號分隔參數清單。
在事件動作中 $Args
,變數包含物件,這些物件代表正在處理之事件的事件引數。 此變數只會在事件註冊命令的 區塊內 Action
填入。
您也可以在傳回之 PSEventArgs 物件的Get-Event
SourceArgs屬性中找到這個變數的值。
$ConsoleFileName
包含會話中最近使用之 .psc1
主控台檔案 () 的路徑。 當您使用 PSConsoleFile 參數啟動 PowerShell,或使用 Cmdlet 將嵌入式管理單元名稱匯出至主控台檔案時 Export-Console
,就會填入此變數。
當您不使用參數使用 Export-Console
Cmdlet 時,它會自動更新會話中最近使用的主控台檔案。 您可以使用這個自動變數來判斷要更新的檔案。
$Error
包含代表最近錯誤之錯誤物件的陣列。
最新的錯誤是陣列 $Error[0]
中的第一個錯誤物件。
若要防止錯誤新增至 $Error
陣列,請使用 ErrorAction 一般參數搭配 Ignore值。 如需詳細資訊,請參閱 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
包含代表 PowerShell 主機執行內容的 EngineIntrinsics 物件。 您可以使用這個變數來尋找 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
僅適用于未命名函式) 的函式和腳本區塊 (。
在沒有 、 或 區塊的函
Begin
式中,變數會$input
列舉函式的所有輸入集合。End
Process
Begin
在 區塊中$input
,變數不包含任何資料。在
Process
區塊中$input
,變數包含目前在管線中的 物件。在
End
區塊中$input
,變數會列舉函式的所有輸入集合。注意
您不能在
$input
相同的函式或腳本區塊中使用 Process 區塊和 End 區塊內的 變數。
由於 $input
是列舉值,因此存取其任何屬性會導致 $input
不再可用。 您可以將儲存 $input
在另一個變數中,以重複使用 $input
屬性。
列舉值包含可用來擷取迴圈值並變更目前迴圈反復專案的屬性和方法。 如需詳細資訊,請參閱 使用列舉值。
$IsCoreCLR
包含 $True
目前的會話是否在 .NET Core Runtime (CoreCLR) 上執行。 否則包含 $False
。
$IsLinux
如果目前的會話正在 Linux 作業系統上執行,則包含 $True
。
否則包含 $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 表示原始提示層級。 當您輸入巢狀層級,並在結束時遞減此值時遞增。
例如,當您使用 $Host.EnterNestedPrompt
方法時,PowerShell 會顯示巢狀命令提示字元。 當您在 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 之使用者的相關資訊,包括使用者身分識別和原始電腦的時區。 此變數僅適用于 PSSessions。
變數 $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 | |
完整功能 Windows 版本的 5.1。 | |
此屬性的 值為 'Core' | |
PowerShell 6 和更新版本以及 PowerShell | |
減少使用量版本的 PowerShell 5.1 | |
例如 Windows Nano Server 或 Windows IoT。 | |
GitCommitId | GitHub 中來源檔案的認可識別碼 |
OS | 作業系統的描述 |
PowerShell 正在執行。 | |
平台 | 作業系統正在執行的平臺 |
開啟。 Linux 和 macOS 上的值為 Unix。 | |
請參閱 $IsMacOs 和 $IsLinux 。 |
|
PSCompatibleVersions | 相容的 PowerShell 版本 |
使用目前版本 | |
PSRemotingProtocolVersion | PowerShell 遠端的版本 |
管理通訊協定。 | |
SerializationVersion | 序列化方法的版本 |
WSManStackVersion | WS-Management堆疊的版本號碼 |
$PWD
包含代表目前目錄完整路徑的路徑物件。
$Sender
包含產生此事件的物件。 此變數只會填入事件註冊命令的 Action 區塊內。 您也可以在 傳回之 PSEventArgs 物件的 Get-Event
Sender 屬性中找到這個變數的值。
$ShellId
包含目前殼層的識別碼。
$StackTrace
包含最近錯誤的堆疊追蹤。
$switch
包含列舉值,而不是語句的結果值 Switch
。 變數 $switch
只有在語句正在執行時 Switch
存在;當語句完成執行時 switch
,就會刪除該變數。 如需詳細資訊,請參閱 about_Switch。
列舉值包含可用來擷取迴圈值並變更目前迴圈反復專案的屬性和方法。 如需詳細資訊,請參閱 使用列舉值。
$this
在定義腳本屬性或腳本方法的腳本區塊中 $this
,變數會參考要擴充的物件。
在自訂類別中 $this
,變數是指類別物件本身,允許存取 類別中定義的屬性和方法。
$true
包含 True。 您可以使用這個變數來表示命令和腳本中的 True 。
使用列舉值
$input
、 $foreach
和 $switch
變數都是用來逐一查看其包含程式碼區塊所處理值的列舉值。
列舉值包含可用來前進或重設反復專案的屬性和方法,或擷取反覆運算值。 直接操作列舉值並不視為最佳做法。
在接受管線輸入的函式中,最佳做法是搭配 ValueFromPipeline 或ValueFromPipelineByPropertyName屬性使用 Parameters。
如需詳細資訊,請參閱 about_Functions_Advanced_Parameters。
MoveNext
MoveNext方法會將列舉值前進到集合的下一個專案。 如果列舉值成功進階,MoveNext會傳回True;如果列舉值已通過集合的結尾,則傳回False。
注意
傳回 My MoveNext的布林值會傳送至輸出資料流程。
您可以藉由將輸出類型傳播至 [void]
,或將輸出管線傳送至 Out-Null來隱藏輸出。
$input.MoveNext() | Out-Null
[void]$input.MoveNext()
重設
Reset方法會將列舉值設定為其初始位置,也就是集合中的第一個專案之前。
目前
Current屬性會取得位於列舉值目前位置的集合或管線中的專案。
Current屬性會繼續傳回相同的屬性,直到呼叫MoveNext為止。
範例
範例 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方法會重設整個集合。
- 目前屬性永遠不會填入。
- 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