ForEach-Object

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

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

O cmdlet ForEach-Object executa uma operação em cada item em 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 ForEach-Object comando.

• Sintaxe de bloco de script. Você pode usar um bloco de script para especificar a operação. Dentro do bloco de script, use a variável $_ para representar o objeto atual. O bloco de script é o valor do parâmetro Process . O bloco de script pode conter qualquer script do 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-Objectdá suporte a beginblocos e process , endconforme descrito em about_Functions.

  Observação

  Os blocos de script são executados no escopo 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, especifique um nome de propriedade ou método do objeto no pipeline. ForEach-Object retorna o valor da propriedade ou do 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.

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

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

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

Se o objeto não for um diretório, o bloco de script obterá o nome do arquivo, dividirá o valor de sua propriedade Length em 1024 e adicionará um espaço (" ") para separá-lo da próxima entrada. O cmdlet usa a propriedade PSIsContainer para determinar se um objeto é um diretório.

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 redireciona para o cmdlet ForEach-Object. 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 de mensagem de cada um dos eventos nesse arquivo. Por fim, o parâmetro End é usado para exibir a data e a hora após a conclusão de todo o processamento.

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

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

Você pode usar esse formato para alterar o formulário 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 entrar. 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 HKCU:\Network com o valor do registro RemotePath definido como \\Server\Share.

O comando usa o Get-ItemProperty cmdlet para obter todas as subchaves da chave de rede e do 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. Essa é 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 cmdlet ForEach-Object é necessário para acessar a propriedade.

Este exemplo mostra o efeito de canalizar a variável $null automática para o cmdlet ForEach-Object.

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

Hello
Hello
Hello
Hello

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

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 alias Foreach do ForEach-Object cmdlet e omite o nome do parâmetro MemberName , que é opcional.

O ForEach-Object cmdlet é útil para obter valores de propriedade, pois 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.

Este exemplo mostra três maneiras de dividir dois nomes de módulo separados por pontos em seus nomes de componente. Os comandos chamam o método Split de cadeias de caracteres. 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 usa a sintaxe tradicional, que inclui um bloco de script e o operador de objeto atual $_. Ele usa a sintaxe de ponto para especificar o método e parênteses para colocar 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 alias foreach do ForEach-Object cmdlet e omite os nomes dos parâmetros MemberName e ArgumentList , que são opcionais.

Neste exemplo, passamos dois blocos de script posicionalmente. Todos os blocos de script são associados 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

Neste exemplo, passamos quatro blocos de script posicionalmente. Todos os blocos de script são associados 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

Conforme mostrado no exemplo anterior, vários 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

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.

Você pode redirecionar qualquer objeto para este cmdlet.

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

O Windows PowerShell inclui os seguintes aliases para ForEach-Object:

• %
• foreach

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

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