PowerShell Where (Where-Object) Explained With Examples

Photo of author

By Victor Ashiedu

Published

Have you ever wondered how to use the PowerShell Where (Where-Object) cmdlet? In this guide, you’ll learn all there is to know about this cmdlet.

In the first section of this guide, I will give you an overview of the Where-Object cmdlet. Then, in the second section, you’ll learn about the syntax of Powershell Where-Object.

Not only that, but you will also learn about the parameters of this all-important cmdlet. I also have a section with multiple examples that show you how to use this cmdlet in scripting.

Finally, in case you still have questions after reading all the sections, I have an FAQ section. In the FAQ section, you will get answers to commonly asked questions about PowerShell Where Where-Object.

Overview

PowerShell Where (Where-Object) An Overview

You can use the Where-Object cmdlet to select (filter) objects from a collection of objects based on the objects’ property values.

The Where-Object cmdlet can accept the collection of objects in two ways.

Firstly, you can send the objects via the pipeline. Alternatively, you can use the InputObject parameter to specify the collection of objects.

Moving on to how you construct the Where-Object, starting from Windows PowerShell 3.0, you can do this in two ways.

Firstly, you can use a script block to construct a Where-Object command. A script block is a set of statements enclosed in a {}.

When you use this method, you’ll call the object’s property with the pipeline automatic variable, $_, followed by a dot (.), then the name of the property.

Once you specify the object’s property as described above, you’ll then use a comparison operator to compare the property to a specified value.

Here is an example of how to use a script block to construct a Where-Object command:

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

Another method to construct a Where-Object command is to use a comparison statement. Unlike script blocks, comparison statements are much like natural language.

Additionally, to use a comparison statement in a Where-Object command, you need to use the Property parameter of the Where-Object. Then, you use a comparison operator to specify a property value you want to return.

To construct the previous PowerShell Where-Object command with a comparison statement, use the command below:

Get-Service | Where-Object -Property Status -eq -Value "Stopped" 
You do not have to specify the Value parameter in the last command. The command below will produce the same result. I can also omit to specify -Property altogether.
Get-Service | Where-Object -Property Status -eq "Stopped" 
Get-Service | Where-Object Status -eq "Stopped" 

Syntaxes Of PowerShell Where (Where-Object)

As hinted in the previous section, you can construct a Where-Object command in two ways.

The first syntax below shows the Powershell Where-Object constructed with a comparison statement. Furthermore, in the second syntax, I have constructed Where-Object with a script block.

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [-EQ] [-Match] [-CEQ] [-NE] [-CNE] [-GT] [-CGT] [ -LT] [-CLT] [-GE] [-CGE] [-LE]* 
     [[-Value] <Object>]
     [<CommonParameters>]
*These are comparison operators. You can use any of the comparison operators here. By default, comparison operators are not case-sensitive.

To make them case-sensitive, add “C”, in front of the original operator. For example, to make the -LT (less than) operator case-sensitive, use -CLT
Where-Object
     [-InputObject <PSObject>]
     [-FilterScript] ScriptBlock
     [<CommonParameters>]

Parameters Of PowerShell Where (Where-Object)

In the table below, I listed all the parameters of Where-Object with a detailed explanation.

Where-Object ParametersComments/Notes
InputObject Instead of pipping values to Where-Object, you can use the InputObject parameter to specify the values you want to filter. However, it is recommended to pipe objects instead of using InputObject parameter. The reason for this is that if you use InputObject parameter, the InputObject value is treated as a single object, not a collection
PropertyThe Property parameter is used when you construct Powershell Where-Object with a comparison statement. Use this parameter to specify the property of the object you want to filter from the collection of object properties.
-EQ, -NE, and other comparison parametersThe use of comparison operators as parameters was introduced in Windows PowerShell 3.0. These parameters behave as normal comparison operators. For example, if I use -EQ parameter in Powershell Where-Object, it checks whether the property of the object is the same as the specified comparison value. For example Status -eq “Stopped”
ValueUse this to specify a property value. Witing the parameter name, Value, is optional.
FilterScriptYou use the FilterScript parameter when you use a script block to construct a Where-Object command. Use this parameter to specify the script block used in filtering the objects – enclose the script block in braces, {}.

