.Where (method)

Filter input from a collection (or a set of properties), returning all or some of the matching items.

Syntax
      collection.Where({ expression } [, mode [, numberToReturn]])

Key
   collection      A collection of objects e.g. filenames, registry keys, servernames.

   expression      A block of script to filter the object properties.

   mode            One of the following:

                     Default  Filter the collection using the expression script block (like Where-Object)
                              to a maximum count if provided; or defaulting to all objects in the
                              collection; if no maximum count was provided in numberToReturn.
 
                     First    Display the First item in the filtered collection; or if a specific count
                              was requested in numberToReturn, return the first N objects. ('first', 5)

                     Last     Display the Last item in the filtered collection; or if a specific count
                              was requested in numberToReturn, return the last N objects. ('Last', 3)
 
                    SkipUntil Skip objects in the collection until an object passes the expression
                              script block filter, and then return the first N objects, defaulting to
                              all remaining objects if no maximum count was provided in numberToReturn.
                              This can include non-filtered items.

                     Until    Return the first N objects in a collection until an object passes the
                              expression script block filter, defaulting to all objects leading up to the
                              first object that passed if no maximum count was provided in numberToReturn.
                              This can include non-filtered items.

                     Split    Split a collection into two, placing all objects that pass the expression
                              script block filter into the first collection up to a maximum count if
                              one was provided in numberToReturn, with the rest of the filtered results
                              being dropped into the second collection regardless if they match the criteria or not.

Available in PowerShell 4.0 and later, this method provides faster performance than Where-object.

Examples

Find all the running notepad processes:

@(Get-Process).Where({ $_.Name -eq 'notepad'; })

Filter a collection of services:

# Get a set of services
$services = Get-Service

# Display the first 3 items in the collection that have a Name starting with 'r' 
$services.where({$_.Name -match '^r'},'First',3)

# Split the services into two groups: Running and not Running 
$running,$notRunning = $services.Where({$_.Status -eq 'Running'},'Split')

# Show the Running services
$running # Show the services that are not Running $notRunning

“We delight in the beauty of the butterfly, but rarely admit the changes it has gone through to achieve that beauty” ~ Maya Angelou

Related:

ForEach-Object - Loop for each object in the pipeline.
Group-Object - Group the objects that contain the same value for a common property.
Select-Object - Select objects based on parameters set in the Cmdlet command string.
Sort-Object - Sort the input objects by property value.
Where-Object - Filter input from the pipeline (Alias = where)
ForEach and Where magic methods by Kirk Munro


Copyright © SS64.com 1999-2017
Some rights reserved