Where-Object

Syntax

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     [-EQ]
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-FilterScript] <ScriptBlock>
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -Match
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CEQ
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -NE
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CNE
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -GT
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CGT
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -LT
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CLT
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -GE
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CGE
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -LE
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CLE
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -Like
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CLike
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -NotLike
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CNotLike
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CMatch
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -NotMatch
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CNotMatch
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -Contains
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CContains
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -NotContains
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CNotContains
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -In
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CIn
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -NotIn
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -CNotIn
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -Is
     [<CommonParameters>]

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -IsNot
     [<CommonParameters>]

Description

The Where-Object cmdlet selects objects that have particular property values from the collection of objects that are passed to it. For example, you can use the Where-Object cmdlet to select files that were created after a certain date, events with a particular ID, or computers that use a particular version of Windows.

Starting in Windows PowerShell 3.0, there are two different ways to construct a Where-Object command.

• Script block. You can use a script block to specify the property name, a comparison operator, and a property value. Where-Object returns all objects for which the script block statement is true.

  For example, the following command gets processes in the Normal priority class, that is, processes where the value of the PriorityClass property equals Normal.

  Get-Process | Where-Object {$_.PriorityClass -eq "Normal"}

  All PowerShell comparison operators are valid in the script block format. For more information, see about_Comparison_Operators.

• Comparison statement. You can also write a comparison statement, which is much more like natural language. Comparison statements were introduced in Windows PowerShell 3.0.

  For example, the following commands also get processes that have a priority class of Normal. These commands are equivalent and you can use them interchangeably.

  Get-Process | Where-Object -Property PriorityClass -EQ -Value "Normal"

  Get-Process | Where-Object PriorityClass -EQ "Normal"

  Starting in Windows PowerShell 3.0, Where-Object adds comparison operators as parameters in a Where-Object command. Unless specified, all operators are case-insensitive. Before Windows PowerShell 3.0, the comparison operators in the PowerShell language were only usable in script blocks.

When you provide a single Property to Where-Object, the cmdlet treats the value of the property as a boolean expression. When the value of the property's Length isn't zero, the expression evaluates to $true. For example: ('hi', '', 'there') | Where-Object Length

The previous example is functionally equivalent to:

• ('hi', '', 'there') | Where-Object Length -GT 0
• ('hi', '', 'there') | Where-Object { $_.Length -gt 0 }

For more information about how PowerShell evaluates booleans, see about_Booleans.

Examples

Example 1: Get stopped services

These commands get a list of all services that are stopped. The $_ automatic variable represents each object that's passed to the Where-Object cmdlet.

The first command uses the script block format, the second command uses the comparison statement format. The commands filter the services the same way and return the same output. Only the syntax is different.

Get-Service | Where-Object { $_.Status -eq "Stopped" }
Get-Service | Where-Object Status -EQ "Stopped"

Example 2: Get processes based on working set

These commands list processes that have a working set greater than 250 megabytes (MB). The commands filter the processes the same way and return the same output. Only the syntax is different.

Get-Process | Where-Object { $_.WorkingSet -GT 250MB }
Get-Process | Where-Object WorkingSet -GT 250MB

Example 3: Get processes based on process name

These commands get the processes that have a ProcessName property value that begins with the letter p. The Match operator lets you use regular expression matches.

The commands filter the processes the same way and return the same output. Only the syntax is different.

Get-Process | Where-Object { $_.ProcessName -Match "^p.*" }
Get-Process | Where-Object ProcessName -Match "^p.*"

Example 4: Use the comparison statement format

This example shows how to use the new comparison statement format of the Where-Object cmdlet.

The first command uses the comparison statement format. It doesn't use any aliases and includes the name for every parameter.

The second command is the more natural use of the comparison command format. The command substitutes the where alias for the Where-Object cmdlet name and omits all optional parameter names.

The commands filter the processes the same way and return the same output. Only the syntax is different.

Get-Process | Where-Object -Property Handles -GE -Value 1000
Get-Process | where Handles -GE 1000

Example 5: Get commands based on properties

This example shows how to write commands that return items that are true or false or have any value for a specified property. Each example shows both the script block and comparison statement formats for the command.

The commands filter their input the same way and return the same output. Only the syntax is different.

# Use Where-Object to get commands that have any value for the OutputType
# property of the command. This omits commands that do not have an OutputType
# property and those that have an OutputType property, but no property value.
Get-Command | Where-Object OutputType
Get-Command | Where-Object { $_.OutputType }

# Use Where-Object to get objects that are containers. This gets objects that
# have the **PSIsContainer** property with a value of $True and excludes all
# others.
Get-ChildItem | Where-Object PSIsContainer
Get-ChildItem | Where-Object { $_.PSIsContainer }

# Finally, use the -not operator (!) to get objects that are not containers.
# This gets objects that do have the **PSIsContainer** property and those
# that have a value of $False for the **PSIsContainer** property.
Get-ChildItem | Where-Object { !$_.PSIsContainer }
# You cannot use the -not operator (!) in the comparison statement format
# of the command.
Get-ChildItem | Where-Object PSIsContainer -eq $False

Example 6: Use multiple conditions

Get-Module -ListAvailable | Where-Object {
    ($_.Name -notlike "Microsoft*" -and $_.Name -notlike "PS*") -and $_.HelpInfoUri
}

This example shows how to create a Where-Object command with multiple conditions.

This command gets non-core modules that support the Updatable Help feature. The command uses the ListAvailable parameter of the Get-Module cmdlet to get all modules on the computer. A pipeline operator (|) sends the modules to the Where-Object cmdlet, which gets modules whose names don't begin with Microsoft or PS, and have a value for the HelpInfoURI property, which tells PowerShell where to find updated help files for the module. The -and logical operator connects the comparison statements.

The example uses the script block command format. Logical operators, such as -and,-or, and -not are valid only in script blocks. You can't use them in the comparison statement format of a Where-Object command.

• For more information about PowerShell logical operators, see about_Logical_Operators.
• For more information about the Updatable Help feature, see about_Updatable_Help.

Parameters

-CContains

-CEQ

-CGE

-CGT

-CIn

-CLE

-CLike

-CLT

-CMatch

-CNE

-CNotContains

-CNotIn

-CNotLike

-CNotMatch

-Contains

-EQ

-FilterScript

-GE

-GT

-In

-InputObject

-Is

-IsNot

-LE

-Like

-LT

-Match

-NE

-NotContains

-NotIn

-NotLike

-NotMatch

-Property

-Value

Inputs

PSObject

You can pipe any object to this cmdlet.

Outputs

Object

This cmdlet returns the selected items from the input object set.

Notes

Windows PowerShell includes the following aliases for Where-Object:

• ?
• where

Starting in Windows PowerShell 4.0, Where and ForEach methods were added for use with collections.

You can read more about these methods here about_arrays

Related Links

• Compare-Object
• ForEach-Object
• Group-Object
• Measure-Object
• New-Object
• Select-Object
• Sort-Object
• Tee-Object
• about_Booleans