PowerShell Where (Where-Object) Examples

PowerShell Where (Where-Object) Examples

Finally, you got to the fun part! Although this is the fun bit, to enjoy this section, you need all the information in the previous sections.

How To Use The -LIKE Operator In PowerShell Where (Where-Object)

Starting from Windows PowerShell 3.0, Microsoft introduced comparison operators as parameters of Where-Object. So, it is not surprising that the -LIKE operator is a parameter of Where-Object.

You use the -LIKE operator when you construct Where-Object with a comparison statement. Use the -LIKE parameter to get objects by filtering with wildcard characters.

Here is an example…

Get-Service | Where-Object -Property Status -LIKE -Value "St*" 

This command returns all processes with a status that starts with “St”. So, I expect the command to return all services with the Stopped status.

Here is the result…

How To Use The -LIKE Operator In PowerShell Where (Where-Object)

In addition to using the -LIKE parameter when you construct with a comparison statement, you can also use it in a Where-Object script block construct.

Here is the previous example with a script block construct.

Get-Service | Where-Object {$_.Status -LIKE "St*"}

How To Use The -MATCH Operator In PowerShell Where (Where-Object)

When you specify the -MATCH parameter in a Where-Object comparison construct Where-Object returns objects that are based on a specified regular expression (RegEx).

For example, if I want to return all services on my PC that start with “d”, I’ll use any of the commands below:

Get-Service | Where-Object -Property Name -Match "^d.*"
Get-Service | Where-Object {$_.Name -Match "^d.*"}

The regular expression, “^d.*” returns all processes that begin with “d”. Here is the result.

How To Use The NOT EQUAL (-NE) Operator In PowerShell Where (Where-Object)

As I have hinted more than once in this guide, Microsoft introduced comparison operators as parameters of Where-Object from PowerShell version 3.0.

This means that the NOT EQUAL (-NE) Operator is now a parameter of Where-Object. Here is a simple example of how to use the -NE parameter in Where-Object.

Get-Service | Where-Object -Property Status -NE "Stopped"

The command returns all services with the status NOT “Stopped”. Here is the result in PowerShell. In other words, the command returns all services with the status of “Running”.

How To Use The NOT EQUAL (-NE) Operator In PowerShell Where (Where-Object)

Before I move on from this example, you may like to see the command constructed in a script block…

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

How To Use The -AND Operator In PowerShell Where (Where-Object)

Generally, you use the -AND operator to return True if 2 or more conditions return True. You can apply this to a Powershell Where-Object statement construct.

Continuing with the Get-Service example, the command below uses the -AND operator to return services with status as “Stopped” and a name like “MicrosoftEd”

Get-Service | Where-Object {($_.Status -EQ "Stopped") -AND ($_.Name -LIKE "MicrosoftEd*")}

Here is the result of the command in Powershell…

How To Use PowerShell Where (Where-Object) To Check If A Collection Contains A String

As I have mentioned several times, one of the ways you can create a Where-Object is by using a comparison statement. One of the comparison parameters of Where-Object is -CONTAINS.

This is one of the containment operators. You can use this operator in a Where-Object comparison statement construct.

Here is an example of a command that returns a service whose name contains WinRM. You can also construct the statement with a script block – see the second command below…

Get-Service | Where-Object -Property Name -CONTAINS "WinRM"
Get-Service | Where-Object {$_.Name -CONTAINS "WinRM"}

The two commands present the same result…

How To Use PowerShell Where (Where-Object) To If A Collection Contains A String
The -CONTAINS operator does not support wildcards.

How To Use PowerShell Where() Method To Return Specified Properties From A Collection.

From PowerShell 4.0, Microsoft introduced the Where() and ForEach() methods. You can access these two methods the way you access any other method.

Since this example is about the Where(), I will focus on it. You read an example of how to use the ForEach() method by opening this link – How To Combine PowerShell Get-ChildItem, ForEach Method And Get-Content.

