Partilhar via

ForEach-Object

Módulo:
Microsoft.PowerShell.Core Module

Executa uma operação em relação a cada item em uma coleção de objetos de entrada.

Sintaxe

ScriptBlockSet (Padrão) 

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 <int>]
    [-TimeoutSeconds <int>]
    [-AsJob]
    [-UseNewRunspace]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Descrição

O ForEach-Object cmdlet executa uma operação em cada item de uma coleção de objetos de entrada. Os objetos de entrada podem ser canalizados para o cmdlet ou especificados usando o parâmetro InputObject .

A partir do Windows PowerShell 3.0, há duas maneiras diferentes de construir um comando ForEach-Object.

  • Sintaxe do bloco de scripts. Podes usar um bloco de scripts para especificar a operação. Dentro do bloco de script, use a $_ variável para representar o objeto atual. O bloco de scripts é o valor do parâmetro Processo . O bloco de scripts pode conter qualquer script PowerShell.

    Por exemplo, o comando a seguir obtém o valor da propriedade ProcessName de cada processo no computador.

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

    ForEach-Object suporta os beginblocos , processe end conforme descrito em about_Functions.

    Observação

    Os blocos de script correm dentro do âmbito do chamador. Portanto, os blocos têm acesso a variáveis nesse escopo e podem criar novas variáveis que persistem nesse escopo após a conclusão do cmdlet.

  • Sintaxe simplificada. Usando a sintaxe simplificada, você especifica uma propriedade ou nome de método do objeto no pipeline. ForEach-Object Retorna o valor da propriedade ou método para cada objeto no pipeline.

    Por exemplo, o comando a seguir também obtém o valor da propriedade ProcessName de cada processo no computador.

    Get-Process | ForEach-Object ProcessName

    A sintaxe simplificada foi introduzida no Windows PowerShell 3.0. Para obter mais informações, consulte about_Simplified_Syntax.

  • Bloco de scripts a correr em paralelo. A partir do PowerShell 7.0, está disponível um terceiro conjunto de parâmetros que executa cada bloco de script em paralelo. O parâmetro ThrottleLimit limita o número de scripts paralelos em execução por vez. Como antes, use a $_ variável para representar o objeto de entrada atual no bloco de script. Use o Using: modificador de escopo para passar referências de variáveis para o script em execução.

    No PowerShell 7, um novo espaço de execução é criado para cada iteração de loop para garantir o máximo isolamento. Isso pode ser um grande impacto de desempenho e recursos se o trabalho que você está fazendo for pequeno em comparação com a criação de novos espaços de execução ou se houver muitas iterações executando um trabalho significativo. A partir do PowerShell 7.1, os espaços de execução de um pool de espaço de execução são reutilizados por padrão. O parâmetro ThrottleLimit define o tamanho do pool de espaço de execução. O tamanho padrão do pool de espaço de execução é 5. Você ainda pode criar um novo espaço de execução para cada iteração usando a opção UseNewRunspace .

    Por padrão, os blocos de script paralelos usam o diretório de trabalho atual do chamador que iniciou as tarefas paralelas.

    Para obter mais informações, consulte a seção NOTAS deste artigo.

Exemplos

Exemplo 1: Dividir inteiros em uma matriz

Este exemplo usa uma matriz de três inteiros e divide cada um deles por 1024.

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

29.296875
55.466796875
12.140625

Exemplo 2: Obter o comprimento de todos os arquivos em um diretório

Este exemplo processa os arquivos e diretórios no diretório $PSHOMEde instalação do PowerShell.

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

Se o objeto não for um diretório, o bloco de script recebe o nome do ficheiro, divide o valor da sua propriedade Comprimento por 1024 e adiciona um espaço (" ") para o separar da entrada seguinte. O cmdlet usa a propriedade PSIsContainer para determinar se um objeto é um diretório.

Exemplo 3: Operar nos eventos mais recentes do Sistema

