共用方式為


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>]
     [-LE]
     [<CommonParameters>]
Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     [-CGE]
     [<CommonParameters>]
Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     [-CLE]
     [<CommonParameters>]
Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     [-CIn]
     [<CommonParameters>]
Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     [-GE]
     [<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>]
     [-Match]
     [<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>]
     [-Like]
     [<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>]
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>]

Description

Cmdlet Where-Object 會從傳遞給它的物件集合中選取具有特定屬性值的物件。 例如,您可以使用 Where-Object Cmdlet 來選取在特定日期之後建立的檔案、具有特定標識碼的事件,或使用特定 Windows 版本的電腦。

從 Windows PowerShell 3.0 開始,有兩種不同的方法來建構Where-Object命令。

  • 腳本區塊。 您可以使用指令碼區塊來指定屬性名稱、比較運算子及屬性值。 Where-Object 會傳回腳本區塊語句為 true 的所有物件。

    例如,下列命令會取得 Normal 優先順序類別中的進程,也就是說, PriorityClass 屬性值等於 Normal 的進程。

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

    所有 PowerShell 比較運算子都以腳本區塊格式有效。 如需比較運算子的詳細資訊,請參閱 about_Comparison_Operators

  • 比較語句。 您也可以撰寫較像自然語言的比較陳述式。 比較陳述式是在 Windows PowerShell 3.0 中引進。

    例如,下列命令也會取得優先順序類別為 Normal 的進程。 這些命令是相等的,可以交換使用。

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

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

    從 Windows PowerShell 3.0 開始,Where-Object 會在 Where-Object 命令中新增比較運算符作為參數。 除非另有指定,否則所有運算子都不區分大小寫。 在 Windows PowerShell 3.0 之前,PowerShell 語言中的比較運算元只能在腳本區塊中使用。

範例

範例 1:停止服務

這些命令會取得目前已停止的所有服務清單。

$_自動變數代表每個傳遞至 Where-Object Cmdlet 的物件。

第一個命令使用文本區塊格式,第二個命令會使用比較語句格式。

這些命令是相等的,可以交換使用。

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

範例 2:根據工作集取得進程

這些命令會列出工作集大於 25,000 KB (KB) 的進程。 因為 WorkingSet 屬性的值是以位元組儲存,所以 25,000 的值乘以 1,024。

scriptblock 和語句語法是相等的,而且可以交換使用。

Get-Process | Where-Object {$_.WorkingSet -GT 25000*1024}
Get-Process | Where-Object WorkingSet -GT (25000*1024)

範例 3:根據進程名稱取得進程

這些命令會取得具有以字母 p 開頭之 ProcessName 屬性值的進程。 Match 運算子可讓您使用正則表示式比對。

scriptblock 和語句語法是相等的,而且可以交換使用。

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

範例 4:使用比較語句格式

此範例示範如何使用 Cmdlet 的新比較語句格式 Where-Object

第一個命令使用比較陳述式格式。 此命令中不會使用任何別名,並且所有的參數都包括參數名稱。

第二個命令是更自然的比較命令格式使用方式。 其中別名會取代 Where-Object Cmdlet 名稱,並省略所有選擇性參數名稱。

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

範例 5:根據屬性取得命令

此範例示範如何撰寫會傳回 True 或 False 的項目,或撰寫具有任何指定屬性值的命令。 每個範例都會顯示命令的腳本區塊和比較語句格式。