Specifically, to access a method, you add a dot after the Where() method, enter a dot after the object, followed by Where(). Then, within the (), you enter the script block – enclosed in {} – that specifies the property to return.

In this example, I will re-write this Where-Object construct using the PowerShell Where() Method construct.

Get-Service | Where-Object {$_.Name -CONTAINS "WinRM"}

Here is the PowerShell Where() Method of the above command…

(Get-Service).Where({$_.Name -CONTAINS "WinRM"})

As expected the above command returned the same result as the one above.

How To Use PowerShell Where() Method To Return Specified Properties From A Collection.

Before I proceed to the next example, I will like to point your attention to the () I used to enclose Get-Service. Without this, the command will fail.

However, you can avoid using the () to enclose the command before the PowerShell Where() Method. To achieve this, save the command in a variable.

$service = Get-Service

Then, call the Where() Method using the variable…

$service.Where({$_.Name -CONTAINS "WinRM"})

How To Use Powershell Where-Object To Check If An Array Contains A Specified String

In this example, I will use the Where-Object script block construct to check if an array contains a string.

Before I use the Where-Object, I have to extract the content of the file first. Then, save it in a variable (optional).

$content = Get-Content D:\report\about_operators.txt

Next, I’ll pipe the variable to the Where-Object script block construct.

$content = Get-Content D:\report\about_operators.txt
$content | Where-Object {$_ -like "*Operators*"}

See the result in the screenshot below…

How To Use PowerShell Where-Object To Return Properties That Begins Or Starts With A Specified String

If you want PowerShell Where-Object to return properties that begin with a string, you need to use the -MATCH parameter. Then, use a regular expression (RegEx).

Continuing from the text file used in the last example, if I want to return all lines in the text file that begins with the word “Operator” (case-insensitive), I will use the commands below:

$content = Get-Content D:\report\about_operators.txt
$content | Where-Object {$_ -Match "^Operator.*"}

The first command saves the content of the text file in a variable. The character, ^ tells PowerShell to return strings that start with “Operator”.

Here is the result in PowerShell…

How To Use PowerShell Where-Object To Return Files Between Two Dates

I must confess that this is a very exciting example for me! I want to show you how to use PowerShell Where-Object to return only files modified between two dates.

To demonstrate this example, I’ll use files on D:\report. But before I dive in, let me first show you all the files in this folder.

I will use the Get-ChildItem command to display the files.

Get-ChildItem D:\report -File

The files have a property called LastWriteTime. This is the property I need to manipulate with the Where-Object.

Not so fast though, as we need to determine the date range for the LastWriteTime (last time the file was modified) for the files we want to return.

In this example, I want to return files modified between 17 and 13 days ago. So, the first step is to use the Get-Date command with the AddDays Method to calculate those dates.

In the commands below, I have saved the two dates in two variables called $13daysago and $17daysago.

$13daysago = (Get-Date).AddDays(-13)
$17daysago = (Get-Date).AddDays(-17)

Finally, I can pipe the output of Get-ChildItem to a Where-Object script block construct. Here is the command that does the final magic…

Get-ChildItem D:\report -File | Where-Object {($_.LastWriteTime -LE $13daysago) -AND ($_.LastWriteTime -GE $17daysago)}

Effectively, the command uses the PowerShell Where-Object to return all files that have a LastWriteTime Less than or Equal to 13 days ago. Then, it also returns all files with LastWriteTime Greater than or Equal to 17 days ago.

Finally, the Where-Object construct combines those two results with the -AND operator. Notably, the -AND operator only returns results if the conditions on both sides of the operator are True.

Here is the script with all the commands…

$13daysago = (Get-Date).AddDays(-13)
$17daysago = (Get-Date).AddDays(-17)
Get-ChildItem D:\report -File | Where-Object {($_.LastWriteTime -LE $13daysago) -AND ($_.LastWriteTime -GE $17daysago)}

And the result in PowerShell…