Este exemplo grava os 1000 eventos mais recentes do log de eventos do sistema em um arquivo de texto. A hora atual é exibida antes e depois de processar os eventos.

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 obtém os 1000 eventos mais recentes do log de eventos do sistema e os canaliza para o ForEach-Object cmdlet. O parâmetro Begin exibe a data e a hora atuais. Em seguida, o parâmetro Process usa o Out-File cmdlet para criar um arquivo de texto chamado events.txt e armazena a propriedade message de cada um dos eventos nesse arquivo. Por último, o parâmetro End é usado para exibir a data e a hora após a conclusão de todo o processamento.

Exemplo 4: Alterar o valor de uma chave do Registro

Este exemplo altera o valor da entrada do Registro RemotePath em todas as subchaves sob a HKCU:\Network chave para texto em maiúsculas.

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

Você pode usar esse formato para alterar a forma ou o conteúdo de um valor de entrada do Registro.

Cada subchave na chave de rede representa uma unidade de rede mapeada que se reconecta ao fazer logon. A entrada RemotePath contém o caminho UNC da unidade conectada. Por exemplo, se você mapear a E: unidade para \\Server\Share, uma subchave E será criada com HKCU:\Network o valor do Registro RemotePath definido como \\Server\Share.

O comando usa o Get-ItemProperty cmdlet para obter todas as subchaves da chave Network e o Set-ItemProperty cmdlet para alterar o valor da entrada do Registro RemotePath em cada chave. Set-ItemProperty No comando, o caminho é o valor da propriedade PSPath da chave do Registro. Esta é uma propriedade do objeto Microsoft .NET Framework que representa a chave do Registro, não uma entrada do Registro. O comando usa o método ToUpper() do valor RemotePath , que é uma cadeia de caracteres REG_SZ.

Como Set-ItemProperty está alterando a propriedade de cada chave, o ForEach-Object cmdlet é necessário para acessar a propriedade.

Exemplo 5: Usar a variável automática $null

Este exemplo mostra o efeito da canalização da $null variável automática para o ForEach-Object cmdlet.

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

Hello
Hello
Hello
Hello

Como o PowerShell trata $null como um espaço reservado explícito, o ForEach-Object cmdlet gera um valor para $null outros objetos canalizados para ele.

Exemplo 6: Obter valores de propriedade

Este exemplo obtém o valor da propriedade Path de todos os módulos do PowerShell instalados usando o parâmetro MemberName do ForEach-Object cmdlet.

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

O segundo comando é equivalente ao primeiro. Ele usa o Foreach alias do ForEach-Object cmdlet e omite o nome do parâmetro MemberName , que é opcional.

O ForEach-Object cmdlet é útil para obter valores de propriedade, porque obtém o valor sem alterar o tipo, ao contrário dos cmdlets Format ou do Select-Object cmdlet, que alteram o tipo de valor da propriedade.

Exemplo 7: Dividir nomes de módulos em nomes de componentes

Este exemplo mostra três maneiras de dividir dois nomes de módulos separados por pontos em seus nomes de componentes. Os comandos chamam o método Split de strings. Os três comandos usam sintaxe diferente, mas são equivalentes e intercambiáveis. A saída é a mesma para os três casos.

"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

O primeiro comando utiliza a sintaxe tradicional, que inclui um bloco de scripts e o operador $_de objeto atual . Ele usa a sintaxe de ponto para especificar o método e parênteses para incluir o argumento delimitador.

O segundo comando usa o parâmetro MemberName para especificar o método Split e o parâmetro ArgumentList para identificar o ponto (.) como o delimitador de divisão.

O terceiro comando usa o foreach alias do ForEach-Object cmdlet e omite os nomes dos parâmetros MemberName e ArgumentList , que são opcionais.

Exemplo 8: Usar ForEach-Object com dois blocos de script

Neste exemplo, passamos dois blocos de script posicionalmente. Todos os blocos de script ligam ao parâmetro Process . No entanto, eles são tratados como se tivessem sido passados para os parâmetros Begin e Process .

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

begin
process
process

Exemplo 9: Usar ForEach-Object com mais de dois blocos de script

Neste exemplo, passamos quatro blocos de script posicionalmente. Todos os blocos de script ligam ao parâmetro Process . No entanto, eles são tratados como se tivessem sido passados para os parâmetros Begin, Process e End .

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

begin
process A
process B
process A
process B
end

Observação