# 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 OutputType
Get-Command | where {$_.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 PSIsContainer
Get-ChildItem | where {$_.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 {!$_.PSIsContainer}
# You cannot use the Not operator (!) in the comparison statement format of the command.
Get-ChildItem | where PSIsContainer -eq $False

範例 6:使用多個條件

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

此範例示範如何建立 Where-Object 具有多個條件的命令。

此命令取得支援可更新之說明功能的非核心模組。 此命令會使用 Cmdlet 的 Get-ModuleListAvailable 參數來取得電腦上的所有模組。 管線運算子 (|) 會將模組傳送至 Where-Object Cmdlet,此 Cmdlet 會取得名稱不是以 Microsoft 或 PS 開頭的模組,並具有 HelpInfoURI 屬性的值,這會告訴 PowerShell 在何處尋找模組的更新說明檔。 比較語句是由 And 邏輯運算子所連接。

此範例使用指令碼區塊命令格式。 邏輯運算符,例如 AndOr,只在腳本區塊中有效。 您無法在命令的 Where-Object 比較語句格式中使用它們。

參數

-CContains

如果對象的屬性值與指定的值完全相符,表示這個 Cmdlet 會從集合取得 物件。 這項作業會區分大小寫。

例如:Get-Process | where ProcessName -CContains "svchost"

CContains 是指值的集合,如果集合包含與指定值完全相符的專案,則為 true。 如果輸入是單一物件,PowerShell 會將它轉換成一個物件的集合。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CEQ

表示如果屬性值與指定的值相同,這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CGE

指出如果屬性值大於或等於指定的值,這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CGT

表示如果屬性值大於指定的值,這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CIn

表示如果屬性值包含指定的值,這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。

例如:Get-Process | where -Value "svchost" -CIn ProcessName

CIn 類似於 CContains,不同之處在於屬性和值位置會反轉。 例如,下列陳述式都是 True。

"abc", "def" -CContains "abc"

"abc" -CIn "abc", "def"

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CLE

表示如果屬性值小於或等於指定的值,這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CLike

指出如果屬性值符合包含通配符的值,這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。

例如:Get-Process | where ProcessName -CLike "*host"

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CLT

表示如果屬性值小於指定的值,這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CMatch

表示如果屬性值符合指定的正則表達式,這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。 當輸入為純量時,相符的值會儲存在自動變數中 $Matches

例如:Get-Process | where ProcessName -CMatch "Shell"

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CNE

指出如果屬性值與指定的值不同,這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CNotContains

指出如果 對象的屬性值與指定的值不完全相符,這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。

例如:Get-Process | where ProcessName -CNotContains "svchost"

"NotContains" 與 "CNotContains" 是指值的集合,並且在集合未包含任何與指定的值完全相符的項目時為 True。 如果輸入是單一物件,PowerShell 會將它轉換成一個物件的集合。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CNotIn

指出如果屬性值與指定的值不完全相符,這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。

例如:Get-Process | where -Value "svchost" -CNotIn -Property ProcessName

NotInCNotIn 運算符類似於 NotContainsCNotContains,不同之處在於屬性和值位置會反轉。 例如,下列陳述式為 True。

"abc", "def" -CNotContains "Abc"

"abc" -CNotIn "Abc", "def"

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CNotLike

如果屬性值不符合包含通配符的值,則表示這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。

例如:Get-Process | where ProcessName -CNotLike "*host"

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CNotMatch

指出如果屬性值不符合指定的正則表達式,這個 Cmdlet 會取得 物件。 這項作業會區分大小寫。 當輸入為純量時,相符的值會儲存在自動變數中 $Matches

例如:Get-Process | where ProcessName -CNotMatch "Shell"

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Contains

指出如果物件屬性值中的任何專案與指定值完全相符,這個 Cmdlet 就會取得 物件。

例如:Get-Process | where ProcessName -Contains "Svchost"

如果屬性值包含單一物件,PowerShell 會將它轉換成一個物件的集合。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:IContains
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-EQ

指出如果屬性值與指定的值相同,這個 Cmdlet 會取得 物件。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:IEQ
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-FilterScript

指定用來篩選物件的指令碼區塊。 將腳本區塊括在大括號 ( {} ) 。

參數名稱 FilterScript 是選擇性的。

Type:ScriptBlock
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-GE

如果屬性值大於或等於指定的值,則這個 Cmdlet 會取得 物件。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:IGE
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-GT

指出如果屬性值大於指定的值,這個 Cmdlet 會取得 物件。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:IGT
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-In

指出如果屬性值符合任何指定的值,這個 Cmdlet 會取得 物件。

例如:Get-Process | where -Property ProcessName -in -Value "Svchost", "TaskHost", "WsmProvHost"

如果 Value 參數的值是單一物件,PowerShell 會將它轉換成一個物件的集合。

如果對象的屬性值是陣列,PowerShell 會使用參考相等來判斷相符專案。 Where-Object 只有在 Property 參數的值和 Value 的任何值都是物件的相同實例時,才會傳回 物件。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:IIn
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-InputObject

指定要篩選的物件。 您也可以使用管線將 物件傳送至 Where-Object

當您搭配 使用 InputObject 參數搭配 Where-Object時,會將 InputObject 值視為單一物件,而不是將命令結果管線傳送至 Where-Object。 即使值是命令結果的集合,例如 -InputObject (Get-Process),也是如此。 由於 InputObject 無法從物件的陣列或集合傳回個別屬性,因此,如果您用來 Where-Object 篩選物件集合中具有定義屬性中特定值的物件,您可以在 Where-Object 管線中使用,如本主題中的範例所示。

Type:PSObject
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Is

指出如果屬性值是指定之 .NET Framework 類型的實例,這個 Cmdlet 就會取得 物件。 使用方括號括住型別名稱。

例如,Get-Process | where StartTime -Is [DateTime]

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-IsNot

指出如果屬性值不是指定之 .NET Framework 類型的實例,這個 Cmdlet 會取得 物件。

例如,Get-Process | where StartTime -IsNot [DateTime]

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-LE

指出如果屬性值小於或等於指定的值,這個 Cmdlet 會取得 物件。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:ILE
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Like

如果屬性值符合包含通配符的值,則這個 Cmdlet 會取得 物件。

例如:Get-Process | where ProcessName -Like "*host"

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:ILike
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-LT

指出如果屬性值小於指定的值,這個 Cmdlet 會取得 物件。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:ILT
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Match

表示如果屬性值符合指定的正則表達式,這個 Cmdlet 會取得 物件。 當輸入為純量時,相符的值會儲存在自動變數中 $Matches

例如:Get-Process | where ProcessName -Match "shell"

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:IMatch
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-NE

指出如果屬性值與指定的值不同,這個 Cmdlet 會取得 物件。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:INE
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-NotContains

如果屬性值中的任何專案都與指定的值完全相符,表示這個 Cmdlet 會取得 物件。

例如:Get-Process | where ProcessName -NotContains "Svchost"

NotContains 是指值的集合,如果集合不包含任何與指定值完全相符的專案,則為 true。 如果輸入是單一物件,PowerShell 會將它轉換成一個物件的集合。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:INotContains
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-NotIn

指出如果屬性值與任何指定值不完全相符,則這個 Cmdlet 會取得 物件。

例如:Get-Process | where -Value "svchost" -NotIn -Property ProcessName

如果 Value 的值是單一物件,PowerShell 會將它轉換成一個物件的集合。

如果對象的屬性值是陣列,PowerShell 會使用參考相等來判斷相符專案。 Where-Object 只有在 Property 的值和 Value 的任何值都不是物件的相同實例時,才會傳回 物件。

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:INotIn
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-NotLike

如果屬性值不符合包含通配符的值,則表示這個 Cmdlet 會取得 物件。

例如:Get-Process | where ProcessName -NotLike "*host"

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:INotLike
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-NotMatch

表示當屬性值不符合指定的正則表達式時,這個 Cmdlet 會取得 物件。 當輸入為純量時,相符的值會儲存在自動變數中 $Matches

例如:Get-Process | where ProcessName -NotMatch "PowerShell"

此參數是在 Windows PowerShell 3.0 引進。

Type:SwitchParameter
Aliases:INotMatch
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Property

指定物件屬性的名稱。

參數名稱 Property 是選擇性的。

此參數是在 Windows PowerShell 3.0 引進。

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Value

指定屬性值。 參數名稱 Value 是選擇性的。 當搭配下列比較參數使用時,此參數會接受通配符:

  • CLike
  • CNotLike
  • 喜歡
  • NotLike

此參數是在 Windows PowerShell 3.0 引進。

Type:Object
Position:1
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:True

輸入

PSObject

您可以使用管線將物件傳送至此 Cmdlet。

輸出

Object

此 Cmdlet 會從輸入物件集傳回選取的專案。

備註

  • 從 Windows PowerShell 4.0 開始,WhereForEach新增方法以與集合搭配使用。
    • 您可以在這裡深入了解這些新方法 about_arrays