So, did my script return the results I wanted? Let’s analyze the result.

The date I am writing this guide is 16th June 2022.

So, 13 days ago from today was the 3rd of June 2022. Likewise, 17 days ago was the 30th of May 2022. If you take a closer look at the last screenshot, my script returned files with LastWriteTime ranging from 31st May to 3rd June.

This agrees with Less than or Equal to 13 days ago AND Greater than or Equal to 17 days ago!

If you’re a sysadmin, you can apply this script in a scenario to manage your log files. For instance, if you have an application that saves log files and you want to see the size of files saved between two dates, you can use this script.

If you want the script NOT to include the dates, but every other date in between, instead of using Less than or Equal (-LE), use Less Than (-LT).
Similarly, instead of using Greater than or Equal (-GE), use Greater Than (-GT)

Hopefully, you can see why I was excited to present this example to you!

Frequently Asked Questions

1. What Is Where-Object In PowerShell?

Where-Object is a cmdlet you can use to select objects from a collection based on properties you specify.

2. What Is The Alias Of Where-Object?

The alias of Where-Object is Where or “?” (without the quotes)

3. What Does @() Mean In PowerShell?

@() is used to create an array in PowerShell. For example, the command below creates an array of three items – System, Documents, and Downloads.

@(“System”, “Documents”, “Downloads”)

4. What Is Recurse In PowerShell?

Recurse is a Switch parameter in some PowerShell cmdlets that instructs the cmdlet to perform a task beyond the first level.

For example, if you use the Recurse parameter in Get-ChildItem, Get-ChildItem will return information from the top level and all sub-directories.

To see a list of all cmdlets that has the Recurse parameter, run the command below:

Get-Command -ParameterName Recurse

As of June 16th when I updated this article, the following cmdlets have the Recurse parameter:

Copy-Item
Get-ChildItem
Get-WmiObject
Remove-Item
Update-Help

5. How Do I Find A Specific File In PowerShell?

To find a specific file in PowerShell, pipe Get-ChildItem to Where-Object. Then, in the Where-Object construct, filter by the Name property, using the -EQ operator to specify the name of the file (including the .txt extension).

For example, to return a file, about_operators.txt, I’ll use the command below:

Get-ChildItem D:\report -File | Where-Object {$_.Name -EQ “about_operators.txt”}

My Final Thoughts

My Final Thoughts About PowerShell Where-Object

The Where-Object (Where or “?”) is a very versatile PowerShell construct that you will file useful in your scripting career. You can use it to return objects from a collection based on the properties you specify.

You can construct Powershell Where-Object in two ways. One, using the comparison construct.

Secondly, you can construct the Where-Object statement using the script block construct.

I hope I made it really easy for you to learn about the PowerShell Where-Object and its applications!

If the post was of any help to you, kindly take a few minutes to tell us what you think at [discourse_topic_url].

However, if you have any questions regarding this article please post your question at [discourse_topic_url]. Our team and other community members will come back to you with a reply as soon as possible.

Finally, you may continue expanding your PowerShell knowledge by reading our other PowerShell guides.

References And Further Reading

  1. Where-Object
  2. about_Comparison_Operators
  3. How to Use PowerShell Where-Object to Filter All the Things
  4. Introduction to the Where Method in PowerShell
  5. [discourse_topic_url]
We go the extra mile to deliver the highest quality content for our readers. Read our Content Writing, Content Review, and Anti-Plagiarism policies to learn more.

About the Author

Photo of author

Victor Ashiedu

Victor is the founder of InfoPress Media, publishers of Ilifeguides and Itechguides. With 20+ years of experience in IT infrastructure, his expertise spans Windows, Linux, and DevOps. Explore his contributions on Itechguides.com for insightful how-to guides and product reviews.

Related Articles

Get in Touch

If this article does not meet your expectations, kindly let us know. We have various ways you can get in touch with us:

  1. Respond to "Was this page helpful?" above
  2. Leave a comment with the "Leave a Comment" form below
  3. Email us at [email protected] or via the Contact Us page.

Leave a comment