[an error occurred while processing this directive]

TOPIC
	about_Foreach

SHORT DESCRIPTION
	Describes a language command you can use to traverse all the items in a 
	collection of items.


LONG DESCRIPTION
	The Foreach statement (also known as a Foreach loop) is a language 
	construct for stepping through (iterating) a series of values in a 
	collection of items. 


	The simplest and most typical type of collection to traverse is an array.
	Within a Foreach loop, it is common to run one or more commands against
	each item in an array. 


  Syntax	
	The following shows the Foreach syntax:

	
		foreach ($<item> in $<collection>){<statement list>}


  The Foreach Statement Outside a Command Pipeline
	The part of the Foreach statement enclosed in parenthesis represents a
	variable and a collection to iterate. Windows PowerShell creates the 
	variable ($<item>) automatically when the Foreach loop runs. Prior to 
	each iteration through the loop, the variable is set to a value in the 
	collection. The block following a Foreach statement {<statement list>}
	contains a set of commands to execute against each item in a collection.
 

  Examples
	For example, the Foreach loop in the following example displays the 
	values in the $letterArray array.

	
		$letterArray = "a","b","c","d"
		foreach ($letter in $letterArray)
		{
			Write-Host $letter
	}


	In this example, the $letterArray array is created and initialized with 
	the string values "a", "b", "c", and "d". The first time the Foreach 
	statement runs, it sets the $letter variable equal to the first item in 
	$letterArray ("a"). Then, it uses the Write-Host cmdlet to display the 
	letter a. The next time through the loop, $letter is set to "b", and so 
	on. After the Foreach loop displays the letter d, Windows PowerShell 
	exits the loop.


	The entire Foreach statement must appear on a single line to run it as a
	command at the Windows PowerShell command prompt. The entire Foreach 
	statement does not have to appear on a single line if you place the 
	command in a .ps1 script file instead. 


	Foreach statements can also be used together with cmdlets that 
	return a collection of items. In the following example, the Foreach 
	statement steps through the list of items that is returned by the 
	Get-ChildItem cmdlet.


		foreach ($file in Get-ChildItem)
		{
			Write-Host $file
	}


	You can refine the example by using an If statement to limit the results 
	that are returned. In the following example, the Foreach statement 
	performs the same looping operation as the previous example, but it adds
	an If statement to limit the results to files that are greater than 100 
	kilobytes (KB):


		foreach ($file in Get-ChildItem)
		{
			if ($file.length -gt 100k) 
			{
				Write-Host $file
		}
	}


	In this example, the Foreach loop uses a property of the $file variable
	to perform a comparison operation ($file.length -gt 100k). The $file 
	variable contains all the properties in the object that is returned by 
	the Get-ChildItem cmdlet. Therefore, you can return more than just a 
	file name. In the next example, Windows PowerShell returns the length and
	the last access time inside the statement list:


		foreach ($file in Get-ChildItem)
		{
			if ($file.length -gt 100k) 
			{
				Write-Host $file
				Write-Host $file.length
				Write-Host $file.lastaccesstime
		}
	}


	In this example, you are not limited to running a single command in a 
	statement list. 


	You can also use a variable outside a Foreach loop and increment the 
	variable inside the loop. The following example counts files over 100 KB
	in size: 

  
		$i = 0
		foreach ($file in Get-ChildItem)
		{
			if ($file.length -gt 100k) 
			{
				Write-Host $file "file size:" ($file.length / 
		1024).ToString("F0") KB
				$i = $i + 1
		}
	}

		if ($i -ne 0)
		{
			Write-Host
			Write-Host $i " file(s) over 100 KB in the current 
		directory."}
		else 
		{
			Write-Host "No files greater than 100 KB in the current 
		directory."
	}


	In the preceding example, the $i variable is set to 0 outside the loop,
	and the variable is incremented inside the loop for each file that is
	found that is larger than 100 KB. When the loop exits, an If statement
	evaluates the value of $i to display a count of all the files over 
	100 KB. Or, it displays a message stating that no files over 100 KB were
	found.


	The previous example also demonstrates how to format the file length 
	results:


		($file.length / 1024).ToString("F0")


	The value is divided by 1,024 to show the results in kilobytes rather 
	than bytes, and the resulting value is then formatted using the 
	fixed-point format specifier to remove any decimal values from the 
	result. The 0 makes the format specifier show no decimal places. 


  The Foreach Statement Inside a Command Pipeline
	When Foreach appears in a command pipeline, Windows PowerShell uses the
	foreach alias, which calls the ForEach-Object command. When you use 
	the foreach alias in a command pipeline, you do not include 
	the ($<item> in $<collection>) syntax as you do with the Foreach 
	statement. This is because the prior command in the pipeline provides 
	this information. The syntax of the foreach alias when used in a command
	pipeline is as follows:
	

		<command> | foreach {<command_block>}
	 

	For example, the Foreach loop in the following command pipeline displays 
	any processes whose working set (memory usage) is greater 
	than 20 megabytes (MB). Windows PowerShell pipes the output from the
	Get-Process command to the foreach alias. Inside the foreach alias 
	command block, the $_.WS variable contains the value of the WS (working
	set) property passed to it by the Get-Process cmdlet. (The $_ portion
	of the declaration is a Windows Script Host [WSH] automatic variable,
	and the WS portion is a property). The If statement uses a conditional
	statement to determine whether the working set is greater than 20 MB 
	(20,000,000 bytes). If so, the name of the process that is stored in 
	the $_.name variable and the working-set size in megabytes are displayed.
	If no process working set is over 20 MB, nothing is displayed.


		Write-Host "Processes with working-sets greater than 20 MB"
		Get-Process | foreach { 
			if ($_.WS -gt 20m)
			{
				Write-Host $_.name ": " 
		($_.WS/1m).ToString("F0") MB -Separator ""
		}
	}


	The foreach alias also supports beginning command blocks, middle command
	blocks, and end command blocks. The beginning and end command blocks run
	once, and the middle command block runs every time the Foreach loop steps
	through a collection or array. 
	

	The syntax of the foreach alias when used in a command pipeline with a 
	beginning, middle, and ending set of command blocks is as follows:
	

		<command> | foreach {<beginning command_block>}{<middle 
		command_block>}{<ending command_block>}

 
	The following example demonstrates the use of the beginning, middle, and
	end command blocks. 


		Get-ChildItem | foreach {
		$fileCount = $directoryCount = 0}{
		if ($_.PsIsContainer) {$directoryCount++} else {$fileCount++}}{
		"$directoryCount directories and $fileCount files"}


	The beginning block creates and initializes two variables to 0:


		{$fileCount = $directoryCount = 0}
 

	The middle block evaluates whether each item returned by Get-ChildItem
	is a directory or a file:


		{if ($_.PsIsContainer) {$directoryCount++} else {$fileCount++}}


	If the item that is returned is a directory, the $directoryCount 
	variable is incremented by 1. If the item is not a directory, 
	the $fileCount variable is incremented by 1. The ending block runs after
	the middle block completes its looping operation and then returns the 
	results of the operation: 

	 
		{"$directoryCount directories and $fileCount files"}


	By using the beginning, middle, and ending command block structure and 
	the pipeline operator, you can rewrite the earlier example to find any 
	files that are greater than 100 KB, as follows:


		Get-ChildItem | foreach{
			$i = 0}{
			if ($_.length -gt 100k)
			{
				Write-Host $_.name "file size:" ($_.length / 
		1024).ToString("F0") KB
				$i++
		}
		}{
			if ($i -ne 0)
			{
				Write-Host
				Write-Host "$i file(s) over 100 KB in the current 
		directory."
		}
			else 
			{
			Write-Host "No files greater than 100 KB in the current 
		directory."}
		}


SEE ALSO
	about_Automatic_Variables
	about_If
	Foreach-Object




[an error occurred while processing this directive]