O primeiro bloco de script é sempre mapeado para o begin bloco, o último bloco é mapeado para o end bloco, e os dois blocos do meio são mapeados para o process bloco.

Exemplo 10: Execute múltiplos blocos de script para cada item do pipeline

Como mostrado no exemplo anterior, múltiplos blocos de script passados usando o parâmetro Process são mapeados para os parâmetros Begin e End . Para evitar esse mapeamento, você deve fornecer valores explícitos para os parâmetros Begin e End .

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

one
two
three
one
two
three

Exemplo 11: Executar script lento em lotes paralelos

Este exemplo executa um bloco de scripts que avalia uma cadeia e entra em modo de suspensão durante um segundo.

$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

O valor do parâmetro ThrottleLimit é definido como 4 para que a entrada seja processada em lotes de quatro. O Using: modificador de âmbito é usado para passar a $Message variável para cada bloco de scripts paralelo.

Exemplo 12: Recuperar entradas de log em paralelo

Este exemplo recupera 50.000 entradas de log de 5 logs do sistema em uma máquina Windows local.

$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

O parâmetro Paralelo especifica o bloco de scripts que é executado em paralelo para cada nome de log de entrada. O parâmetro ThrottleLimit garante que todos os cinco blocos de script correm ao mesmo tempo.

Exemplo 13: Executar em paralelo como um trabalho

Este exemplo cria um trabalho que executa um bloco de scripts em paralelo, dois de cada vez.

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    …

O parâmetro ThrottleLimit limita o número de blocos de scripts paralelos a correr ao mesmo tempo. O parâmetro AsJob faz com que o ForEach-Object cmdlet retorne um objeto de trabalho em vez de transmitir a saída para o console. A $job variável recebe o objeto de trabalho que coleta dados de saída e monitora o estado de execução. A $job.ChildJobs propriedade contém os trabalhos filhos que executam os blocos de script paralelos.

Exemplo 14: Usando referências de variáveis seguras de thread

Este exemplo invoca blocos de script em paralelo para recolher objetos Process com nomes únicos.

$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

Uma única instância de um objeto ConcurrentDictionary é passada a cada bloco de script para recolher os objetos. Como o ConcurrentDictionary é thread safe, é seguro ser modificado por cada script paralelo. Um objeto não thread-safe, como System.Collections.Generic.Dictionary, não seria seguro para uso aqui.

Observação

Este exemplo é um uso ineficiente do parâmetro Parallel . O script adiciona o objeto de entrada a um objeto de dicionário simultâneo. É trivial e não vale a pena a sobrecarga de invocar cada script em um tópico separado. Funcionar ForEach-Object sem o interruptor paralelo é mais eficiente e rápido. Este exemplo destina-se apenas a demonstrar como usar variáveis thread safe.

Exemplo 15: Erros de escrita com execução paralela

Este exemplo grava no fluxo de erros em paralelo, onde a ordem dos erros escritos é aleatória.

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

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

Exemplo 16: Terminando erros na execução paralela

Este exemplo demonstra um erro de terminação em um scriptblock em execução paralela.

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 nunca foi escrito porque o scriptblock paralelo para essa iteração foi encerrado.

Observação

As variáveis de parâmetros comuns PipelineVariablenão são suportadas em ForEach-Object -Parallel cenários, mesmo com o modificador de Using: escopo.

Exemplo 17: Passando variáveis em blocos de script paralelos aninhados

Você pode criar uma variável fora de um ForEach-Object -Parallel scriptblock com escopo e usá-la dentro do scriptblock com o modificador de Using: escopo. A partir do PowerShell 7.2, você pode criar uma variável dentro de um ForEach-Object -Parallel scriptblock com escopo e usá-la dentro de um scriptblock aninhado.

$test1 = 'TestA'
1..2 | ForEach-Object -Parallel {
    $Using:test1
    $test2 = 'TestB'
    1..2 | ForEach-Object -Parallel {
        $Using:test2
    }
}

TestA
TestA
TestB
TestB
TestB
TestB

Observação

Em versões anteriores ao PowerShell 7.2, o scriptblock aninhado não pode acessar a $test2 variável e um erro é gerado.

