ForEach-Object

Referência

Módulo:: Microsoft.PowerShell.Core

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

Sintaxe

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

Description

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 comando ForEach-Object.

do bloco 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-Object dá suporte aos blocos begin, processe end, conforme descrito em about_functions.

Nota

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.
instrução Operation. Você também pode escrever uma instrução de operação, que é muito mais parecida com a linguagem natural. Você pode usar a instrução de operação para especificar um valor de propriedade ou chamar um método. As instruções de operação foram introduzidas no Windows PowerShell 3.0.

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

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

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.

$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 obtém os 1000 eventos mais recentes do log de eventos do sistema e os armazena na variável $Events. $Events é canalizado para o cmdlet ForEach-Object. O parâmetro Begin exibe a data e a hora atuais. Em seguida, o parâmetro Process usa o cmdlet Out-File 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.

Exemplo 4: alterar o valor de uma chave do Registro

Este exemplo altera o valor da entrada do registro RemotePath em todas as subchaves na chave HKCU:\Network para texto em letras 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 o formulário ou o conteúdo de um valor de entrada do Registro.

Cada subchave na chave Network representa uma unidade de rede mapeada que se reconectará no logon. A entrada RemotePath contém o caminho UNC da unidade conectada. Por exemplo, se você mapear a unidade E: para , haverá uma subchave E de e o valor da entrada do registro RemotePath na subchave E é .

O comando usa o cmdlet para obter todas as subchaves da chave de de Rede e o cmdlet para alterar o valor da entrada do registro RemotePath em cada chave. No comando Set-ItemProperty, 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.

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

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 nulo como um espaço reservado explícito, o cmdlet ForEach-Object gera um valor para $Null, assim como acontece com outros objetos que você redireciona para ele.

Exemplo 6: Obter valores de propriedade

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

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

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

O cmdlet é muito útil para obter valores de propriedade, pois obtém o valor sem alterar o tipo, diferentemente dos cmdlets formatar ou o cmdlet , que altera o tipo de valor da propriedade.

Exemplo 7: Dividir nomes de módulo em nomes de componente

Este exemplo mostra três maneiras de dividir dois nomes de módulo separados por pontos em seus nomes de componente.

"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

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.

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 ArgumentName para identificar o ponto (".") como o delimitador dividido.

O terceiro comando usa o alias foreach do cmdlet e omite os nomes dos parâmetros De Nome de Membro e ArgumentList, que são opcionais.

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

Neste exemplo, passamos dois blocos de script posicionalmente. Todos os blocos de script são associados ao parâmetro processo . 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: Usando ForEach-Object com mais de dois blocos de script

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

begin
process A
process B
process A
process B
end

Nota

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

Exemplo 10: Executar vários blocos de script para cada item de pipeline

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

Parâmetros

-ArgumentList

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

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:	Object[]
Aliases:	Args
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Begin

Especifica um bloco de script executado antes que esse cmdlet processe objetos de entrada. Esse bloco de script só é executado uma vez para todo o pipeline. Para obter mais informações sobre o bloco begin, consulte about_Functions.

Tipo:	ScriptBlock
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Confirm

Solicita a confirmação antes de executar o cmdlet.

Tipo:	SwitchParameter
Aliases:	cf
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-End

Especifica um bloco de script executado após esse cmdlet processar todos os objetos de entrada. Esse bloco de script só é executado uma vez para todo o pipeline. Para obter mais informações sobre o bloco end, consulte about_Functions.

Tipo:	ScriptBlock
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-InputObject

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

Quando você usa o parâmetro InputObject com , em vez de canalizar resultados de comando para , 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 aqueles objetos que têm valores específicos em propriedades definidas, use ForEach-Object no pipeline, conforme mostrado nos exemplos deste tópico.

Tipo:	PSObject
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	True
Aceitar caracteres curinga:	False

-MemberName

Especifica a propriedade a ser acessada ou o método a ser chamado.

Caracteres curinga são permitidos, mas funcionam somente se a cadeia de caracteres resultante for resolvida para um valor exclusivo. Se, por exemplo, você executar Get-Process | ForEach -MemberName *Namee mais de um membro existir com um nome que contenha o Nome da cadeia de caracteres, como as propriedades ProcessName e Name, o comando falhará.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:	String
Cargo:	0
Valor padrão:	None
Obrigatório:	True
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	True

-Process

Especifica a operação executada em cada objeto de entrada. Esse bloco de script é executado para cada objeto no pipeline. Para obter mais informações sobre o bloco process, consulte about_Functions.

Quando você fornece vários blocos de script para o parâmetro Process, o primeiro bloco de script sempre é mapeado para o bloco begin. Se houver apenas dois blocos de script, o segundo bloco será mapeado para o bloco process. Se houver três ou mais blocos de script, o primeiro bloco de script sempre será mapeado para o bloco begin, o último bloco será mapeado para o bloco end e os blocos no meio serão mapeados para o bloco process.

Tipo:	ScriptBlock[]
Cargo:	0
Valor padrão:	None
Obrigatório:	True
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-RemainingScripts

Especifica todos os blocos de script que não são obtidos pelo parâmetro processo .

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:	ScriptBlock[]
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-WhatIf

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

Tipo:	SwitchParameter
Aliases:	wi
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

Entradas

PSObject

Você pode redirecionar qualquer objeto para este cmdlet.

Saídas

PSObject

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

Observações

O cmdlet funciona muito parecido com a instrução foreach , exceto que você não pode canalizar a entrada para uma instrução foreach . Para obter mais informações sobre a instrução Foreach, 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

Compartilhar via

ForEach-Object

Sintaxe

Description

Exemplos

Exemplo 1: dividir inteiros em uma matriz

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

Exemplo 3: Operar nos eventos mais recentes do Sistema

Exemplo 4: alterar o valor de uma chave do Registro

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

Exemplo 6: Obter valores de propriedade

Exemplo 7: Dividir nomes de módulo em nomes de componente

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

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

Exemplo 10: Executar vários blocos de script para cada item de pipeline

Parâmetros

-ArgumentList

-Begin

-Confirm

-End

-InputObject

-MemberName

-Process

-RemainingScripts

-WhatIf

Entradas

Saídas

Observações

Recursos adicionais

Compartilhar via

ForEach-Object

Sintaxe

Description

Exemplos

Exemplo 1: dividir inteiros em uma matriz

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

Exemplo 3: Operar nos eventos mais recentes do Sistema

Exemplo 4: alterar o valor de uma chave do Registro

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

Exemplo 6: Obter valores de propriedade

Exemplo 7: Dividir nomes de módulo em nomes de componente

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

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

Exemplo 10: Executar vários blocos de script para cada item de pipeline

Parâmetros

-ArgumentList

-Begin

-Confirm

-End

-InputObject

-MemberName

-Process

-RemainingScripts

-WhatIf

Entradas

Saídas

Observações

Links Relacionados

Recursos adicionais