PowerShell Logo Small

Where-Object



This is the built-in help made by Microsoft for the command 'Where-Object', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Selects objects from a collection based on their property values.

SYNTAX


Where-Object [-Property] <String> [[-Value] [<Object>]] [-EQ] [-InputObject [<PSObject>]] [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -Contains [<CommonParameters>]
Where-Object [-FilterScript] <ScriptBlock> [-InputObject [<PSObject>]] [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -GE [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -GT [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -In [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CContains [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CEQ [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CGE [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CGT [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CIn [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CLE [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CLike [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CLT [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CMatch [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CNE [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CNotContains [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CNotIn [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CNotLike [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -CNotMatch [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -Is [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -IsNot [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -LE [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -Like [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -LT [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -Match [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -NE [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -NotContains [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -NotIn [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -NotLike [<CommonParameters>]
Where-Object [-Property] <String> [[-Value] [<Object>]] [-InputObject [<PSObject>]] -NotMatch [<CommonParameters>]



Search powershellhelp.space

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 with a particular version of Windows.


Beginning 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 Windows PowerShell comparison operators are valid in the script block format. For more information about comparison operators, see about_Comparison_Operators
(http://go.microsoft.com/fwlink/?LinkID=113217).


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 can be used interchangeably.


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


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


Beginning in Windows PowerShell 3.0, Where-Object adds comparison operators as parameters in a Where-Object command. Unless specified, all operators are case-insensitive.
Prior to Windows PowerShell 3.0, the comparison operators in the Windows PowerShell language could be used only in script blocks.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/p/?linkid=289623
Compare-Object
ForEach-Object
Group-Object
Measure-Object
New-Object
Select-Object
Sort-Object
Tee-Object

REMARKS

<

Examples


-------------------------- EXAMPLE 1 --------------------------

PS C:\>Get-Service | Where-Object {$_.Status -eq "Stopped"}
PS C:\>Get-Service | where Status -eq "Stopped"



This command gets a list of all services that are currently stopped. The "$_" symbol represents each object that is passed to the Where-Object cmdlet.

The first command uses the script block format. The second command uses the comparison statement format. The commands are equivalent and can be used interchangeably.









-------------------------- EXAMPLE 2 --------------------------

PS C:\>Get-Process | Where-Object {$_.WorkingSet -gt 25000*1024}
PS C:\>Get-Process | Where-Object WorkingSet -gt (25000*1024)



This command lists processes that have a working set greater than 25,000 kilobytes (KB). Because the value of the WorkingSet property is stored in bytes, the value of 25,000
is multiplied by 1,024.

The first command uses the script block format. The second command uses the comparison statement format. The commands are equivalent and can be used interchangeably.






-------------------------- EXAMPLE 4 --------------------------

PS C:\>Get-Process | Where-Object {$_.ProcessName -Match "^p.*"}
PS C:\>Get-Process | Where-Object ProcessName -Match "^p.*"



This command gets the processes that have a ProcessName property value that begins with the letter "p". The match operator lets you use regular expression matches.

The first command uses the script block format. The second command uses the comparison statement format. The commands are equivalent and can be used interchangeably.






-------------------------- EXAMPLE 5 --------------------------

PS C:\>Get-Process | Where-Object -Property Handles -ge -Value 1000
PS C:\>Get-Process | where Handles -ge 1000



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

The first command uses the comparison statement format. In this command, no aliases are used and all parameters include the parameter name.

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






-------------------------- EXAMPLE 6 --------------------------

The first pair of commands gets commands that have any value for the OutputType property of the command. They omit commands that do not have an OutputType property and those
that have an OutputType property, but no property value.
PS C:\>Get-Command | where OutputType
PS C:\>Get-Command | where {$_.OutputType}

The second pair of commands gets objects that are containers. It gets objects that have the PSIsContainer property with a value of True ($true) and excludes all others.The
"equals $True" (-eq $true) part of the command is assumed by the language. You do not need to specify it explicitly.
PS C:\>Get-ChildItem | where PSIsContainer
PS C:\>Get-ChildItem | where {$_.PSIsContainer}

The third pair of commands uses the Not operator (!) to get objects that are not containers. It gets objects that do have the PSIsContainer property and those that have a
value of False ($false) for the PSIsContainer property.You cannot use the Not operator (!) in the comparison statement format of the command.
PS C:\>Get-ChildItem | where {!$_.PSIsContainer}
PS C:\>Get-ChildItem | where PSIsContainer -eq $false



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






-------------------------- EXAMPLE 7 --------------------------

PS C:\>Get-Module -ListAvailable | where {($_.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 do not begin with "Microsoft" or "PS" and have a value for the
HelpInfoURI property, which tells Windows PowerShell where to find updated help files for the module. The comparison statements are connected by the -And logical operator.

The example uses the script block command format. Logical operators, such as -And and -Or, are valid only in script blocks. You cannot use them in the comparison statement
format of a Where-Object command.

For more information about Windows PowerShell logical operators, see about_Logical_Operators (http://go.microsoft.com/fwlink/?LinkID=113238). For more information about the
Updatable Help feature, see about_Updatable_Help (http://go.microsoft.com/fwlink/?LinkID=235801).