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

none

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

none

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

none

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

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. 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}

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 }

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}

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();}

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.



Table Of Contents