Edit

Share via

about_Foreach

  • Article

Short description

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

Long description

The foreach statement is a language construct for iterating over a set of values in a collection.

The simplest and most typical type of collection to traverse is an array. Within a foreach loop, it's 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 part of the foreach statement inside parenthesis represents a variable and a collection to iterate. PowerShell creates the variable $<item> automatically when the foreach loop runs. At the start of each iteration, foreach sets the item variable to the next value in the collection. The {<statement list>} block contains the commands to execute for each iteration.

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 contains 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 Write-Host to display the value. The next time through the loop, $letter is set to b. The pattern repeats for each item in the array.

You can also use foreach statements with cmdlets that return a collection of items. In the following example, the foreach statement steps through the list of items returned by the Get-ChildItem cmdlet.

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

You can refine the example using an if statement to limit the results that are returned. In the following example, the if statement limits the results to files that are greater than 100 kilobytes (KB):

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

In this example, the foreach loop uses a property of the $file variable to perform a comparison operation ($file.length -gt 100KB). The $file variable has all the properties of the object returned by the Get-ChildItem.

In the next example, the script displays the length and the last access time inside the statement list:

foreach ($file in Get-ChildItem)
{
  if ($file.Length -gt 100KB)
  {
    Write-Host $file
    Write-Host $file.Length
    Write-Host $file.LastAccessTime
  }
}

You can also use variables from outside a foreach loop. The following example counts files over 100 KB in size:

$i = 0
foreach ($file in Get-ChildItem) {
  if ($file.length -gt 100KB) {
    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 100KB in the current directory.'
}
else {
  Write-Host 'No files greater than 100KB in the current directory.'
}

In the preceding example, $i starts with a value of 0 outside the loop. Then, $i is incremented inside the loop for each file that's larger than 100KB. When the loop exits, an if statement evaluates the value of $i to display a count of files over 100KB.

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 following function parses PowerShell scripts and script modules and returns the location of functions contained within. The example demonstrates how to use the MoveNext method and the Current property of the $foreach variable inside of a foreach script block.

For more information, see Using Enumerators.

function Get-FunctionPosition {
  [CmdletBinding()]
  [OutputType('FunctionPosition')]
  param(
    [Parameter(Position = 0, Mandatory,
      ValueFromPipeline, ValueFromPipelineByPropertyName)]
    [ValidateNotNullOrEmpty()]
    [Alias('PSPath')]
    [System.String[]]
    $Path
  )

  process {
    try {
      $filesToProcess = if ($_ -is [System.IO.FileSystemInfo]) {
        $_
      } else {
        Get-Item -Path $Path
      }
      $parser = [System.Management.Automation.Language.Parser]
      foreach ($item in $filesToProcess) {
        if ($item.PSIsContainer -or
            $item.Extension -notin @('.ps1', '.psm1')) {
          continue
        }
        $tokens = $errors = $null
        $ast = $parser::ParseFile($item.FullName, ([ref]$tokens),
          ([ref]$errors))
        if ($errors) {
          $msg = "File '{0}' has {1} parser errors." -f $item.FullName,
            $errors.Count
          Write-Warning $msg
        }
        :tokenLoop foreach ($token in $tokens) {
          if ($token.Kind -ne 'Function') {
            continue
          }
          $position = $token.Extent.StartLineNumber
          do {
            if (-not $foreach.MoveNext()) {
              break tokenLoop
            }
            $token = $foreach.Current
          } until ($token.Kind -in @('Generic', 'Identifier'))
          $functionPosition = [pscustomobject]@{
            Name       = $token.Text
            LineNumber = $position
            Path       = $item.FullName
          }
          $addMemberSplat = @{
              InputObject = $functionPosition
              TypeName = 'FunctionPosition'
              PassThru = $true
          }
          Add-Member @addMemberSplat
        }
      }
    }
    catch {
      throw
    }
  }
}

See also