Exemplo 18: Criando vários trabalhos que executam scripts em paralelo

O parâmetro ThrottleLimit limita o número de scripts paralelos em execução durante cada instância do ForEach-Object -Parallel. Ele não limita o número de trabalhos que podem ser criados ao usar o parâmetro AsJob . Como os próprios trabalhos são executados simultaneamente, é possível criar vários trabalhos paralelos, cada um rodando até o número limite de blocos de script simultâneos.

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

$jobs | Receive-Job -Wait

Este exemplo cria 10 trabalhos em execução. Cada trabalho não é executado mais do que 5 scripts simultaneamente. O número total de instâncias em execução simultânea é limitado a 50 (10 trabalhos vezes o ThrottleLimit de 5).

Parâmetros

-ArgumentList

Especifica uma matriz de argumentos para uma chamada de método. Para mais informações sobre o comportamento de ArgumentList, consulte about_Splatting.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Propriedades dos parâmetros

Tipo:

Object[]

Valor padrão:None
Suporta curingas:False
DontShow:False
Pseudónimos:Argumentos

Conjuntos de parâmetros

PropertyAndMethodSet
Posição:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-AsJob

Faz com que a invocação paralela seja executada como um trabalho do PowerShell. Um único objeto de trabalho é devolvido em vez da saída dos blocos de script em execução. O objeto de trabalho contém trabalhos filhos para cada bloco de script paralelo que é executado. Você pode usar o objeto de trabalho com qualquer um dos cmdlets de trabalho do PowerShell para ver o estado de execução e recuperar dados.

Esse parâmetro foi introduzido no PowerShell 7.0.

Propriedades dos parâmetros

Tipo:SwitchParameter
Valor padrão:None
Suporta curingas:False
DontShow:False

Conjuntos de parâmetros

ParallelParameterSet
Posição:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-Begin

Especifica um bloco de script que é executado antes deste cmdlet processar quaisquer objetos de entrada. Este bloco de scripts só é executado uma vez em todo o pipeline. Para obter mais informações sobre o begin bloco, consulte about_Functions.

Propriedades dos parâmetros

Tipo:ScriptBlock
Valor padrão:None
Suporta curingas:False
DontShow:False

Conjuntos de parâmetros

ScriptBlockSet
Posição:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-Confirm

Solicita confirmação antes de executar o cmdlet.

Propriedades dos parâmetros

Tipo:SwitchParameter
Valor padrão:False
Suporta curingas:False
DontShow:False
Pseudónimos:Cf.

Conjuntos de parâmetros

(All)
Posição:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-End

Especifica um bloco de script que se executa após este cmdlet processar todos os objetos de entrada. Este bloco de scripts só é executado uma vez em todo o pipeline. Para obter mais informações sobre o end bloco, consulte about_Functions.

Propriedades dos parâmetros

Tipo:ScriptBlock
Valor padrão:None
Suporta curingas:False
DontShow:False

Conjuntos de parâmetros

ScriptBlockSet
Posição:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-InputObject

Especifica os objetos de entrada. ForEach-Object executa o bloco de script ou a instrução de operação em cada objeto de entrada. Insira uma variável que contenha os objetos ou digite um comando ou expressão que obtenha os objetos.

Quando você usa o parâmetro InputObject com ForEach-Object, em vez de canalizar os resultados do comando para ForEach-Object, o valor InputObject é tratado como um único objeto. Isso é verdadeiro mesmo se o valor for uma coleção que é o resultado de um comando, como -InputObject (Get-Process). Como InputObject não pode retornar propriedades individuais de uma matriz ou coleção de objetos, recomendamos que, se você usar ForEach-Object para executar operações em uma coleção de objetos para esses objetos que têm valores específicos em propriedades definidas, use ForEach-Object no pipeline, conforme mostrado nos exemplos deste tópico.

Propriedades dos parâmetros

Tipo:PSObject
Valor padrão:None
Suporta curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Posição:Named
Obrigatório:False
Valor do pipeline:True
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-MemberName

Especifica o nome da propriedade member a ser obtida ou o método member a ser chamado. Os membros devem ser membros da instância, não membros estáticos.

