ForEach-Object

Perform an operation (execute a block of statements) against each item in a collection of input objects, typically passed through the pipeline.

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

key
   -process ScriptBlock[]
       A block of PowerShell script that is applied to each incoming object.
        
   -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.
        
   -begin scriptblock
       A script block to run before processing any input objects.
        
   -end scriptblock
       A script block to run after processing all input objects.
 
   CommonParameters:
       -Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
       -OutBuffer -OutVariable.

Standard Aliases for Foreach-Object: the '%' symbol, ForEach

For operations in the pipeline, the ForEach alias will take precedence over the ForEach statement.
For operations not in the pipeline the ForEach statement will take precedence.

For the fastest performance:
Use the ForEach statement when the collection of objects is small enough that it can be loaded into memory. (eg an array of 20 string values)
Use the ForEach-Object cmdlet when you want to pass only one object at a time through the pipeline, minimising memory usage. (e.g. a directory containing 10,000 files)

Examples

Retrieve the files (and folders) from the C: drive and display the size of each:

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

(The $_ variable holds a reference to the current item being processed.)

Retrieve the 1000 most recent events from the system event log and store them in the $events variable:

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

Then pipe the $events variable into the ForEach-Object cmdlet.

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

In this example, the -Process parameter uses Out-File to create a text file and stores the .message property of each event. The -Begin and -End parameters are used to display the date and time before and after the command has completed.
In this example, the backtick character ` is the PowerShell line continuation character.

“The best way to have a good idea is to have a lot of ideas” ~ Linus Pauling

Related:

ForEach statement
Compare-Object Compare the properties of objects
Group-Object - Group the objects that contain the same value for a common property
Measure-Object - Measure aspects of object properties and create objects from those values
New-Object - Create a new .Net object
Select-Object - Select objects based on parameters set in the Cmdlet command string
Sort-Object - Sort the input objects by property value
Tee-Object - Send input objects to two places
Where-Object - Filter input from the pipeline allowing operation on only certain objects


© Copyright SS64.com 1999-2013
Some rights reserved