ForEach-Object
Executa uma operação em relação a cada item em uma coleção de objetos de entrada.
Sintaxe
ScriptBlockSet (Predefiniçã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>]
Description
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 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-Objectsuporta osbeginblocos ,processeendconforme 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, você especifica uma propriedade ou nome de método do objeto no pipeline.
ForEach-ObjectRetorna 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 ProcessNameA sintaxe simplificada foi introduzida no Windows PowerShell 3.0. Para obter mais informações, consulte about_Simplified_Syntax.
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 obtém o nome do arquivo, divide o valor de sua propriedade Length por 1024 e adiciona 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.
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 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 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: Usando ForEach-Object com dois blocos de script
Neste exemplo, passamos dois blocos de script posicionalmente. Todos os blocos de script se 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: Usando ForEach-Object com mais de dois blocos de script
Neste exemplo, passamos quatro blocos de script posicionalmente. Todos os blocos de script se 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: Executar vários blocos de script para cada item de pipeline
Como 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 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[] |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | Argumentos |
Conjuntos de parâmetros
PropertyAndMethodSet
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Begin
Especifica um bloco de script que é executado antes que este cmdlet processe quaisquer objetos de entrada. Este bloco de script só é executado uma vez para todo o pipeline. Para obter mais informações sobre o begin bloco, consulte about_Functions.
Propriedades dos parâmetros
| Tipo: | ScriptBlock |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
ScriptBlockSet
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Confirm
Solicita confirmação antes de executar o cmdlet.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | Cf. |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-End
Especifica um bloco de script que é executado depois que esse cmdlet processa todos os objetos de entrada. Este bloco de script só é executado uma vez para todo o pipeline. Para obter mais informações sobre o end bloco, consulte about_Functions.
Propriedades dos parâmetros
| Tipo: | ScriptBlock |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
ScriptBlockSet
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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 |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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 |
| Default value: | None |
| Suporta carateres universais: | True |
| NãoMostrar: | False |
Conjuntos de parâmetros
PropertyAndMethodSet
| Position: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Process
Especifica a operação executada em cada objeto de entrada. Este 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 mapeado para o begin bloco, o último bloco é mapeado para o end bloco e os blocos do meio são mapeados para o process bloco.
Propriedades dos parâmetros
| Tipo: | |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
ScriptBlockSet
| Position: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-RemainingScripts
Especifica todos os blocos de script que não são usados pelo parâmetro Process .
Esse parâmetro foi introduzido no Windows PowerShell 3.0.
Propriedades dos parâmetros
| Tipo: | |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
ScriptBlockSet
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-WhatIf
Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | Wi |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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 Windows PowerShell inclui os seguintes aliases para ForEach-Object:
%foreach
O cmdlet ForEach-Object funciona de forma muito semelhante à instrução foreach, exceto que você não pode canalizar 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, Where e ForEach métodos foram adicionados para uso com coleções. Você pode ler mais sobre esses novos métodos aqui about_Arrays
