about_Automatic_Variables

簡短描述

描述變數，這些變數會儲存PowerShell所建立及維護的狀態資訊。

就概念上講，這些變數大部分會被視為只讀。 即使可以寫入，但為了回溯相容性，則不應該寫入。

以下是 PowerShell 中的自動變數清單：

• $$
• $?
• $^
• $_
• $args
• $ConsoleFileName
• $EnabledExperimentalFeatures
• $Error
• $Event
• $EventArgs
• $EventSubscriber
• $ExecutionContext
• $false
• $foreach
• $HOME
• $Host
• $input
• $IsCoreCLR
• $IsLinux
• $IsMacOS
• $IsWindows
• $LASTEXITCODE
• $Matches
• $MyInvocation
• $NestedPromptLevel
• $null
• $PID
• $PROFILE
• $PSBoundParameters
• $PSCmdlet
• $PSCommandPath
• $PSCulture
• $PSDebugContext
• $PSEdition
• $PSHOME
• $PSItem
• $PSScriptRoot
• $PSSenderInfo
• $PSUICulture
• $PSVersionTable
• $PWD
• $Sender
• $ShellId
• $StackTrace
• $switch
• $this
• $true

詳細描述

$$

包含工作階段所接收最後一行中的最後一個令牌。

$?

包含最後一個命令的執行狀態。 如果最後一個命令成功，則包含 True ， 如果失敗則為 False 。 剖析錯誤不會產生執行，因此不會影響的值 $?。

針對在管線中多個階段執行的 Cmdlet 和進階函式，例如，在和 區塊中process，this.WriteError()呼叫 或 $PSCmdlet.WriteError() 分別在任何時間點將 設為 $? False，就像 和 $PSCmdlet.ThrowTerminatingError()一樣this.ThrowTerminatingError()。end

Write-Error Cmdlet 一律會在執行後立即設定$?為 False，但不會針對呼叫它的函式設定$?為 False：

function Test-WriteError
{
    Write-Error "Bad"
    "The `$? variable is: $?"
}

Test-WriteError
"Now the `$? variable is: $?"

Test-WriteError:
Line |
   7 |  Test-WriteError
     |  ~~~~~~~~~~~~~~~
     | Bad
The $? variable is: False
Now the $? variable is: True

針對後者， $PSCmdlet.WriteError() 應該改用 。

針對原生命令 （可執行檔），$?當 為 0 時$LASTEXITCODE會設定為 True，當 為任何其他值時$LASTEXITCODE，則設定為 False。

注意

在 PowerShell 7 之前，將語句包裝在括弧 (...)、subexpression 語法 $(...)或數位運算式 @(...) 一律重設為 $? True。 例如， (Write-Error) 顯示為 $? True。 此行為在 PowerShell 7 中已變更，因此 $? 一律會反映這些表達式中最後一個命令執行的實際成功。

$^

包含會話所接收最後一行中的第一個令牌。

$_

與 $PSItem 相同。 包含管線物件中的目前物件。 您可以在命令中使用這個變數，在管線中的每個物件上執行動作。

如需詳細資訊，請參閱 about_PSItem。

$args

包含傳遞至函式、腳本或腳本區塊之未宣告參數的值陣列。 當您建立函式時，可以使用 關鍵詞宣告參數 param ，或在函式名稱後面加上括號中的逗號分隔參數清單。

在事件動作中 $args ，變數包含對象，這些物件代表正在處理之事件的事件自變數。 此變數只會在事件註冊命令的 區塊內 Action 填入。 這個變數的值也可以在傳回物件的 Get-Event PSEventArgs SourceArgs屬性中找到。

$ConsoleFileName

包含工作階段中最近使用之主控台檔案 （.psc1） 的路徑。 當您使用 PSConsoleFile 參數啟動 PowerShell，或使用 Cmdlet 將嵌入式管理單元名稱匯出至控制台檔案時 Export-Console ，就會填入此變數。

當您使用不含參數的 Export-Console Cmdlet 時，會自動更新會話中最近使用的主控台檔案。 您可以使用這個自動變數來判斷要更新的檔案。

$EnabledExperimentalFeatures

包含已啟用之實驗性功能的名稱清單。

Error$

包含代表最近錯誤之錯誤物件的陣列。 最近的錯誤是陣列 $Error[0]中的第一個錯誤物件。

若要防止錯誤新增至$Error陣列，請使用 ErrorAction 一般參數搭配 Ignore 值。 如需詳細資訊，請參閱 about_CommonParameters。

$Event

