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>]

Description

ForEach-Object Cmdlet 會在輸入物件集合中的每個項目上執行作業。 輸入物件可以使用管線傳送至 Cmdlet，或使用 InputObject 參數指定。

從 Windows PowerShell 3.0 開始，有兩種不同的方法來建構 ForEach-Object 命令。

• 腳本區塊語法。 您可以使用文稿區塊來指定作業。 在腳本區塊內，使用 $_ 變數來表示目前的物件。 腳本區塊是 Process 參數的值。 腳本區塊可以包含任何 PowerShell 腳本。

  例如，下列命令會取得計算機上每個進程的 ProcessName 屬性值。

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

  ForEach-Object begin支援、 process和 end 區塊，如about_Functions中所述。

  備註

  腳本區塊會在呼叫端的範圍中執行。 因此，區塊可以存取該範圍中的變數，而且可以在 Cmdlet 完成之後，建立該範圍中保存的新變數。

• 簡化的語法。 使用簡化的語法，您可以在管線中指定 物件的屬性或方法名稱。 ForEach-Object 會傳回管線中每個物件的 屬性或方法值。

  例如，下列命令也會取得計算機上每個進程的 ProcessName 屬性值。

  Get-Process | ForEach-Object ProcessName

  簡化的語法是在 Windows PowerShell 3.0 中引進的。 如需詳細資訊，請參閱 about_Simplified_Syntax。

範例

範例 1：在陣列中除整數

此範例會採用三個整數的數位，並將其中每個整數除以 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，並新增空格 （“ ”） 以將它與下一個專案分開。 Cmdlet 會使用 PSIsContainer 屬性來判斷物件是否為目錄。

範例 3：在最近的系統事件上作

這個範例會將 1000 個最新的事件從系統事件記錄檔寫入文字檔。 目前的時間會顯示在處理事件之前和之後。

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

Get-EventLog 會從系統事件記錄檔取得 1000 個最新的事件，並將其傳送至 ForEach-Object Cmdlet。 Begin 參數會顯示目前的日期和時間。 接下來， Process 參數會 Out-File 使用 Cmdlet 來建立名為 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，則會在 中建立HKCU:\Network子機碼，並將 RemotePath 登錄值設定為 \\Server\Share。

此命令會 Get-ItemProperty 使用 Cmdlet 來取得 網路 機碼和 Set-ItemProperty Cmdlet 的所有子機碼，以變更每個機碼中 RemotePath 登錄專案的值。 在命令中 Set-ItemProperty ，路徑是登錄機碼 的 PSPath 屬性值。 這是Microsoft .NET Framework 對象的屬性，代表登錄機碼，而不是登錄專案。 此命令會使用 RemotePath 值的 ToUpper（） 方法，這是字串REG_SZ。

因為 Set-ItemProperty 變更每個索引鍵的 屬性，因此需要 ForEach-Object Cmdlet 才能存取 屬性。

範例 5：使用$null自動變數

此範例顯示將 $null 自動變數管線傳送至 ForEach-Object Cmdlet 的效果。

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

Hello
Hello
Hello
Hello

因為 PowerShell 會將 $null 視為明確的佔位符，所以 ForEach-Object Cmdlet 會產生值給 $null，就像用於管道傳送給它的其他物件一樣。

範例 6：取得屬性值

這個範例會使用 Cmdlet 的 MemberName 參數，取得所有已安裝 PowerShell 模組之 ForEach-Object 屬性的值。

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

第二個命令相當於第一個命令。 它會使用 Foreach Cmdlet 的 ForEach-Object 別名，並省略 MemberName 參數的名稱，這是選擇性的。

ForEach-Object Cmdlet 對於取得屬性值很有用，因為它會取得值而不變更類型，不同於 Format Cmdlet 或 Select-Object Cmdlet，這會變更屬性值類型。

範例 7：將模組名稱分割成元件名稱

此範例示範三種方式可將兩個點分隔的模組名稱分割成其元件名稱。 命令會呼叫字串的 Split 方法。 這三個命令使用不同的語法，但它們是相等且可互換的。 這三個案例的輸出都相同。

"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

第一個命令會使用傳統語法，其中包含腳本區塊和目前的物件運算子 $_。 它會使用點語法來指定方法及括弧來括住分隔符自變數。

第二個命令會使用 MemberName 參數來指定 Split 方法和 ArgumentList 參數，以識別點 （.） 做為分割分隔符。

第三個命令會使用 foreach Cmdlet 的 ForEach-Object 別名，並省略 MemberName 和 ArgumentList 參數的名稱，這些參數是選擇性的。

