ForEach-Object

モジュール:: Microsoft.PowerShell.Core Module

入力オブジェクトのコレクション内の各項目に対して操作を実行します。

構文

ScriptBlockSet (既定)

ForEach-Object
    [-Process] <ScriptBlock[]>
    [-InputObject <PSObject>]
    [-Begin <ScriptBlock>]
    [-End <ScriptBlock>]
    [-RemainingScripts <ScriptBlock[]>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

PropertyAndMethodSet

ForEach-Object
    [-MemberName] <String>
    [-InputObject <PSObject>]
    [-ArgumentList <Object[]>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

ParallelParameterSet

ForEach-Object
    -Parallel <ScriptBlock>
    [-InputObject <PSObject>]
    [-ThrottleLimit <Int32>]
    [-TimeoutSeconds <Int32>]
    [-AsJob]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

説明

ForEach-Object コマンドレットは、入力オブジェクトのコレクション内の各項目に対して操作を実行します。入力オブジェクトは、コマンドレットにパイプ処理するか、 InputObject パラメーターを使用して指定できます。

Windows PowerShell 3.0 以降では、ForEach-Object コマンドを作成する 2 つの異なる方法があります。

スクリプトブロックの。スクリプトブロックを使用して操作を指定できます。スクリプトブロック内で、$_ 変数を使用して現在のオブジェクトを表します。スクリプトブロックは 、Process パラメーターの値です。スクリプトブロックには、任意の PowerShell スクリプトを含めることができます。

たとえば、次のコマンドは、コンピューター上の各 プロセスの ProcessName プロパティの値を取得します。

Get-Process | ForEach-Object {$_.ProcessName}

ForEach-Object は、beginで説明されているように、process、end、およびブロックをサポートします。

注

スクリプトブロックは、呼び出し元のスコープで実行されます。したがって、ブロックはそのスコープ内の変数にアクセスでき、コマンドレットの完了後にそのスコープに保持される新しい変数を作成できます。
操作ステートメント。また、自然言語によく似た操作ステートメントを書くこともできます。 operation ステートメントを使用して、プロパティ値を指定したり、メソッドを呼び出したりできます。操作ステートメントは、Windows PowerShell 3.0 で導入されました。

たとえば、次のコマンドは、コンピューター上の各 プロセスの ProcessName プロパティの値も取得します。

Get-Process | ForEach-Object ProcessName
並列実行スクリプトブロック。 PowerShell 7.0 以降では、各スクリプトブロックを並列で実行する 3 つ目のパラメーターセットを使用できます。 ThrottleLimit パラメーターは、一度に実行される並列スクリプトの数を制限します。前と同様に、 $_ 変数を使用して、スクリプトブロック内の現在の入力オブジェクトを表します。 $using: キーワードを使用して、実行中のスクリプトに変数参照を渡します。

PowerShell 7 では、ループイテレーションごとに新しい実行空間が作成され、最大限の分離が確保されます。これは、新しい実行空間の作成に比べて作業が少ない場合や、多くの反復で大きな作業が実行されている場合に、パフォーマンスとリソースに大きな影響を与える可能性があります。 PowerShell 7.1 の時点では、実行空間プールからの実行空間は既定で再利用されます。ランスペース・プール・サイズは、 ThrottleLimit パラメーターによって指定されます。既定の実行空間プールのサイズは 5 です。 UseNewRunspace スイッチを使用して、イテレーションごとに新しい実行空間を作成できます。

既定では、並列スクリプトブロックは、並列タスクを開始した呼び出し元の現在の作業ディレクトリを使用します。

詳細については、この記事の「メモ」セクションを参照してください。

例

例 1: 配列内の整数を除算する

この例では、3 つの整数の配列を受け取り、それぞれの整数を 1024 で除算します。

30000, 56798, 12432 | ForEach-Object -Process {$_/1024}

29.296875
55.466796875
12.140625

例 2: ディレクトリ内のすべてのファイルの長さを取得する

この例では、PowerShell インストールディレクトリ内のファイルとディレクトリ $PSHOME処理します。

Get-ChildItem $PSHOME |
  ForEach-Object -Process {if (!$_.PSIsContainer) {$_.Name; $_.Length / 1024; " " }}

オブジェクトがディレクトリでない場合、スクリプトブロックはファイルの名前を取得し、 その Length プロパティの値を 1024 で除算し、次のエントリと区切るためにスペース (" ") を追加します。このコマンドレットは、PSISContainer プロパティを使用して、オブジェクトがディレクトリであるかどうかを判断します。

例 3: 最新のシステムイベントを操作する

次の使用例は、システムイベントログから 1000 件の最新のイベントをテキストファイルに書き込みます。現在の時刻は、イベントの処理の前後に表示されます。

$Events = Get-EventLog -LogName System -Newest 1000
$events | ForEach-Object -Begin {Get-Date} -Process {Out-File -FilePath Events.txt -Append -InputObject $_.Message} -End {Get-Date}

Get-EventLog は、システムイベントログから最新の1000個のイベントを取得し、 $Events 変数に格納します。 $Events その後、 ForEach-Object コマンドレットにパイプされます。 Begin パラメーターには、現在の日付と時刻が表示されます。次に、 Process パラメーターは Out-File コマンドレットを使用して、events.txt という名前のテキストファイルを作成し、そのファイルに各イベントのメッセージプロパティを格納します。最後に、 End パラメーターは、すべての処理が完了した後の日付と時刻を表示するために使用されます。

例 4: レジストリキーの値を変更する

この例では、キーの下にあるすべてのサブキーの HKCU:\Network レジストリエントリの値を大文字のテキストに変更します。

Get-ItemProperty -Path HKCU:\Network\* |
  ForEach-Object {Set-ItemProperty -Path $_.PSPath -Name RemotePath -Value $_.RemotePath.ToUpper();}

この形式を使用して、レジストリエントリ値のフォームまたはコンテンツを変更できます。

ネットワーク キーの各サブキーは、サインオン時に再接続するマップされたネットワークドライブを表します。 RemotePath エントリには、接続されているドライブの UNC パスが含まれています。たとえば、E: ドライブを \\Server\Share にマップすると、RemotePath レジストリ値が \\Server\Share に設定された E サブキーが HKCU:\Network に作成されます。

このコマンドでは、 Get-ItemProperty コマンドレットを使用して Network キーのすべてのサブキーを取得し、 Set-ItemProperty コマンドレットを使用して各キーの RemotePath レジストリエントリの値を変更します。 Set-ItemProperty コマンドでは、パスはレジストリキーの PSPath プロパティの値です。これは、レジストリエントリではなく、レジストリキーを表す Microsoft .NET Framework オブジェクトのプロパティです。このコマンドは、文字列 (REG_SZ) である RemotePath 値の ToUpper() メソッドを使用します。

Set-ItemProperty は各キーのプロパティを変更するため、プロパティにアクセスするには ForEach-Object コマンドレットが必要です。

例 5: $Null自動変数を使用する

この例では、$Null 自動変数を ForEach-Object コマンドレットにパイプ処理する効果を示します。

1, 2, $null, 4 | ForEach-Object {"Hello"}

Hello
Hello
Hello
Hello

PowerShell は null を明示的なプレースホルダーとして扱うため、 ForEach-Object コマンドレットは、パイプ処理する他のオブジェクトの場合と同様に、 $Null の値を生成します。

例 6: プロパティ値を取得する

この例では、コマンドレットの MemberName パラメーターを使用して、インストールされているすべての PowerShell モジュールの ForEach-Object プロパティの値を取得します。

Get-Module -ListAvailable | ForEach-Object -MemberName Path
Get-Module -ListAvailable | Foreach Path

2 番目のコマンドは、最初のコマンドと同じです。 Foreach コマンドレットのForEach-Objectエイリアスを使用し、MemberName パラメーターの名前を省略します(省略可能)。

ForEach-Object コマンドレットは、Format コマンドレットやプロパティ値の型を変更する Select-Object コマンドレットとは異なり、型を変更せずに値を取得するため、プロパティ値を取得する場合に便利です。

例 7: モジュール名をコンポーネント名に分割する

この例では、2 つのドット区切りのモジュール名をコンポーネント名に分割する 3 つの方法を示します。このコマンドは、文字列の Split メソッドを呼び出します。 3 つのコマンドは異なる構文を使用しますが、同等で交換可能です。出力は、3 つのケースすべてで同じです。

"Microsoft.PowerShell.Core", "Microsoft.PowerShell.Host" | ForEach-Object {$_.Split(".")}
"Microsoft.PowerShell.Core", "Microsoft.PowerShell.Host" | ForEach-Object -MemberName Split -ArgumentList "."
"Microsoft.PowerShell.Core", "Microsoft.PowerShell.Host" | Foreach Split "."

Microsoft
PowerShell
Core
Microsoft
PowerShell
Host

最初のコマンドでは、スクリプトブロックと現在のオブジェクト演算子 $_を含む従来の構文を使用します。ドット構文を使用して、区切り記号引数を囲むメソッドとかっこを指定します。

2 番目のコマンドでは 、MemberName パラメーターを使用して Split メソッドを指定し 、ArgumentList パラメーターを使用してドット (.) を分割区切り記号として識別します。

3 番目のコマンドは、コマンドレットの ForEach-Object エイリアスを使用し、省略可能な MemberName パラメーターと ArgumentList パラメーターの名前を省略します。

例 8: 2 つのスクリプトブロックで ForEach-Object を使用する

この例では、2 つのスクリプトブロックを位置指定して渡します。すべてのスクリプトブロックは Process パラメーターにバインドされます。ただし、これらは Begin パラメーターと Process パラメーターに渡されたかのように扱われます。

1..2 | ForEach-Object { 'begin' } { 'process' }

begin
process
process

例 9: 2 つ以上のスクリプトブロックで ForEach-Object を使用する

この例では、2 つのスクリプトブロックを位置指定して渡します。すべてのスクリプトブロックは Process パラメーターにバインドされます。ただし、これらは Begin、 Process、および End パラメーターに渡されたかのように扱われます。

1..2 | ForEach-Object { 'begin' } { 'process A' }  { 'process B' }  { 'end' }

begin
process A
process B
process A
process B
end

注

最初のスクリプトブロックは常に begin ブロックにマッピングされ、最後のブロックは end ブロックにマッピングされ、その間のブロックはすべて process ブロックにマッピングされます。

例 10: パイプライン項目ごとに複数のスクリプトブロックを実行する

前の例に示すように、 Process パラメーターを使用して渡された複数のスクリプトブロックが Begin パラメーターと End パラメーターにマップされます。このマッピングを回避するには、 Begin パラメーターと End パラメーターに明示的な値を指定する必要があります。

1..2 | ForEach-Object -Begin $null -Process { 'one' }, { 'two' }, { 'three' } -End $null

one
two
three
one
two
three

例 11: 低速スクリプトを並列バッチで実行する

この例では、文字列を評価し、1 秒間スリープする単純なスクリプトブロックを実行します。

$Message = "Output:"

1..8 | ForEach-Object -Parallel {
    "$using:Message $_"
    Start-Sleep 1
} -ThrottleLimit 4

Output: 1
Output: 2
Output: 3
Output: 4
Output: 5
Output: 6
Output: 7
Output: 8

ThrottleLimit パラメーターの値は 4 に設定され、入力は 4 つのバッチで処理されます。 $using: キーワードは、各並列スクリプトブロックに $Message 変数を渡すために使用されます。

例 12: ログエントリを並列で取得する

この例では、ローカル Windows マシン上の 5 つのシステムログから 50,000 個のログエントリを取得します。

$logNames = 'Security','Application','System','Windows PowerShell','Microsoft-Windows-Store/Operational'

$logEntries = $logNames | ForEach-Object -Parallel {
    Get-WinEvent -LogName $_ -MaxEvents 10000
} -ThrottleLimit 5

$logEntries.Count

Parallel パラメーターは、入力ログ名ごとに並行して実行されるスクリプトブロックを指定します。 ThrottleLimit パラメーターを使用すると、5 つのスクリプトブロックすべてが同時に実行されます。

例 13: ジョブとして並列で実行する

この例では、単純なスクリプトブロックを並行して実行し、一度に 2 つのバックグラウンドジョブを作成します。

$job = 1..10 | ForEach-Object -Parallel {
    "Output: $_"
    Start-Sleep 1
} -ThrottleLimit 2 -AsJob

$job | Receive-Job -Wait

Output: 1
Output: 2
Output: 3
Output: 4
Output: 5
Output: 6
Output: 7
Output: 8
Output: 9
Output: 10

$job変数は、出力データを収集し、実行状態を監視するジョブオブジェクトを受け取ります。ジョブオブジェクトは、待機スイッチパラメータを使用してReceive-Jobにパイプされます。そして、これは、AsJobなしで実行されたかのように、出力ForEach-Object -Parallelコンソールにストリーミングされます。

例 14: スレッドセーフ変数参照の使用

この例では、スクリプトブロックを並列で呼び出して、一意の名前の Process オブジェクトを収集します。

$threadSafeDictionary = [System.Collections.Concurrent.ConcurrentDictionary[string,object]]::new()
Get-Process | ForEach-Object -Parallel {
    $dict = $using:threadSafeDictionary
    $dict.TryAdd($_.ProcessName, $_)
}

$threadSafeDictionary["pwsh"]

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
     82    82.87     130.85      15.55    2808   2 pwsh

ConcurrentDictionary オブジェクトの 1 つのインスタンスが各スクリプトブロックに渡され、オブジェクトが収集されます。 ConcurrentDictionary はスレッドセーフであるため、各並列スクリプトで変更しても安全です。 System.Collections.Generic.Dictionary などのスレッドセーフでないオブジェクトは、ここでは安全に使用できません。

注

この例は、 Parallel パラメーターの非常に非効率的な使用です。スクリプトは、入力オブジェクトを同時ディクショナリオブジェクトに追加するだけです。これは些細なことであり、個別のスレッドで各スクリプトを呼び出すオーバーヘッドに見合う価値はありません。 パラレルスイッチなしでForEach-Objectを通常どおり実行すると、はるかに効率的かつ高速になります。この例は、スレッドセーフ変数を使用する方法を示すことを目的としています。

例 15: 並列実行によるエラーの書き込み

この例では、書き込まれたエラーの順序がランダムであるエラーストリームに並列で書き込みます。

1..3 | ForEach-Object -Parallel {
    Write-Error "Error: $_"
}

Write-Error: Error: 1
Write-Error: Error: 3
Write-Error: Error: 2

例 16: 並列実行でのエラーの終了

この例では、1 つの並列実行スクリプトブロックで終了エラーを示します。

1..5 | ForEach-Object -Parallel {
    if ($_ -eq 3)
    {
        throw "Terminating Error: $_"
    }

    Write-Output "Output: $_"
}

Exception: Terminating Error: 3
Output: 1
Output: 4
Output: 2
Output: 5

Output: 3 は、そのイテレーションの並列スクリプトブロックが終了したために書き込まれることはありません。

注

PipelineVariable 共通パラメーター変数は、キーワードを使用しても Foreach-Object -Parallel シナリオではサポート $using:。

例 17: 入れ子になった並列スクリプト ScriptBlockSet で変数を渡す

Foreach-Object -Parallel スコープの scriptblock の外部に変数を作成し、$using キーワードを使用して scriptblock 内で使用できます。

$test1 = 'TestA'
1..2 | Foreach-Object -Parallel {
    $using:test1
}

TestA
TestA

# You CANNOT create a variable inside a scoped scriptblock
# to be used in a nested foreach parallel scriptblock.
$test1 = 'TestA'
1..2 | Foreach-Object -Parallel {
    $using:test1
    $test2 = 'TestB'
    1..2 | Foreach-Object -Parallel {
        $using:test2
    }
}

Line |
   2 |  1..2 | Foreach-Object -Parallel {
     |         ~~~~~~~~~~~~~~~~~~~~~~~~~~
     | The value of the using variable '$using:test2' cannot be retrieved because it has not been set in the local session.

入れ子になった scriptblock は $test2 変数にアクセスできないため、エラーがスローされます。

パラメーター

-ArgumentList

メソッド呼び出しに対する引数の配列を指定します。 ArgumentListの動作 () の詳細については、about_Splattingを参照してください。

このパラメーターは、Windows PowerShell 3.0 で導入されました。

パラメーターのプロパティ

型:	Object[]
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False
Aliases:	引数

パラメーターセット

PropertyAndMethodSet

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-AsJob

並列呼び出しを PowerShell ジョブとして実行します。実行中のスクリプトブロックからの出力ではなく、1 つのジョブオブジェクトが返されます。ジョブオブジェクトには、実行する各並列スクリプトブロックの子ジョブが含まれています。ジョブオブジェクトは、すべての PowerShell ジョブコマンドレットで使用して、実行状態を監視し、データを取得できます。

このパラメーターは PowerShell 7.0 で導入されました。

パラメーターのプロパティ

型:	SwitchParameter
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーターセット

ParallelParameterSet

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-Begin

このコマンドレットが入力オブジェクトを処理する前に実行されるスクリプトブロックを指定します。このスクリプトブロックは、パイプライン全体に対して 1 回だけ実行されます。 begin ブロックの詳細については、「about_Functions」を参照してください。

パラメーターのプロパティ

型:	ScriptBlock
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーターセット

ScriptBlockSet

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-Confirm

コマンドレットを実行する前に確認を求めるメッセージが表示されます。

パラメーターのプロパティ

型:	SwitchParameter
規定値:	False
ワイルドカードのサポート:	False
DontShow:	False
Aliases:	cf

パラメーターセット

(All)

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-End

このコマンドレットがすべての入力オブジェクトを処理した後に実行されるスクリプトブロックを指定します。このスクリプトブロックは、パイプライン全体に対して 1 回だけ実行されます。 end ブロックの詳細については、「about_Functions」を参照してください。

パラメーターのプロパティ

型:	ScriptBlock
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーターセット

ScriptBlockSet

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-InputObject

入力オブジェクトを指定します。 ForEach-Object は、各入力オブジェクトに対してスクリプトブロックまたは操作ステートメントを実行します。オブジェクトを含む変数を入力するか、オブジェクトを取得するコマンドまたは式を入力します。

で ForEach-Object パラメーターを使用する場合、コマンドの結果をForEach-Objectにパイプするのではなく、InputObject 値は 1 つのオブジェクトとして扱われます。これは、値がコマンドの結果であるコレクション ( -InputObject (Get-Process) など) の場合でも当てはまります。 InputObject は配列またはオブジェクトのコレクションから個々のプロパティを返すことができないため、ForEach-Object を使用して、定義されたプロパティに特定の値を持つオブジェクトのオブジェクトのコレクションに対して操作を実行する場合は、このトピックの例に示すように、パイプラインで ForEach-Object を使用することをお勧めします。

パラメーターのプロパティ

型:	PSObject
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーターセット

(All)

配置:	Named
必須:	False
パイプラインからの値:	True
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-MemberName

取得するプロパティまたは呼び出すメソッドを指定します。

ワイルドカード文字は許可されますが、結果の文字列が一意の値に解決される場合にのみ機能します。たとえば、Get-Process | ForEach -MemberName *Nameを実行すると、ワイルドカードパターンが複数のメンバーと一致し、コマンドが失敗します。

このパラメーターは、Windows PowerShell 3.0 で導入されました。

パラメーターのプロパティ

型:	String
規定値:	None
ワイルドカードのサポート:	True
DontShow:	False

パラメーターセット

PropertyAndMethodSet

配置:	0
必須:	True
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-Parallel

入力オブジェクトの並列処理に使用するスクリプトブロックを指定します。操作を記述するスクリプトブロックを入力します。

このパラメーターは PowerShell 7.0 で導入されました。

パラメーターのプロパティ

型:	ScriptBlock
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーターセット

ParallelParameterSet

配置:	Named
必須:	True
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-Process

各入力オブジェクトに対して実行される操作を指定します。このスクリプトブロックは、パイプライン内のすべてのオブジェクトに対して実行されます。 process ブロックの詳細については、「about_Functions」を参照してください。

Process パラメーターに複数のスクリプトブロックを指定すると、最初のスクリプトブロックは常に begin ブロックにマップされます。スクリプトブロックが 2 つしかない場合、2 つ目のブロックは process ブロックにマップされます。スクリプトブロックが 3 つ以上ある場合、最初のスクリプトブロックは常に begin ブロックにマッピングされ、最後のブロックは end ブロックにマッピングされ、その間のブロックはすべて process ブロックにマッピングされます。

パラメーターのプロパティ

型:	ScriptBlock[]
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーターセット

ScriptBlockSet

配置:	0
必須:	True
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-RemainingScripts

Process パラメータによって取得されないすべてのスクリプトブロックを指定します。

このパラメーターは、Windows PowerShell 3.0 で導入されました。

パラメーターのプロパティ

型:	ScriptBlock[]
規定値:	None
ワイルドカードのサポート:	False
DontShow:	False

パラメーターセット

ScriptBlockSet

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-ThrottleLimit

並列に並べるスクリプトブロックの数を指定します。実行中のスクリプトブロック数が ThrottleLimit を下回るまで、入力オブジェクトはブロックされます。既定値は 5 です。

このパラメーターは PowerShell 7.0 で導入されました。

パラメーターのプロパティ

型:	Int32
規定値:	5
ワイルドカードのサポート:	False
DontShow:	False

パラメーターセット

ParallelParameterSet

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-TimeoutSeconds

すべての入力が並列に処理されるまで待機する秒数を指定します。指定したタイムアウト時間が経過すると、実行中のすべてのスクリプトが停止します。また、処理する残りの入力オブジェクトは無視されます。既定値の 0 はタイムアウトを無効にし、 ForEach-Object -Parallel は無期限に実行できます。コマンドラインで Ctrl+C と入力すると、実行中の ForEach-Object -Parallel コマンドが停止します。このパラメータは、 AsJob パラメータと一緒に使用することはできません。

このパラメーターは PowerShell 7.0 で導入されました。

パラメーターのプロパティ

型:	Int32
規定値:	0
ワイルドカードのサポート:	False
DontShow:	False

パラメーターセット

ParallelParameterSet

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-UseNewRunspace

並列呼び出しでは、実行スペースプールから実行空間を再利用するのではなく、ループイテレーションごとに新しい実行空間を作成します。

このパラメーターは PowerShell 7.1 で導入されました

パラメーターのプロパティ

型:	SwitchParameter
規定値:	False
ワイルドカードのサポート:	False
DontShow:	False

パラメーターセット

ParallelParameterSet

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

-WhatIf

コマンドレットを実行した場合の動作を示します。コマンドレットは実行されません。

パラメーターのプロパティ

型:	SwitchParameter
規定値:	False
ワイルドカードのサポート:	False
DontShow:	False
Aliases:	ウィスコンシン

パラメーターセット

(All)

配置:	Named
必須:	False
パイプラインからの値:	False
プロパティ名別のパイプラインからの値:	False
残りの引数からの値:	False

CommonParameters

このコマンドレットでは、一般的なパラメーター -Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction、-WarningVariable の各パラメーターがサポートされています。詳細については、about_CommonParametersを参照してください。

入力

PSObject

任意のオブジェクトをこのコマンドレットにパイプできます。

出力

PSObject

このコマンドレットは、入力によって決定されるオブジェクトを返します。

メモ

ForEach-Object コマンドレットは、Foreach ステートメントとよく似ていますが、Foreach ステートメントに入力をパイプすることはできません。 Foreach ステートメントの詳細については、about_Foreachを参照してください。

PowerShell 4.0 以降では、コレクションで使用するために Where メソッドと ForEach メソッドが追加されました。これらの新しいメソッドの詳細については、about_arrays

ForEach-Object -Parallelの使用

ForEach-Object -Parallel パラメーターセットは、PowerShell の内部 API を使用して、新しい実行空間で各スクリプトブロックを実行します。これは、順次処理で通常 ForEach-Object を実行するよりもはるかにオーバーヘッドが高くなります。スクリプトブロックが実行する作業と比較して、並列実行のオーバーヘッドが小さい場合は、 Parallel を使用することが重要です。例えば次が挙げられます。
- マルチコアマシンでのコンピューティング集中型スクリプト
- 結果の待機またはファイル操作の実行に時間を費やすスクリプト
Parallel パラメーターを使用すると、スクリプトの実行速度が通常よりもはるかに遅くなる可能性があります。特に、並列スクリプトが単純な場合。 Parallel を試して、それが有益な場所を見つけます。
並行して実行する場合、 ScriptProperties または ScriptMethods で修飾されたオブジェクトは、スクリプトが元々アタッチされていたものとは異なる実行空間で実行されると、正しく機能することを保証できません。

Scriptblock 呼び出しは、実際に呼び出された場所に関係なく、常に ホーム ランスペースで実行を試みます。ただし、 ForEach-Object -Parallel は使用後に削除される一時的な実行空間を作成するため、スクリプトを実行するための実行空間はもうありません。

この動作は、 ホーム ランスペースがまだ存在する限り機能します。ただし、スクリプトが呼び出し元の実行空間にのみ存在し、 ホーム ランスペースに存在しない外部変数に依存している場合は、目的の結果が得られない場合があります。
終了しないエラーは、スクリプトブロックの並列実行で発生するため、コマンドレットエラーストリームに書き込まれます。並列スクリプトブロックの実行順序は非決定論的であるため、エラーストリームにエラーが表示される順序はランダムです。同様に、警告、詳細、情報などの他のデータストリームに書き込まれたメッセージは、不確定な順序でそれらのデータストリームに書き込まれます。

例外などの終了エラーは、発生するスクリプトブロックの個々の並列インスタンスを終了します。 1 つのスクリプトブロックで終了エラーが発生しても、 Foreach-Object コマンドレットが終了しない可能性があります。他のスクリプトブロックは、並列で実行され、終了エラーが発生しない限り、引き続き実行されます。終了するエラーは、エラーデータストリームに、 の FullyQualifiedErrorId を持つ PSTaskException として書き込まれます。終了エラーは、PowerShell try/catch ブロックまたは trap ブロックを使用して、終了しないエラーに変換できます。
PipelineVariable 共通パラメーター変数は、キーワードを使用しても並列シナリオではサポート $using:。

Von Bedeutung

ForEach-Object -Parallel パラメーターセットは、個別のプロセススレッドでスクリプトブロックを並列に実行します。 $using: キーワードを使用すると、コマンドレット呼び出しスレッドから実行中の各スクリプトブロックスレッドに変数参照を渡すことができます。スクリプトブロックは異なるスレッドで実行されるため、参照によって渡されるオブジェクト変数は安全に使用する必要があります。通常、変更されない参照オブジェクトから読み取るのは安全です。ただし、オブジェクトの状態を変更する場合は、.NET System.Collection.Concurrent 型などのスレッドセーフオブジェクトを使用する必要があります (例 11 を参照)。

次の方法で共有

ForEach-Object

構文

ScriptBlockSet (既定)

PropertyAndMethodSet

ParallelParameterSet

説明

例

例 1: 配列内の整数を除算する

例 2: ディレクトリ内のすべてのファイルの長さを取得する

例 3: 最新のシステム イベントを操作する

例 4: レジストリ キーの値を変更する

例 5: $Null自動変数を使用する

例 6: プロパティ値を取得する

例 7: モジュール名をコンポーネント名に分割する

例 8: 2 つのスクリプト ブロックで ForEach-Object を使用する

例 9: 2 つ以上のスクリプト ブロックで ForEach-Object を使用する

例 10: パイプライン項目ごとに複数のスクリプト ブロックを実行する

例 11: 低速スクリプトを並列バッチで実行する

例 12: ログ エントリを並列で取得する

例 13: ジョブとして並列で実行する

例 14: スレッド セーフ変数参照の使用

例 15: 並列実行によるエラーの書き込み

例 16: 並列実行でのエラーの終了

例 17: 入れ子になった並列スクリプト ScriptBlockSet で変数を渡す

パラメーター

-ArgumentList

パラメーターのプロパティ

パラメーター セット

-AsJob

パラメーターのプロパティ

パラメーター セット

-Begin

パラメーターのプロパティ

パラメーター セット

-Confirm

パラメーターのプロパティ

パラメーター セット

-End

パラメーターのプロパティ

パラメーター セット

-InputObject

パラメーターのプロパティ

パラメーター セット

-MemberName

パラメーターのプロパティ

パラメーター セット

-Parallel

パラメーターのプロパティ

パラメーター セット

-Process

パラメーターのプロパティ

パラメーター セット

-RemainingScripts

パラメーターのプロパティ

パラメーター セット

-ThrottleLimit

パラメーターのプロパティ

パラメーター セット

-TimeoutSeconds

パラメーターのプロパティ

パラメーター セット

-UseNewRunspace

パラメーターのプロパティ

パラメーター セット

-WhatIf

パラメーターのプロパティ

パラメーター セット

CommonParameters

入力

PSObject

出力

PSObject

メモ

関連リンク

例 3: 最新のシステムイベントを操作する

例 4: レジストリキーの値を変更する

例 8: 2 つのスクリプトブロックで ForEach-Object を使用する

例 9: 2 つ以上のスクリプトブロックで ForEach-Object を使用する

例 10: パイプライン項目ごとに複数のスクリプトブロックを実行する

例 12: ログエントリを並列で取得する

例 14: スレッドセーフ変数参照の使用

パラメーターセット

パラメーターセット

パラメーターセット

パラメーターセット

パラメーターセット

パラメーターセット

パラメーターセット

パラメーターセット

パラメーターセット

パラメーターセット

パラメーターセット

パラメーターセット

パラメーターセット

パラメーターセット