包含 PSEventArgs 物件，表示正在處理的事件。 這個變數只會在事件註冊命令的 區塊內 Action 填入，例如 Register-ObjectEvent。 這個變數的值與 Cmdlet 傳回的物件 Get-Event 相同。 您可以在文稿區塊中使用變數的屬性Event，例如 $Event.TimeGenerated。Action

$EventArgs

包含物件，表示從 正在處理之事件的 EventArgs 衍生的第一個事件自變數。 此變數只會在事件註冊命令的 區塊內 Action 填入。 您也可以在傳回物件的 Get-Event PSEventArgs SourceEventArgs屬性中找到此變數的值。

$EventSubscriber

包含 PSEventSubscriber 物件，表示正在處理之事件的事件訂閱者。 此變數只會在事件註冊命令的 區塊內 Action 填入。 這個變數的值與 Cmdlet 傳回的物件 Get-EventSubscriber 相同。

$ExecutionContext

包含 代表PowerShell主機執行內容的EngineIntrinsics 物件。 您可以使用這個變數來尋找 Cmdlet 可用的執行物件。

$false

包含 False。 您可以使用這個變數在命令和文稿中代表 False ，而不是使用字串 "false"。 如果字串轉換成非空白字串或非零整數，則可以將字元串解譯為 True 。

$foreach

包含 ForEach 循環的列舉值（而非產生的值）。 只有在 $ForEach 迴圈正在執行時 ForEach ，變數才會存在;迴圈完成之後就會刪除該變數。

列舉值包含屬性和方法，可用來擷取循環值，並變更目前的循環反覆專案。 如需詳細資訊，請參閱 使用列舉值。

$HOME

包含使用者主目錄的完整路徑。 在 Windows 上，此變數會使用 Windows 環境變數的值 "$env:USERPROFILE" ，通常是 C:\Users\<UserName>。 在 Unix 上，此變數會使用環境變數的值 HOME 。

重要

Windows 可以重新導向使用者配置檔的位置。 這表示 $HOME 可能沒有 與 "$env:HOMEDRIVE$env:HOMEPATH"相同的值。

$Host

包含物件，表示 PowerShell 的目前主應用程式。 您可以使用這個變數來代表命令中的目前主機，或顯示或變更主機的屬性，例如 $Host.version 或$Host.CurrentCulture或或 。 $Host.UI.RawUI.BackGroundColor = "Red"

注意

中的 $Host.PrivateData 色彩設定已由 $PSStyle 喜好設定變數取代。 如需詳細資訊，請參閱 about_ANSI_Terminals。

$input

包含列舉值，列舉傳遞至函式的所有輸入。 變數 $input 僅適用於函式、腳本區塊（這是未命名的函式），以及腳本檔案（儲存的腳本區塊）。

• 在沒有 、 process或 end 區塊的begin函式中$input，變數會列舉函式的所有輸入集合。

• 在區塊中begin$input，變數不包含任何數據。

• 在區塊中process$input，變數包含管線中的目前物件。

• 在區塊中end$input，變數會列舉函式所有輸入的集合。

  注意

  您無法在同 $input 一個函式或腳本區塊中使用 區塊內的 process end 變數。

由於 $input 是列舉值，因此存取其任何屬性會導致 $input 不再可用。 您可以將儲存 $input 在另一個變數中，以重複使用 $input 屬性。

列舉值包含屬性和方法，可用來擷取循環值，並變更目前的循環反覆專案。 如需詳細資訊，請參閱 使用列舉值。

從$input命令行叫用 時，參數所-Commandpwsh指定的命令也可以使用 變數。 下列範例會從 Windows 命令殼層執行。

echo Hello | pwsh -Command """$input World!"""

$IsCoreCLR

包含 $true 目前工作階段是否在 .NET Core 執行時間 （CoreCLR） 上執行。 否則會包含 $false。

$IsLinux

如果目前的工作階段是在 Linux 作業系統上執行， 則包含 $true 。 否則會包含 $false。

$IsMacOS

如果目前的工作階段是在 MacOS 作業系統上執行， 則包含 $true 。 否則會包含 $false。

$IsWindows

$true包含目前工作階段是否在 Windows 作業系統上執行。 否則會包含 $false。

$LASTEXITCODE

包含最後一個原生程式或執行之 PowerShell 腳本的結束代碼。

針對 PowerShell 腳本，的值 $LASTEXITCODE 取決於腳本的呼叫方式，以及是否 exit 使用 關鍵詞：

• 當文稿使用 exit 關鍵字時：

  $LASTEXITCODE 設定為 由 關鍵詞指定的 exit 值。 如需詳細資訊，請參閱 about_Language_Keywords。

