ForEach-Object

语法

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

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

ForEach-Object
            -Parallel <scriptblock>
            [-InputObject <psobject>]
            [-ThrottleLimit <int>]
            [-TimeoutSeconds <int>]
            [-AsJob]
            [-UseNewRunspace]
            [-WhatIf]
            [-Confirm]
            [<CommonParameters>]

说明

cmdlet ForEach-Object 对输入对象集合中的每个项执行操作。 输入对象可以通过管道传递给 cmdlet，也可以使用 InputObject 参数指定。

从 Windows PowerShell 3.0 开始，可通过两种不同的方法来构造ForEach-Object命令。

• 脚本块。 你可以使用某个脚本块来指定操作。 在脚本块中，使用 $_ 变量表示当前对象。 脚本块是 Process 参数的值。 脚本块可以包含任何 PowerShell 脚本。

  例如，以下命令将获取计算机上每个进程的 ProcessName 属性值。

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

  ForEach-Object支持 、 process和 end 块，begin如 about_functions 中所述。

  注意

  脚本块在调用方的范围内运行。 因此，这些块有权访问该范围内的变量，并且可以在 cmdlet 完成后创建在该范围内保留的新变量。

• 操作语句。 还可以编写操作语句，这更像是自然语言。 你可以使用该操作语句来指定属性值或调用方法。 Windows PowerShell 3.0 中引入了操作语句。

  例如，以下命令还将获取计算机上每个进程的 ProcessName 属性值。

  Get-Process | ForEach-Object ProcessName

• 并行运行的脚本块。 从 PowerShell 7.0 开始，可以使用第三个参数集并行运行每个脚本块。 ThrottleLimit 参数限制一次运行的并行脚本数。 如前所述，使用 $_ 变量表示脚本块中的当前输入对象。 $using: 使用关键字 (keyword) 将变量引用传递给正在运行的脚本。

  在 PowerShell 7 中，为每个循环迭代创建新的运行空间，以确保最大隔离。 如果正在执行的工作与创建新运行空间相比较小，或者执行大量工作，则可能会对性能和资源造成较大影响。 从 PowerShell 7.1 起，默认情况下会重复使用 runspace 池中的 runspace。 ThrottleLimit 参数设置运行空间池大小。 默认运行空间池大小为 5。 你仍然可以使用 UseNewRunspace 开关为每个迭代创建新的 runspace。

  默认情况下，并行脚本块使用启动并行任务的调用方当前工作目录。

  有关详细信息，请参阅本文的 NOTES 部分。

示例

示例 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的所有子项中的 RemotePath 注册表项的值更改为大写文本。

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

可以使用此格式更改注册表条目值的形式或内容。

网络密钥中的每个子项都表示一个映射的网络驱动器，该驱动器在登录时重新连接。 RemotePath 项包含连接的驱动器的 UNC 路径。 例如，如果将驱动器映射到 E:\\Server\Share，则会在 中创建 HKCU:\NetworkE 子项，并将 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-ObjectPath 属性的值。

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

第二个命令等效于第一个命令。 它使用 Foreach cmdlet 的 ForEach-Object 别名，并省略 MemberName 参数的名称，这是可选的。

cmdlet ForEach-Object 可用于获取属性值，因为它获取值而不更改类型，这与 格式 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 参数将点 (.) 标识为拆分分隔符。

第三个命令使用 cmdlet 的 ForEach-ObjectForeach 别名，并省略 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

示例 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：并行批处理运行慢脚本

此示例运行一个脚本块，该脚本块计算字符串并休眠一秒钟。

$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，以便四个批次处理输入。 关键字 (keyword) $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

50000

Parallel 参数指定为每个输入日志名称并行运行的脚本块。 ThrottleLimit 参数可确保所有五个脚本块同时运行。

示例 13：作为作业并行运行

此示例创建一个作业，该作业并行运行一个脚本块，一次运行两个脚本块。

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

PS> $job

Id     Name            PSJobTypeName   State         HasMoreData     Location      Command
--     ----            -------------   -----         -----------     --------      -------
23     Job23           PSTaskJob       Running       True            PowerShell    …

PS> $job.ChildJobs

Id     Name            PSJobTypeName   State         HasMoreData     Location      Command
--     ----            -------------   -----         -----------     --------      -------
24     Job24           PSTaskChildJob  Completed     True            PowerShell    …
25     Job25           PSTaskChildJob  Completed     True            PowerShell    …
26     Job26           PSTaskChildJob  Running       True            PowerShell    …
27     Job27           PSTaskChildJob  Running       True            PowerShell    …
28     Job28           PSTaskChildJob  NotStarted    False           PowerShell    …
29     Job29           PSTaskChildJob  NotStarted    False           PowerShell    …
30     Job30           PSTaskChildJob  NotStarted    False           PowerShell    …
31     Job31           PSTaskChildJob  NotStarted    False           PowerShell    …
32     Job32           PSTaskChildJob  NotStarted    False           PowerShell    …
33     Job33           PSTaskChildJob  NotStarted    False           PowerShell    …

ThrottleLimit 参数限制一次运行的并行脚本块数。 AsJob 参数使 ForEach-Object cmdlet 返回作业对象，而不是将流式输出返回到控制台。 变量 $job 接收收集输出数据和监视运行状态的作业对象。 属性 $job.ChildJobs 包含运行并行脚本块的子作业。

