powershellscripts.com

Tutorials  PowerShell Cmdlet Help for ForEach-Object



NAME
ForEach-Object

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

SYNTAX
ForEach-Object [-Process] [-Begin ] [-End ] [-InputObject ] [ ommonParameters>]


DESCRIPTION
The ForEach-Object cmdlet performs an operation on each of a set of input objects. The input objects can be piped t
o 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 Proc
ess 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 in
put object is processed. The other, specified as the value of the End parameter, runs after the last input object i
s 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
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
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
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
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


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

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.


NOTES





-------------------------- 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 $_.m
essage} -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, t
he Process parameter uses the Out-File cmdlet to create a text file named events.txt and stores the message propert
y 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 -v
alue $_.RemotePath.ToUpper();}


Description
-----------
This command changes the value of the RemotePath registry entry in all of the subkeys under the HKCU:\Network key t
o 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 b
e an E subkey of HKCU:\Network and the value of the RemotePath registry entry in the E subkey will be \\Server\Shar
e.

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 Remote
Path 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.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113300