• 直接呼叫文稿時，例如 ./Test.ps1，或使用 呼叫運算子 （&） 例如 & ./Test.ps1：

  $LASTEXITCODE的值不會變更，除非：

  • 腳本會呼叫另一個使用 關鍵詞的 exit 腳本
  • 腳本會呼叫原生命令
  • 腳本會使用 exit 關鍵詞

• 使用 File 參數呼叫pwsh文本時，$LASTEXITCODE會設定為：

  • 1 如果腳本因例外狀況而終止
  • 關鍵詞所 exit 指定的值，如果在腳本中使用
  • 0 如果腳本成功完成，則為

• 使用 Command 參數呼叫pwsh文本時，$LASTEXITCODE會設定為：

  • 1 如果腳本因例外狀況而終止，或最後一個命令的結果設定 $? 為 $false
  • 0 如果腳本成功完成，且最後一個命令的結果設定 $? 為 $true

如需 File 和 Command 參數的詳細資訊，請參閱about_Pwsh。

$Matches

變數 $Matches 適用於 -match 和 -notmatch 運算符。 當您將純量輸入提交至 -match 或 -notmatch 運算符，且其中一個偵測到相符專案時，它們會傳回布爾值，並以任何相符字串值的哈希表填$Matches入自動變數。 $Matches當您搭配 -match 運算符使用正則表達式時，哈希表也可以填入擷取。

如需 運算子的詳細資訊 -match ，請參閱 about_Comparison_Operators。 如需正則表達式的詳細資訊，請參閱 about_Regular_Expressions。

變數$Matches也可在語句-Regex中使用 switch 參數。 其填入方式與 -match 和 -notmatch 運算符相同。 如需 語句的詳細資訊 switch ，請參閱 about_Switch。

注意

在工作階段中填入時 $Matches ，它會保留相符的值，直到被另一個相符專案覆寫為止。 如果 -match 再次使用，且找不到相符專案，則不會重設為 $Matches $null。 先前相符的值會保留在 中 $Matches ，直到找到另一個相符項目為止。

$MyInvocation

包含目前命令的相關信息，例如名稱、參數、參數值，以及如何啟動、呼叫或叫用命令的相關信息，例如呼叫目前命令的腳本名稱。

$MyInvocation 只會針對腳本、函式和腳本區塊填入。 您可以使用 System.Management.Automation.InvocationInfo 物件$MyInvocation中傳回的資訊，例如函式的名稱 （$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

從 PowerShell 7 開始， $PSCulture 反映目前 PowerShell Runspace （session） 的文化特性。 如果在 PowerShell Runspace 中變更文化特性， $PSCulture 則會更新該 Runspace 的值。

文化特性會決定數位、貨幣和日期等項目的顯示格式，並儲存在 System.Globalization.CultureInfo 物件中。 用來 Get-Culture 顯示計算機的文化特性。 $PSCulture 包含 Name 屬性的值。

$PSDebugContext

偵錯時，此變數包含偵錯環境的相關信息。 否則，它會包含 Null 值。 因此，您可以使用它來判斷調試程式是否具有控制權。 填入時，它會包含具有斷點和 InvocationInfo 屬性的 PsDebugContext 物件。 InvocationInfo 屬性有數個實用的屬性，包括 Location 屬性。 Location 屬性會指出正在偵錯的腳本路徑。

$PSEdition

在中包含 $PSVersionTable.PSEdition相同的值。 此變數可用於模組指令清單檔案，但 $PSVersionTable 不是。

$PSHOME

包含 PowerShell 安裝目錄的完整路徑，通常是 C:\Program Files\PowerShell\7 在 Windows 系統中。 您可以在 PowerShell 檔案的路徑中使用這個變數。 例如，下列命令會在概念說明主題中搜尋說明一詞：

Select-String -Pattern Help -Path $PSHOME\en-US\*.txt

$PSItem

與 $_ 相同。 包含管線物件中的目前物件。 您可以在命令中使用這個變數，在管線中的每個物件上執行動作。

如需詳細資訊，請參閱 about_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 的值 。Current系統 UICulture.Name 屬性。 若要取得 系統的 System.Globalization.CultureInfo 物件，請使用 Get-UICulture Cmdlet。

$PSVersionTable

包含唯讀哈希表，其中顯示目前會話中執行之 PowerShell 版本的詳細數據。 資料表包含下列專案：