Caracteres curinga são permitidos, mas funcionam somente se a cadeia de caracteres resultante for resolvida para um valor exclusivo. Por exemplo, se você executar Get-Process | foreach -MemberName *Nameo , o padrão curinga corresponderá a mais de um membro, fazendo com que o comando falhe.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Propriedades dos parâmetros

Tipo:String
Valor padrão:None
Suporta curingas:True
DontShow:False

Conjuntos de parâmetros

PropertyAndMethodSet
Posição:0
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-Parallel

Especifica o bloco de script a ser usado para processamento paralelo de objetos de entrada. Introduza um bloco de scripts que descreve a operação.

Esse parâmetro foi introduzido no PowerShell 7.0.

Propriedades dos parâmetros

Tipo:ScriptBlock
Valor padrão:None
Suporta curingas:False
DontShow:False

Conjuntos de parâmetros

ParallelParameterSet
Posição:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-Process

Especifica a operação executada em cada objeto de entrada. Este bloco de scripts é executado para todos os objetos do pipeline. Para obter mais informações sobre o process bloco, consulte about_Functions.

Quando fornece múltiplos blocos de script ao parâmetro de Processo , o primeiro bloco de script é sempre mapeado para o begin bloco. Se existirem apenas dois blocos de script, o segundo bloco é mapeado para o process bloco. Se houver três ou mais blocos de script, o primeiro bloco de script é sempre mapeado para o begin bloco, o último bloco é mapeado para o end bloco e os blocos do meio para o process bloco.

Propriedades dos parâmetros

Tipo:

ScriptBlock[]

Valor padrão:None
Suporta curingas:False
DontShow:False

Conjuntos de parâmetros

ScriptBlockSet
Posição:0
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-RemainingScripts

Especifica todos os blocos de script que não são ocupados pelo parâmetro do Processo .

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Propriedades dos parâmetros

Tipo:

ScriptBlock[]

Valor padrão:None
Suporta curingas:False
DontShow:False

Conjuntos de parâmetros

ScriptBlockSet
Posição:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-ThrottleLimit

Especifica o número de blocos de script que correm em paralelo. Os objetos de entrada são bloqueados até que a contagem de blocos de script em execução fique abaixo do Limite de Aceleração. O valor predefinido é 5.

O parâmetro ThrottleLimit limita o número de scripts paralelos em execução durante cada instância do ForEach-Object -Parallel. Ele não limita o número de trabalhos que podem ser criados ao usar o parâmetro AsJob . Como os próprios trabalhos são executados simultaneamente, é possível criar vários trabalhos paralelos, cada um correndo até o número limite de blocos de script simultâneos.

Esse parâmetro foi introduzido no PowerShell 7.0.

Propriedades dos parâmetros

Tipo:Int32
Valor padrão:5
Suporta curingas:False
DontShow:False

Conjuntos de parâmetros

ParallelParameterSet
Posição:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-TimeoutSeconds

Especifica o número de segundos a aguardar para que todas as entradas sejam processadas em paralelo. Após o tempo limite especificado, todos os scripts em execução são interrompidos. E todos os objetos de entrada restantes a serem processados são ignorados. O valor padrão de 0 desabilita o tempo limite e ForEach-Object -Parallel pode ser executado indefinidamente. Digitar Ctrl+C na linha de comando interrompe um comando em execução ForEach-Object -Parallel . Esse parâmetro não pode ser usado junto com o parâmetro AsJob .

Esse parâmetro foi introduzido no PowerShell 7.0.

Propriedades dos parâmetros

Tipo:Int32
Valor padrão:0
Suporta curingas:False
DontShow:False

Conjuntos de parâmetros

ParallelParameterSet
Posição:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-UseNewRunspace

Faz com que a invocação paralela crie um novo espaço de execução para cada iteração de loop em vez de reutilizar espaços de execução do pool de espaço de execução.

Este parâmetro foi introduzido no PowerShell 7.1

Propriedades dos parâmetros

Tipo:SwitchParameter
Valor padrão:False
Suporta curingas:False
DontShow:False

Conjuntos de parâmetros

ParallelParameterSet
Posição:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

Propriedades dos parâmetros