範例 8：搭配兩個腳本區塊使用 ForEach-Object

在此範例中，我們會以位置傳遞兩個腳本區塊。 所有腳本區塊都會系結至 Process 參數。 不過，它們會被視為已傳遞至 Begin 和 Process 參數。

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

begin
process
process

範例 9：搭配兩個以上的腳本區塊使用 ForEach-Object

在此範例中，我們會以位置傳遞四個腳本區塊。 所有腳本區塊都會系結至 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

參數

-ArgumentList

指定方法呼叫的自變數陣列。 如需 ArgumentList行為的詳細資訊，請參閱 about_Splatting。

此參數是在 Windows PowerShell 3.0 中引進的。

參數屬性

類型:	Object[]
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	參數

參數集

PropertyAndMethodSet

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Begin

指定在此 Cmdlet 處理任何輸入物件之前執行的腳本區塊。 此腳本區塊只會針對整個管線執行一次。 如需區塊的詳細資訊 begin ，請參閱 about_Functions。

參數屬性

類型:	ScriptBlock
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ScriptBlockSet

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Confirm

在執行 Cmdlet 之前，提示您進行確認。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False
別名:	cf

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-End

指定在此 Cmdlet 處理所有輸入物件之後執行的腳本區塊。 此腳本區塊只會針對整個管線執行一次。 如需區塊的詳細資訊 end ，請參閱 about_Functions。

參數屬性

類型:	ScriptBlock
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ScriptBlockSet

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-InputObject

指定輸入物件。 ForEach-Object 在每個輸入物件上執行腳本區塊或 operation 語句。 輸入包含 物件的變數，或輸入取得物件的命令或表達式。

當您搭配 使用 ForEach-Object 參數時，ForEach-Object 值會視為單一物件，而不是將命令結果 。 即使值是命令結果的集合，例如 -InputObject (Get-Process)也是如此。 因為 InputObject 無法從物件的陣列或集合傳回個別屬性，因此，如果您針對 ForEach-Object 那些在定義屬性中具有特定值的物件執行作業，請在 ForEach-Object 管線中使用 ，如本主題的範例所示。

參數屬性

類型:	PSObject
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	True
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-MemberName

指定要取得的成員屬性名稱，或要呼叫的成員方法。 成員必須是實例成員，而不是靜態成員。

允許通配符，但只有在產生的字串解析為唯一值時，才能運作。 例如，如果您執行 Get-Process | foreach -MemberName *Name，通配符模式會比對多個造成命令失敗的成員。

此參數是在 Windows PowerShell 3.0 中引進的。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	True
不要顯示:	False

參數集

PropertyAndMethodSet

Position:	0
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Process

指定在每個輸入物件上執行的作業。 此腳本區塊會針對管線中的每個物件執行。 如需區塊的詳細資訊 process ，請參閱 about_Functions。

當您將多個腳本區塊提供給 Process 參數時，第一個腳本區塊一律會對應至 begin 區塊。 如果只有兩個腳本區塊，則第二個區塊會對應至 process 區塊。 如果有三個以上的腳本區塊，第一個腳本區塊一律會對應至 begin 區塊，最後一個區塊會對應至 end 區塊，而中間區塊則會對應至 process 區塊。

參數屬性

類型:	ScriptBlock[]
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ScriptBlockSet

Position:	0
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-RemainingScripts

指定 Process 參數未採用的所有腳本區塊。

此參數是在 Windows PowerShell 3.0 中引進的。

參數屬性

類型:	ScriptBlock[]
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ScriptBlockSet

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-WhatIf

顯示 Cmdlet 執行時會發生什麼事。 該 Cmdlet 未被執行。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False
別名:	無線

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CommonParameters

此 Cmdlet 支援一般參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。

輸入

PSObject

您可以將任何物件通過管道傳遞至此命令工具。

輸出

PSObject

此 Cmdlet 會傳回由輸入決定的物件。

備註

Windows PowerShell 包含下列 ForEach-Object的別名：

• %
• foreach

ForEach-Object Cmdlet 的運作方式非常類似 foreach 語句，不同之處在於您無法使用管線將輸入傳送至 foreach 語句。 如需 語句的詳細資訊 foreach ，請參閱 about_Foreach。

從 PowerShell 4.0 開始，已新增 Where 和 ForEach 方法來搭配集合使用。 您可以在這裡深入了解這些新方法 about_Arrays

相關連結

• 比較物件 (Compare-Object)
• Where-Object
• 群組物件
• 測量物件
• New-Object
• 選擇物件
• 排序物件 (Sort-Object)
• Tee-Object