ForEach-Object

Referência

Módulo:: Microsoft.PowerShell.Core

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

Syntax

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

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-Object dá suporte aos beginblocos , processe end conforme 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.
Instrução de operação. Você também pode escrever uma instrução de operação, que é muito mais semelhante à linguagem natural. Você pode usar a instrução de operação para especificar um valor de propriedade ou chamar um método. 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 $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 obterá o nome do arquivo, dividirá o valor de sua propriedade Length por 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 1.000 eventos mais recentes do log de eventos do sistema e os armazena na $Events variável . $Events em seguida, é canalizado para o ForEach-Object cmdlet. O parâmetro Begin exibe a data e 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 hora após todo o processamento ter sido concluído.

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 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 a forma ou o conteúdo de um valor de entrada de registro.

Cada subchave da chave Network representa uma unidade de rede mapeada que será reconectada ao efetuar logon. A entrada RemotePath contém o caminho UNC da unidade conectada. Por exemplo, se você mapear a unidade E: para \\Server\Share, haverá uma subchave E de HKCU:\Network e o valor da entrada do Registro RemotePath na subchave E será \\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 ForEach-Object cmdlet é necessário para acessar a propriedade.

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

Este exemplo mostra o efeito de canalizar a $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 nulo como um espaço reservado explícito, o ForEach-Object cmdlet gera um valor para $Null, assim como faz para 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 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 é muito ú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.

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

Esses exemplos mostram 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 de cadeias de caracteres Split. Os três comandos usam uma 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 incluir 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 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.

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

Observação

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

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.

Este parâmetro foi introduzido no Windows PowerShell 3.0.

Type:	Object[]
Aliases:	Args
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Begin

Especifica um bloco de script que é 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 begin bloco, consulte about_Functions.

Type:	ScriptBlock
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Confirm

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

Type:	SwitchParameter
Aliases:	cf
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 end bloco, consulte about_Functions.

Type:	ScriptBlock
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 contém os objetos ou digite um comando ou uma expressão que obtém 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 os objetos que têm valores específicos em propriedades definidas, use ForEach-Object no pipeline, conforme mostrado nos exemplos neste tópico.

Type:	PSObject
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-MemberName

Especifica a propriedade a ser obtida 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á.

Este parâmetro foi introduzido no Windows PowerShell 3.0.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	True

-Process

Especifica a operação que é executada em cada objeto de entrada. Esse bloco de script é executado para cada objeto no pipeline. Para obter mais informações sobre o process bloco, 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 begin bloco. Se houver apenas dois blocos de script, o segundo bloco será mapeado para o process bloco. Se houver três ou mais blocos de script, o primeiro bloco de script sempre será mapeado para o begin bloco, o último bloco será mapeado para o end bloco e os blocos entre eles serão mapeados para o process bloco.

Type:	ScriptBlock[]
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-RemainingScripts

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

Este parâmetro foi introduzido no Windows PowerShell 3.0.

Type:	ScriptBlock[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-WhatIf

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

Type:	SwitchParameter
Aliases:	wi
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Entradas

PSObject

Você pode redirecionar qualquer objeto para este cmdlet.

Saídas

PSObject

Esse cmdlet retorna objetos determinados pela entrada.

Observações

O ForEach-Object cmdlet funciona muito parecido com a instrução Foreach , exceto que você não pode redirecionar 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, Where os métodos 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

Syntax

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

Syntax

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