示例 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 对象的单个实例将传递到每个脚本块以收集对象。 由于 ConcurrentDictionary 是线程安全的，因此可以安全地由每个并行脚本进行修改。 非线程安全对象（如 System.Collections.Generic.Dictionary）在这里使用不安全。

示例 15：使用并行执行写入错误

此示例并行写入错误流，其中写入错误的顺序是随机的。

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

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

示例 16：在并行执行中终止错误

此示例演示一个并行运行的脚本块中的终止错误。

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 永远不会写入，因为该迭代的并行脚本块已终止。

示例 17：在嵌套并行脚本 ScriptBlockSet 中传递变量

可以在作用域的脚本块外部Foreach-Object -Parallel创建变量，并在脚本块$using中使用该变量和关键字 (keyword) 。

$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' can't be retrieved because it has
     | not been set in the local session.

嵌套脚本块无法访问变量 $test2 ，并引发错误。

示例 18：创建多个并行运行脚本的作业

ThrottleLimit 参数限制在每个 实例 ForEach-Object -Parallel期间运行的并行脚本数。 它不会限制使用 AsJob 参数时可以创建的作业数。 由于作业本身是并发运行的，因此可以创建多个并行作业，每个作业的运行上限为并发脚本块的限制数。

$jobs = for ($i=0; $i -lt 10; $i++) {
    1..10 | ForEach-Object -Parallel {
        ./RunMyScript.ps1
    } -AsJob -ThrottleLimit 5
}

$jobs | Receive-Job -Wait

此示例创建 10 个正在运行的作业。 每个作业同时运行不超过 5 个脚本。 并发运行的实例总数限制为 50 个 (10 个作业， 而 ThrottleLimit 为 5) 。

参数

-ArgumentList

-AsJob

-Begin

-Confirm

-End

-InputObject

-MemberName

-Parallel

-Process

-RemainingScripts

-ThrottleLimit

-TimeoutSeconds

-UseNewRunspace

-WhatIf

输入

PSObject

你可以通过管道将任何对象传递给此 cmdlet。

输出

PSObject

此 cmdlet 返回由输入确定的对象。

备注

PowerShell 包含以下别名 ForEach-Object：

• 所有平台：
  • %
  • foreach

ForEach-Object cmdlet 的工作方式与 Foreach 语句非常类似，只是不能通过管道将输入传递给 Foreach 语句。 有关 Foreach 语句的详细信息，请参阅 about_Foreach。

从 PowerShell 4.0 开始， WhereForEach 添加了用于集合的方法。 可在此处阅读有关这些新方法 的详细信息about_arrays

使用 ForEach-Object -Parallel：

• ForEach-Object -Parallel 在新 runspace 中运行每个脚本块。 与使用顺序处理运行 ForEach-Object 相比，新运行空间产生的开销要大得多。 与脚本块执行的工作相比，并行运行的开销较小时，使用 Parallel 非常重要。 例如：

  • 多核计算机上的计算密集型脚本
  • 花费时间等待结果或执行文件操作的脚本

  使用 Parallel 参数可能会导致脚本的运行速度比平常慢得多。 尤其是当并行脚本是普通的时。 尝试 使用 Parallel 来发现它可能有益的位置。

• 并行运行时，如果用 ScriptProperties 或 ScriptMethods 修饰的对象在与最初附加到它们的脚本不同的运行空间中运行，则无法保证它们正常运行。

  无论实际调用的位置如何，Scriptblock 调用始终尝试在其 主 运行空间中运行。 但是， ForEach-Object -Parallel 会创建在使用后删除的临时运行空间，因此不再有运行空间供脚本执行。

  只要 主 运行空间仍然存在，此行为就可以工作。 但是，如果脚本依赖于仅存在于调用方 runspace 而不是 主 运行空间中的外部变量，则可能无法获得所需的结果。

• 非终止错误将写入 cmdlet 错误流，因为它们在并行运行的脚本块中发生。 由于并行 scriptblock 执行顺序是不确定的，因此错误在错误流中的出现顺序是随机的。 同样，写入其他数据流（如警告、详细或信息）的消息将按不确定的顺序写入这些数据流。

  终止错误（如异常）会终止发生错误的脚本块的各个并行实例。 一个脚本块中的终止错误可能不会导致 cmdlet 的 Foreach-Object 终止。 其他并行运行的脚本块将继续运行，除非它们也遇到终止错误。 终止错误作为 ErrorRecord 写入到错误数据流中， 其 FullyQualifiedErrorId 为 PSTaskException。 终止错误可以使用 PowerShell try/catch 或 trap 块转换为非终止错误。

• 即使使用 $using: 关键字 (keyword) ，并行方案中也不支持PipelineVariable 通用参数变量。

  重要

  参数 ForEach-Object -Parallel 集在单独的进程线程上并行运行脚本块。 关键字 (keyword) $using: 允许将变量引用从 cmdlet 调用线程传递到每个正在运行的脚本块线程。 由于脚本块在不同的线程中运行，因此必须安全地使用引用传递的对象变量。 通常，从不更改的引用对象进行读取是安全的。 如果需要修改对象状态，则必须使用线程安全对象，例如 .NET System.Collection.Concurrent 类型 (请参阅示例 14) 。

相关链接

• Compare-Object
• Where-Object
• Group-Object
• Measure-Object
• New-Object
• Select-Object
• Sort-Object
• Tee-Object