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 をします。 解析エラーは実行されないため、 $?の値には影響しません。

パイプライン内の複数のステージ (たとえば、processブロックとend ブロックの両方で実行されるコマンドレットと高度な関数の場合は、this.ThrowTerminatingError()や$PSCmdlet.ThrowTerminatingError()と同様に、任意のポイント セットでそれぞれthis.WriteError()または$PSCmdlet.WriteError()を$?Falseを呼び出します。

Write-Error コマンドレットは、実行直後に常に$?を 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() を使用する必要があります。

ネイティブ コマンド (実行可能ファイル) の場合、$?は $LASTEXITCODE が 0 の場合は True に設定され、$LASTEXITCODEが他の値である場合は False に設定されます。

Note

PowerShell 7 まで、かっこ内のステートメント(...)、部分式構文$(...)、または配列式@(...)常に$?Trueにリセットされます。 たとえば、 (Write-Error) は $? を True と表示します。 この動作は PowerShell 7 で変更され、 $? は、これらの式での最後のコマンド実行の実際の成功を常に反映します。

$^

セッションによって受信された最後の行の最初のトークンを格納します。

$_

$PSItem と同じ。 パイプライン オブジェクト内の現在のオブジェクトを格納します。 この変数は、パイプライン内のすべてのオブジェクトに対してアクションを実行するコマンドで使用できます。

詳細については、「 about_PSItem」を参照してください。

$args

関数、スクリプト、またはスクリプト ブロックに渡される宣言されていないパラメーターの値の配列を格納します。 関数を作成するときに、 param キーワードを使用するか、関数名の後にかっこで囲まれたパラメーターのコンマ区切りリストを追加して、パラメーターを宣言できます。

イベント アクションでは、 $args 変数には、処理中のイベントのイベント引数を表すオブジェクトが含まれます。 この変数は、イベント登録コマンドの Action ブロック内でのみ設定されます。 この変数の値は、返されるPSEventArgs オブジェクトの SourceArgs プロパティGet-Event見つけることもできます。

$ConsoleFileName

セッションで最後に使用されたコンソール ファイル (.psc1) のパスを格納します。 この変数は、 PSConsoleFile パラメーターを使用して PowerShell を起動するとき、または Export-Console コマンドレットを使用してスナップイン名をコンソール ファイルにエクスポートするときに設定されます。

パラメーターを指定せずに Export-Console コマンドレットを使用すると、セッションで最後に使用されたコンソール ファイルが自動的に更新されます。 この自動変数を使用して、更新するファイルを決定できます。

$EnabledExperimentalFeatures

有効になっている実験用機能の名前の一覧が含まれます。

Error$

最新のエラーを表すエラー オブジェクトの配列が含まれています。 最新のエラーは、配列 $Error[0]の最初のエラー オブジェクトです。

エラーが $Error 配列に追加されないようにするには、 ErrorAction 共通パラメーターを使用し、値 Ignoreを指定します。 詳細については、「about_CommonParameters」を参照してください。

$Event

処理中のイベントを表す PSEventArgs オブジェクトを格納します。 この変数は、Register-ObjectEventなどのイベント登録コマンドのAction ブロック内でのみ設定されます。 この変数の値は、 Get-Event コマンドレットが返すのと同じオブジェクトです。 Action スクリプト ブロックでは、Event変数のプロパティ ($Event.TimeGenerated など) を使用できます。

$EventArgs

処理中のイベントの EventArgs から派生する最初のイベント引数を表すオブジェクトを格納します。 この変数は、イベント登録コマンドの Action ブロック内でのみ設定されます。 この変数の値は、Get-Eventが返すPSEventArgs オブジェクトの SourceEventArgs プロパティにも見つかります。

$EventSubscriber

処理中のイベントのイベント サブスクライバーを表す PSEventSubscriber オブジェクトを格納します。 この変数は、イベント登録コマンドの Action ブロック内でのみ設定されます。 この変数の値は、 Get-EventSubscriber コマンドレットが返すのと同じオブジェクトです。

$ExecutionContext

PowerShell ホストの実行コンテキストを表す EngineIntrinsics オブジェクトを格納します。 この変数を使用して、コマンドレットで使用できる実行オブジェクトを見つけることができます。

$false

Falseを格納します。 この変数を使用すると、文字列"false"を使用する代わりに、コマンドとスクリプトで False を表すことができます。 文字列は、空でない文字列または 0 以外の整数に変換される場合True として解釈できます。

$foreach

ForEach ループの列挙子 (結果の値ではない) を格納します。 $ForEach変数は、ForEach ループの実行中にのみ存在し、ループの完了後に削除されます。

列挙子には、ループ値を取得し、現在のループイテレーションを変更するために使用できるプロパティとメソッドが含まれています。 詳細については、「 列挙子の使用」を参照してください。

$HOME

ユーザーのホーム ディレクトリの完全なパスが含まれています。 Windows では、この変数は "$env:USERPROFILE" Windows 環境変数 (通常は C:\Users\<UserName>) の値を使用します。 Unix では、この変数は HOME 環境変数の値を使用します。

重要

Windows では、ユーザーのプロファイルの場所をリダイレクトできます。 これは、 $HOME が "$env:HOMEDRIVE$env:HOMEPATH"と同じ値を持たない可能性があることを意味します。

$Host

PowerShell の現在のホスト アプリケーションを表すオブジェクトを格納します。 この変数を使用すると、コマンドで現在のホストを表したり、ホストのプロパティ ( $Host.version 、 $Host.CurrentCulture、 $Host.UI.RawUI.BackGroundColor = "Red"など) を表示または変更したりできます。

Note

$Host.PrivateDataの色設定は、$PSStyleユーザー設定変数に置き換えられました。 詳細については、「 about_ANSI_Terminals」を参照してください。

$input

関数に渡されるすべての入力を列挙する列挙子を格納します。 $input変数は、関数、スクリプト ブロック (名前のない関数)、スクリプト ファイル (保存されたスクリプト ブロック) でのみ使用できます。

• begin、process、またはend ブロックを持たない関数では、$input変数は関数へのすべての入力のコレクションを列挙します。

• begin ブロックでは、$input変数にデータが含まれています。

• process ブロックでは、$input変数にパイプライン内の現在のオブジェクトが含まれています。

• end ブロックでは、$input変数は関数へのすべての入力のコレクションを列挙します。

  Note

  同じ関数またはスクリプト ブロック内の process ブロックと end ブロックの両方の内部で、$input変数を使用することはできません。

$inputは列挙子であるため、プロパティのいずれかにアクセスすると、$inputは使用できなくなります。 $inputを別の変数に格納して、$inputプロパティを再利用できます。

列挙子には、ループ値を取得し、現在のループイテレーションを変更するために使用できるプロパティとメソッドが含まれています。 詳細については、「 列挙子の使用」を参照してください。

$input変数は、コマンド ラインから呼び出されたときに、pwshの -Command パラメーターで指定されたコマンドでも使用できます。 次の例は、Windows コマンド シェルから実行されます。

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

$IsCoreCLR

現在のセッションが .NET Core ランタイム (CoreCLR) で実行されている場合の $True が含まれます。 それ以外の場合は、 $Falseが含まれます。

$IsLinux

現在のセッションが Linux オペレーティング システムで実行されている場合の $True が含まれます。 それ以外の場合は、 $Falseが含まれます。

$IsMacOS

現在のセッションが MacOS オペレーティング システムで実行されている場合の $True が含まれます。 それ以外の場合は、 $Falseが含まれます。

$IsWindows

現在のセッションが Windows オペレーティング システムで実行されている場合の $TRUE が含まれます。 それ以外の場合は、 $FALSEが含まれます。

$LASTEXITCODE

最後に実行されたネイティブ プログラムまたは PowerShell スクリプトの終了コードが含まれます。

PowerShell スクリプトの場合、 $LASTEXITCODE の値は、スクリプトの呼び出し方法と、 exit キーワードが使用されたかどうかによって異なります。

• スクリプトで exit キーワードを使用する場合:

  $LASTEXITCODE は、 exit キーワードによって指定された値に設定されます。 詳細については、「 about_Language_Keywords」を参照してください。

• スクリプトが ./Test.ps1のように直接呼び出されたとき、または call 演算子を使用して呼び出された場合 (&) は次のように & ./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演算子で動作します。 scalar入力を-match演算子または-notmatch演算子に送信し、いずれかが一致を検出すると、ブール値が返され、$Matches自動変数に一致した文字列値のハッシュ テーブルが設定されます。 $Matches ハッシュ テーブルには、-match演算子で正規表現を使用する場合にキャプチャを設定することもできます。

-match演算子の詳細については、「about_Comparison_Operators」を参照してください。 正規表現の詳細については、「 about_Regular_Expressions」を参照してください。

$Matches変数は、-Regex パラメーターを持つswitch ステートメントでも機能します。 -match演算子と-notmatch演算子と同じ方法で設定されます。 switch ステートメントの詳細については、about_Switchを参照してください。

Note

セッションに $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 がコレクションに含まれている場合、オブジェクトの 1 つとしてカウントされます。

$a = "one", $null, "three"
$a.count

3

$null変数を ForEach-Object コマンドレットにパイプすると、他のオブジェクトの場合と同様に、$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は、Key と Value の形式で表示されます。

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

実行されているコマンドレットまたは高度な関数を表すオブジェクトを格納します。

コマンドレットまたは関数コードでオブジェクトのプロパティとメソッドを使用して、使用条件に応答できます。 たとえば、 ParameterSetName プロパティには、使用されているパラメーター セットの名前が含まれており、 ShouldProcess メソッドはコマンドレットに WhatIf および Confirm パラメーターを動的に追加します。

$PSCmdlet自動変数の詳細については、「about_Functions_CmdletBindingAttributeとabout_Functions_Advanced」を参照してください。

$PSCommandPath

実行されているスクリプトの完全なパスとファイル名が含まれます。 この変数は、すべてのスクリプトで有効です。

$PSCulture

PowerShell 7 以降では、 $PSCulture は現在の PowerShell 実行空間 (セッション) のカルチャを反映しています。 PowerShell 実行空間でカルチャが変更された場合、その実行空間の $PSCulture 値が更新されます。

カルチャは、数値、通貨、日付などの項目の表示形式を決定し、 System.Globalization.CultureInfo オブジェクトに格納されます。 Get-Cultureを使用して、コンピューターのカルチャを表示します。 $PSCulture には、 Name プロパティの値が含まれています。

$PSDebugContext

デバッグ中、この変数にはデバッグ環境に関する情報が含まれています。 それ以外の場合は、 null 値が含まれます。 その結果、デバッガーに制御があるかどうかを判断するために使用できます。 設定されると、Breakpoints および InvocationInfo プロパティを持つPsDebugContext オブジェクトが含まれます。 InvocationInfo プロパティには、Location プロパティなど、いくつかの便利なプロパティがあります。 Location プロパティは、デバッグ対象のスクリプトのパスを示します。

$PSEdition

$PSVersionTable.PSEditionに同じ値が含まれています。 この変数はモジュール マニフェスト ファイルで使用できます。一方、 $PSVersionTable は使用できません。

$PSHOME

PowerShell のインストール ディレクトリの完全なパス (通常は Windows システムの C:\Program Files\PowerShell\7 ) が含まれます。 この変数は、PowerShell ファイルのパスで使用できます。 たとえば、次のコマンドは、概念ヘルプ トピックで Help という単語を検索します。

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

$PSItem

$_ と同じ。 パイプライン オブジェクト内の現在のオブジェクトを格納します。 この変数は、パイプライン内のすべてのオブジェクトに対してアクションを実行するコマンドで使用できます。

詳細については、「 about_PSItem」を参照してください。

$PSScriptRoot

実行中のスクリプトの親ディレクトリの完全なパスが含まれています。

PowerShell 2.0 では、この変数はスクリプト モジュール (.psm1) でのみ有効です。 PowerShell 3.0 以降では、すべてのスクリプトで有効です。

$PSSenderInfo

PSSession を開始したユーザーに関する情報 (ユーザー ID や発信元コンピューターのタイム ゾーンなど) が含まれます。 この変数は PSSessions でのみ使用できます。

$PSSenderInfo変数には、ユーザーが構成可能なプロパティ ApplicationArguments が含まれています。既定では、元のセッションからの$PSVersionTableのみが含まれます。 ApplicationArguments プロパティにデータを追加するには、New-PSSessionOption コマンドレットの ApplicationArguments パラメーターを使用します。

$PSUICulture

オペレーティング システムで構成されているユーザー インターフェイス (UI) カルチャの名前を格納します。 UI カルチャは、どのテキスト文字列がメニューやメッセージなどのユーザー インターフェイス要素に使用されるかを決定します。 これは、 System.Globalization.CultureInfo.Current の値です。システムのプロパティを UICulture.Name します。 システムの System.Globalization.CultureInfo オブジェクトを取得するには、 Get-UICulture コマンドレットを使用します。

$PSVersionTable

現在のセッションで実行されている PowerShell のバージョンに関する詳細を表示する読み取り専用ハッシュ テーブルが含まれています。 この表には、次の項目が含まれています。

• PSVersion - PowerShell のバージョン番号
• PSEdition このプロパティの値は、PowerShell 4 以下の場合は "Desktop" で、フル機能の Windows エディションでは PowerShell 5.1 になります。 このプロパティの値は、PowerShell 6 以降の Core と、Windows Nano Server や Windows IoT などのフットプリントが小さいエディションの Windows PowerShell 5.1 です。
• GitCommitId - ソース ファイルのコミット ID (GitHub)
• OS - PowerShell が実行されているオペレーティング システムの説明。
• プラットフォーム - オペレーティング システムが実行されているプラットフォーム。 Linux と macOS の値は Unix です。 $IsMacOs と $IsLinux を参照してください。
• PSCompatibleVersions - 現在のバージョンと互換性のある PowerShell のバージョン
• PSRemotingProtocolVersion - PowerShell リモート管理プロトコルのバージョン。
• SerializationVersion - シリアル化メソッドのバージョン
• WSManStackVersion - WS-Management スタックのバージョン番号

$PWD

現在の PowerShell 実行空間の現在のディレクトリの場所の完全なパスを表すパス オブジェクトを格納します。

Note

PowerShell では、プロセスごとに複数の実行空間がサポートされます。 各実行空間には、独自の 現在のディレクトリがあります。 これは、プロセスの現在のディレクトリ ( [System.Environment]::CurrentDirectory) とは同じではありません。

$Sender

このイベントを生成したオブジェクトを格納します。 この変数は、イベント登録コマンドの Action ブロック内でのみ設定されます。 この変数の値は、返される PSEventArgs オブジェクトの Sender プロパティ Get-Event 見つけることもできます。

$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_Remote」を参照してください。

$this変数は、スクリプト ブロックをイベント ハンドラーのデリゲートとして受け取る .NET イベント クラスでも使用されます。 このシナリオでは、 $this はイベント送信者と呼ばれるイベントの発生元オブジェクトを表します。

$true

Trueを含みます。 この変数を使用すると、コマンドとスクリプトで True を表すことができます。

列挙子の使用

$input、$foreach、および$switch変数はすべて、含まれているコード ブロックによって処理される値を反復処理するために使用される列挙子です。

列挙子には、反復を進めたりリセットしたり、反復値を取得したりするために使用できるプロパティとメソッドが含まれています。 列挙子を直接操作することはベスト プラクティスとは見なされません。

• ループ内では、フロー制御キーワード break と continue をお勧めします。

• パイプライン入力を受け入れる関数内では、 ValueFromPipeline または ValueFromPipelineByPropertyName 属性でパラメーターを使用することをお勧めします。

  詳細については、「about_Functions_Advanced_Parameters」を参照してください。

MoveNext

MoveNext メソッドは、列挙子をコレクションの次の要素に進めます。 MoveNext は、列挙子が正常に詳細設定された場合は True を返します。列挙子がコレクションの末尾を通過した場合に False します。

Note

MoveNext によって返されるBoolean値が出力ストリームに送信されます。 出力を抑制するには、出力を [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 メソッドを使用します。

Note

foreach ループの各イテレーションは、MoveNext メソッドを自動的に呼び出します。

次のループは 2 回だけ実行されます。 2 番目のイテレーションでは、イテレーションが完了する前にコレクションが 3 番目の要素に移動されます。 2 回目の反復の後、反復処理する値がもうなくなり、ループが終了します。

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 メソッドが呼び出されるため、最初の 2 つの要素ループします。 最初の 2 つのループの後、 if ステートメントは失敗し、ループは 3 つの要素すべてを正常に反復処理します。

重要

これにより、無限ループが発生する可能性があります。

$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変数とまったく同じ規則があります。 次の例では、すべての列挙子の概念を示します。

Note

MoveNext メソッドの後にbreakステートメントがない場合でも、NotEvaluatedケースが実行されない点に注意してください。

$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