Tipo:SwitchParameter
Valor padrão:False
Suporta curingas:False
DontShow:False
Pseudónimos:Wi

Conjuntos de parâmetros

(All)
Posição:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome da propriedade:False
Valor dos argumentos restantes:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

PSObject

Você pode canalizar qualquer objeto para este cmdlet.

Saídas

PSObject

Este cmdlet retorna objetos que são determinados pela entrada.

Notas

O PowerShell inclui os seguintes aliases para ForEach-Object:

  • Todas as plataformas:
    • %
    • foreach

O ForEach-Object cmdlet funciona de forma muito semelhante à foreach instrução, exceto que você não pode canalizar a entrada para uma foreach instrução. Para obter mais informações sobre a foreach instrução, consulte about_Foreach.

A partir do PowerShell 4.0, Where e ForEach métodos foram adicionados para uso com coleções. Você pode ler mais sobre esses novos métodos aqui about_Arrays

Utilização de ForEach-Object -Parallel:

  • ForEach-Object -Parallel executa cada bloco de script num novo espaço de execução. Os novos espaços de execução criam significativamente mais sobrecarga do que a execução ForEach-Object com processamento sequencial. É importante usar o Paralelo , onde a sobrecarga de correr em paralelo é pequena comparada com o trabalho que o bloco de scripts faz. Por exemplo:

    • Scripts de computação intensiva em máquinas multi-core
    • Scripts que passam o tempo esperando por resultados ou fazendo operações de arquivo

    O uso do parâmetro Parallel pode fazer com que os scripts sejam executados muito mais lentamente do que o normal. Especialmente se os scripts paralelos forem triviais. Experimente o Parallel para descobrir onde ele pode ser benéfico.

  • Quando executados em paralelo, não é possível garantir que os objetos decorados com ScriptProperties ou ScriptMethods funcionem corretamente se forem executados em um espaço de execução diferente do que os scripts foram originalmente anexados a eles.

    A invocação Scriptblock sempre tenta ser executada em seu espaço de execução inicial , independentemente de onde ela é realmente invocada. No entanto, ForEach-Object -Parallel cria espaços de execução temporários que são excluídos após o uso, portanto, não há mais espaço de execução para os scripts serem executados.

    Esse comportamento pode funcionar enquanto o espaço de execução inicial ainda existir. No entanto, você pode não obter o resultado desejado se o script depender de variáveis externas que estão presentes apenas no espaço de execução do chamador e não no espaço de execução inicial .

  • Os erros de não terminação são gravados no fluxo de erros do cmdlet à medida que ocorrem em blocos de script em execução paralela. Como a ordem de execução paralela do scriptblock não é determinística, a ordem em que os erros aparecem no fluxo de erros é aleatória. Da mesma forma, as mensagens gravadas em outros fluxos de dados, como aviso, verbose ou informações, são gravadas nesses fluxos de dados em uma ordem indeterminada.

    Erros de encerramento, como exceções, encerram a instância paralela individual dos blocos de script nos quais eles ocorrem. Um erro de encerramento em um scriptblocks pode não causar o encerramento do ForEach-Object cmdlet. Os outros blocos de script, executados em paralelo, continuam a ser executados, a menos que também encontrem um erro de encerramento. O erro de terminação é gravado no fluxo de dados de erro como um ErrorRecord com um FullyQualifiedErrorId de PSTaskException. Os erros de encerramento podem ser convertidos em erros de não terminação usando o PowerShell try/catch ou trap blocos.

  • As variáveis de parâmetros comuns PipelineVariablenão são suportadas em cenários paralelos, mesmo com o modificador de Using: escopo.

    Importante

    O ForEach-Object -Parallel conjunto de parâmetros executa blocos de script em paralelo em threads de processo separados. O Using: modificador permite passar referências de variáveis do thread de invocação do cmdlet para cada thread de scriptblock em execução. Como os blocos de script correm em threads diferentes, as variáveis de objeto passadas por referência devem ser usadas em segurança. Geralmente, é seguro ler a partir de objetos referenciados que não mudam. Se você precisar modificar o estado do objeto, deverá usar objetos thread safe, como tipos .NET System.Collection.Concurrent (consulte o Exemplo 14).