ForEach-Object

 

Additional Resources for ForEach-Object

 

Looping Through a Collection of Objects

http://www.microsoft.com/technet/scriptcenter/topics/msh/cmdlets/foreach-object.mspx

 

 

SYNOPSIS

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

 

SYNTAX

ForEach-Object [-process] <ScriptBlock[]> [-inputObject <psobject>] [-begin <scriptblock>] [-end <scriptblock>] [<CommonParameters>]

 

DETAILED DESCRIPTION

Performs an operation against 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 which 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 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, included the ones specified with Begin and End, are passed down the pipeline.

 

PARAMETERS

 

-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

 

-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

 

-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

 

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".

 

INPUT TYPE

Object

 

NOTES

 

For more information, type "Get-Help ForEach-Object -detailed". For technical information, type "Get-Help ForEach-Object -full".

 

When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".

 

EXAMPLE 1

 

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

 

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

 

This command retrieves the files and directories in the root of the C: drive and returns and displays the size of each of them. The zeroes represent directories where no file size was available.

 

EXAMPLE 3

 

$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}

 

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

 

get-itemproperty -path hkcu:\Network\* |

 foreach-object {set-itemproperty -path $_.pspath -name RemotePath

-value $_.RemotePath.ToUpper();}

 

This command updates a set of registry entries by using the Set-ItemPropertycmdlet. The registry entries specify the UNC path of mapped network drives on the computer. This command changes the characters in the UNC path to uppercase. In a real scenario, you might need to change the server name or another component of the path.

 

Because the Set-ItemProperty cmdlet acts on a single property, the ForEach-Object cmdlet is used to call Set-ItemProperty for each property (registry entries in this case) being changed. The name of the registry entries is RemotePath and they are located in HKCU\Network\<mapped drive letter>. The entries are retrieved by using the Get-ItemProperty cmdlet and piped as input to ForEach-Object. In the call to Set-ItemProperty within ForEach-Object, the $_ variable holds a reference to the current registry entry being processed. The value of the PSPath property is the registry key containing the current entry. The RemotePath property is of type System.String, which includes the ToUpper method used to change the value of the entry to uppercase.

 

RELATED LINKS

Where-Object

Compare-Object

Group-Object

Select-Object

Sort-Object