ForEach-Object

Applies To: Windows PowerShell 2.0

Performs an operation against each of a set of input objects.

Syntax

ForEach-Object [-Process] <ScriptBlock[]> [-Begin <scriptblock>] [-End <scriptblock>] [-InputObject <psobject>] [<CommonParameters>]

Description

The ForEach-Object cmdlet performs an operation on each of a set of input objects. The input objects can be piped to the cmdlet or specified by using the InputObject parameter.

The operation to perform is described within a script block that is provided to the cmdlet as the value of the Process parameter. The script block can contain any Windows PowerShell script.

Within the script block, the current input object is represented by the $_ variable.

In addition to using the script block that describes the operations to be carried out on each input object, you can provide two additional script blocks. One, specified as the value of the Begin parameter, runs before the first input object is processed. The other, specified as the value of the End parameter, runs after the last input object is processed.

The results of the evaluation of all the script blocks, including the ones specified with Begin and End, are passed down the pipeline.

Parameters

-Begin <scriptblock>

Specifies a script block to run before processing any input objects.

Required?	false
Position?	named
Default Value
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-End <scriptblock>

Specifies a script block to run after processing all input objects.

Required?	false
Position?	named
Default Value
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-InputObject <psobject>

Accepts an object that the script block specified in the process parameter will act upon. Enter a variable that contains the objects, or type a command or expression that gets the objects.

Required?	false
Position?	named
Default Value
Accept Pipeline Input?	true (ByValue)
Accept Wildcard Characters?	false

-Process <ScriptBlock[]>

Specifies the script block that is applied to each incoming object.

Required?	true
Position?	1
Default Value
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

<CommonParameters>

This command supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, and WarningVariable. For more information, see about_CommonParameters.

Inputs and Outputs

The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns.

Inputs	System.Management.Automation.PSObject You can pipe any object to ForEach-Object.
Outputs	System.Management.Automation.PSObject The objects that ForEach-Object returns are determined by the input.

Example 1

C:\PS>30000,56798,12432 | foreach-object -process {$_/1024}

Description
-----------
This command accepts an array of integers, divides each one of them by 1024, and displays the results.

Example 2

C:\PS>get-childitem C:\ | foreach-object -process { $_.length / 1024 }

Description
-----------
This command retrieves the files and directories in the root of the C: drive, and it returns and displays the size of each of them. The zeros represent directories in which no file size was available.

Example 3

C:\PS>$events = get-eventlog -logname system -newest 1000

C:\PS> $events | foreach-object -begin {get-date} -process {out-file -filepath events.txt -append -inputobject $_.message} -end {get-date}

Description
-----------
This command retrieves the 1000 most recent events from the system log and stores them in the $events variable. It then pipes the events to the ForEach-Object cmdlet. The Begin parameter displays the current date and time. Next, the Process parameter uses the Out-File cmdlet to create a text file named events.txt and stores the message property of each of the events in that file. Last, the End parameter is used to display the date and time after all of the processing has completed.

Example 4

C:\PS>get-itemproperty -path hkcu:\Network\* | foreach-object {set-itemproperty -path $_.pspath -name RemotePath -value $_.RemotePath.ToUpper();}

Description
-----------
This command changes the value of the RemotePath registry entry in all of the subkeys under the HKCU:\Network key to uppercase text. You can use this format to change the form or content of a registry entry value.

Each subkey in the Network key represents a mapped network drive that will reconnect at logon. The RemotePath entry contains the UNC path of the connected drive. For example, if you map the E: drive to \\Server\Share, there will be an E subkey of HKCU:\Network and the value of the RemotePath registry entry in the E subkey will be \\Server\Share.

The command uses the Get-ItemProperty cmdlet to get all of the subkeys of the Network key and the Set-ItemProperty cmdlet to change the value of the RemotePath registry entry in each key. In the Set-ItemProperty command, the path is the value of the PSPath property of the registry key. (This is a property of the Microsoft .NET Framework object that represents the registry key; it is not a registry entry.) The command uses the ToUpper() method of the RemotePath value, which is a string (REG_SZ).

Because Set-ItemProperty is changing the property of each key, the ForEach-Object cmdlet is required to access the property.

Example 5

C:\PS>1, 2, $null, 4 | foreach-object {"Hello"}

Hello
Hello
Hello
Hello

Description
-----------
This example shows the effect of piping the $null automatic variable to the ForEach-Object cmdlet. 

Because Windows PowerShell treats null as an explicit placeholder, the ForEach-Object cmdlet generates a value for $null, just as it does for other objects that you pipe to it.

For more information about the $null automatic variable, see about_Automatic_Variables.