• PSVersion - PowerShell 版本號碼
• PSEdition 此屬性具有 PowerShell 4 和以下版本的 『Desktop』 值，以及功能完整的 Windows 版本上的 PowerShell 5.1。 此屬性針對 PowerShell 6 和更新版本以及 Windows PowerShell 5.1 的使用量降低版本， Core 例如 Windows Nano Server 或 Windows IoT 的值。
• GitCommitId - GitHub 中來源檔案的認可標識碼，
• OS - 說明 PowerShell 正在執行的作業系統。
• 平臺 - 作業系統執行的平臺。 Linux 和macOS 上的值為 Unix。 請參閱 $IsMacOs 和 $IsLinux。
• PSCompatibleVersions - 與目前版本相容的 PowerShell 版本
• PSRemotingProtocolVersion - PowerShell 遠端管理通訊協定的版本。
• SerializationVersion - 串行化方法的版本
• WSManStackVersion - WS-Management 堆棧的版本號碼

$PWD

包含path物件，代表目前PowerShell Runspace之目前目錄位置的完整路徑。

注意

PowerShell 支援每個進程的多個 Runspace。 每個 Runspace 都有自己的 目前目錄。 這與進程的目前目錄不同： [System.Environment]::CurrentDirectory。

$Sender

包含產生此事件的物件。 此變數只會在事件註冊命令的 Action 區塊內填入。 您也可以在傳回物件的 PSEventArgs Get-Event Sender 屬性中找到此變數的值。

$ShellId

包含目前殼層的標識碼。

$StackTrace

包含最新錯誤的堆疊追蹤。

$switch

包含列舉值，而非語句的結果值 Switch 。 $switch只有在語句執行時Switch，變數才會存在;當語句完成執行時switch，就會刪除該變數。 如需詳細資訊，請參閱 about_Switch。

列舉值包含屬性和方法，可用來擷取循環值，並變更目前的循環反覆專案。 如需詳細資訊，請參閱 使用列舉值。

$this

變數 $this 用於擴充類別的腳本區塊中，以參考類別本身的實例。

PowerShell 的可延伸類型系統 （ETS） 可讓您使用腳本區塊將屬性新增至類別。 在定義文稿屬性或腳本方法的腳本區塊中， $this 變數會參考正在擴充之類別的 實例。 例如，PowerShell 使用 ETS 將 BaseName 屬性新增至 FileInfo 類別。

PS> Get-ChildItem .\README.md | Get-Member BaseName | Format-List

TypeName   : System.IO.FileInfo
Name       : BaseName
MemberType : ScriptProperty
Definition : System.Object BaseName {get=if ($this.Extension.Length -gt 0)
             {$this.Name.Remove($this.Name.Length - $this.Extension.Length
             )}else{$this.Name};}

如需詳細資訊，請參閱 about_Types.ps1xml。

在 PowerShell 類別中 $this ，變數是指類別本身的實體對象，允許存取類別中定義的屬性和方法。 如需詳細資訊，請參閱 about_Classes。

. $this NET 事件類別也會使用變數，這些類別會採用腳本區塊作為事件處理程式的委派。 在此案例中， $this 表示源自事件的物件，稱為事件傳送者。

$true

包含 True。 您可以使用此變數在命令和文稿中代表 True 。

使用列舉值

$input、 $foreach和 $switch 變數都是列舉值，用來逐一查看其包含程式代碼區塊所處理的值。

列舉值包含可用來推進或重設反覆專案，或擷取反覆運算值的屬性和方法。 直接操作列舉值並不被視為最佳做法。

• 在迴圈內，流程控制關鍵詞應該會中斷並繼續。

• 在接受管線輸入的函式中，最佳做法是搭配 ValueFromPipeline 或 ValueFromPipelineByPropertyName 屬性使用參數。

  如需詳細資訊，請參閱 about_Functions_Advanced_Parameters。

MoveNext

MoveNext 方法會將枚舉器前進到集合的下一個專案。 如果列舉值成功進階， False MoveNext 會傳回True枚舉器是否已通過集合結尾。

注意

MoveNext 傳回的布爾值會傳送至輸出數據流。 您可以透過將輸出類型轉換成 [void] 或將輸出傳送至 Out-Null 來隱藏輸出。

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

方法會將 Reset 列舉值設定為其初始位置，也就是 集合中第一個專案之前 。

Current

屬性 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 會重設整個集合。
• 永遠不會 Current 填入屬性。
• MoveNext 方法會傳回 false，因為無法進階集合。
  • 呼叫 MoveNext 會 $input 清除變數。

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 方法。

Current除非您明確呼叫MoveNext，否則不會填入屬性。 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 hasn't changed: $num"
    }
}

Iteration: 0
        Num: one
        Current: one
Iteration: 1
        Num: two
        Current: two
Before MoveNext (Current): two
After MoveNext (Current): three
Num hasn't 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()
        ("`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
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_OutputTypeAttribute
• about_Functions_CmdletBindingAttribute
• about_Hash_Tables
• about_Preference_Variables
• about_Splatting
• about_Variables