diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Logical_Operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Logical_Operators.md index d52596d0913..c45531fbfad 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Logical_Operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Logical_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that connect statements in PowerShell. Locale: en-US -ms.date: 08/29/2022 +ms.date: 12/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_logical_operators?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Logical_Operators @@ -17,10 +17,35 @@ Describes the operators that connect statements in PowerShell. The PowerShell logical operators connect expressions and statements, allowing you to use a single expression to test for multiple conditions. -For example, the following statement uses the and operator and the or operator -to connect three conditional statements. The statement is true only when the -value of $a is greater than the value of $b, and either $a or $b is less than -20. +Statements that use the logical operators return boolean (TRUE or FALSE) +values. + +The PowerShell logical operators evaluate only the statements required to +determine the truth value of the statement. If the left operand in a statement +that contains the `-and` operator is FALSE, the right operand isn't evaluated. +If the left operand in a statement that contains the `-or` statement is TRUE, +the right operand isn't evaluated. As a result, you can use these statements in +the same way that you would use the `if` statement. + +> [!IMPORTANT] +> The `-and`, `-or` and `-xor` operators have equal precedence. They are +> evaluated from left to right as they appear within the expression. For more +> information, see [about_Operator_Precedence][01]. + +## Syntax + +The syntax of the logical operators is as follows: + +```Syntax + {-and | -or | -xor} +{! | -not} +``` + +## Examples + +The following example uses the `-and` and `-or` operators to connect three +conditional statements. The result is TRUE only when the value of `$a` is +greater than the value of `$b`, and either `$a` or `$b` is less than `20`. ```powershell ($a -gt $b) -and (($a -lt 20) -or ($b -lt 20)) @@ -46,38 +71,29 @@ PowerShell supports the following logical operators. (1 -eq 1) -xor (2 -eq 2) # Result is False ``` -- Logical not (`-not`) or (`!`) - Negates the statement that follows. +- Logical NOT (`-not`) or (`!`) - Negates the statement that follows. ```powershell -not (1 -eq 1) # Result is False !(1 -eq 1) # Result is False ``` -The previous examples also use the equal to comparison operator `-eq`. For more -information, see [about_Comparison_Operators](about_Comparison_Operators.md). -The examples also use the Boolean values of integers. The integer 0 has a value -of FALSE. All other integers have a value of TRUE. - -The syntax of the logical operators is as follows: - -```Syntax - {-and | -or | -xor} -{! | -not} -``` - -Statements that use the logical operators return Boolean (TRUE or FALSE) -values. - -The PowerShell logical operators evaluate only the statements required to -determine the truth value of the statement. If the left operand in a statement -that contains the and operator is FALSE, the right operand isn't evaluated. If -the left operand in a statement that contains the or statement is TRUE, the -right operand isn't evaluated. As a result, you can use these statements in -the same way that you would use the `if` statement. +The previous examples also use the equality comparison operator, `-eq`. For +more information, see [about_Comparison_Operators][03]. The examples also use +the boolean values of integers. The integer `0` has a boolean value of FALSE. +All other integers have a value of TRUE. ## See also -- [about_Operators](about_Operators.md) -- [about_Comparison_operators](about_Comparison_Operators.md) -- [about_If](about_If.md) -- [Compare-Object](xref:Microsoft.PowerShell.Utility.Compare-Object) +- [about_Operators][02] +- [about_Operator_Precedence][01] +- [about_Comparison_Operators][03] +- [about_If][04] +- [Compare-Object][05] + + +[01]: about_Operator_Precedence.md +[02]: about_Operators.md +[03]: about_Comparison_Operators.md +[04]: about_If.md +[05]: xref:Microsoft.PowerShell.Utility.Compare-Object diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index e38eb8bb542..dd3e2a435b4 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -1,7 +1,7 @@ --- description: Lists the PowerShell operators in precedence order. Locale: en-US -ms.date: 06/29/2021 +ms.date: 12/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operator_precedence?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Operator_Precedence @@ -33,15 +33,15 @@ evaluated. Operators on the same line, or in the same group, have equal precedence. The Operator column lists the operators. The Reference column lists the -PowerShell Help topic in which the operator is described. To display the topic, -type `Get-Help `. +PowerShell Help topic in which the operator is described. To display the topic +interactively, use `Get-Help -Name `. | OPERATOR | REFERENCE | | --------------------------- | ------------------------------------ | | `$() @() () @{}` | [about_Operators][ops] | -| `. ?.` (member access) | [about_Operators][ops] | +| `.` (member access) | [about_Operators][ops] | | `::` (static) | [about_Operators][ops] | -| `[0] ?[0]` (index operator) | [about_Operators][ops] | +| `[0]` (index operator) | [about_Operators][ops] | | `[int]` (cast operators) | [about_Operators][ops] | | `-split` (unary) | [about_Split][split] | | `-join` (unary) | [about_Join][join] | @@ -85,16 +85,13 @@ that happens. | ------------------------------------------------------- | ------------------------------------ | | `.` (dot-source) | [about_Operators][ops] | | `&` (call) | [about_Operators][ops] | -| `? : ` (Ternary operator) | [about_Operators][ops] | -| `??` (null-coalese operator) | [about_Operators][ops] | | | (pipeline operator) | [about_Operators][ops] | | `> >> 2> 2>> 2>&1` | [about_Redirection][redir] | -| && || (pipeline chain operators) | [about_Operators][ops] | -| `= += -= *= /= %= ??=` | [about_Assignment_Operators][assign] | +| `= += -= *= /= %=` | [about_Assignment_Operators][assign] | ## Examples -The following two commands show the arithmetic operators and the effect of +The following two examples show the arithmetic operators and the effect of using parentheses to force PowerShell to evaluate the enclosed part of the expression first. @@ -107,28 +104,28 @@ PS> (2 + 3) * 4 ``` The following example gets the read-only text files from the local directory -and saves them in the `$read_only` variable. +and saves them in the `$readOnly` variable. ```powershell -$read_only = Get-ChildItem *.txt | Where-Object {$_.IsReadOnly} +$readOnly = Get-ChildItem -Path *.txt | Where-Object { $_.IsReadOnly } ``` It is equivalent to the following example. ```powershell -$read_only = ( Get-ChildItem *.txt | Where-Object {$_.IsReadOnly} ) +$readOnly = (Get-ChildItem -Path *.txt | Where-Object { $_.IsReadOnly }) ``` Because the pipeline operator (`|`) has a higher precedence than the assignment operator (`=`), the files that the `Get-ChildItem` cmdlet gets are sent to the `Where-Object` cmdlet for filtering before they are assigned to the -`$read_only` variable. +`$readOnly` variable. The following example demonstrates that the index operator takes precedence over the cast operator. This expression creates an array of three strings. Then, it uses the index -operator with a value of 0 to select the first object in the array, which is +operator with a value of `0` to select the first object in the array, which is the first string. Finally, it casts the selected object as a string. In this case, the cast has no effect. @@ -163,7 +160,7 @@ PS> (2 -gt 4) -and 1 False ``` -If the -and operator had higher precedence, the answer would be TRUE. +If the `-and` operator had higher precedence, the result would be TRUE. ```powershell PS> 2 -gt (4 -and 1) @@ -176,6 +173,27 @@ parentheses to force the evaluation order, even when it forces the default operator precedence. The parentheses make your intentions clear to people who are reading and maintaining your scripts. +The following example demonstrates the precedence between the `-and` and `-or` +logical operators. + +```powershell +PS> $true -or $false -and $false +False +``` + +In other languages such as C#, logical AND typically has a higher precedence +than logical OR, so you may expect the above expression to yield TRUE. + +However, the `-and` and `-or` operators have equal precedence in PowerShell. +They are evaluated from the left to right as they appear within the expression. +As `$true -or $false` is TRUE and `$true -and $false` is FALSE, the result of +the expression is FALSE. + +> [!IMPORTANT] +> Other contexts within PowerShell such as [WMI Query Language (WQL)][wql] and +> the Active Directory filter have their own operator precedence that might +> differ from PowerShell logical operator precedence. + ## See also - [about_Operators][ops] @@ -189,7 +207,7 @@ are reading and maintaining your scripts. - [about_Split][split] - [about_Type_Operators][type] - + [math]: about_Arithmetic_Operators.md [assign]: about_Assignment_Operators.md [compare]: about_Comparison_Operators.md @@ -200,3 +218,4 @@ are reading and maintaining your scripts. [scopes]: about_Scopes.md [split]: about_Split.md [type]: about_Type_Operators.md +[wql]: about_WQL.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Logical_Operators.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Logical_Operators.md index e2a18dcdb65..58000d02dc9 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Logical_Operators.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Logical_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that connect statements in PowerShell. Locale: en-US -ms.date: 08/29/2022 +ms.date: 12/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_logical_operators?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Logical_Operators @@ -17,10 +17,35 @@ Describes the operators that connect statements in PowerShell. The PowerShell logical operators connect expressions and statements, allowing you to use a single expression to test for multiple conditions. -For example, the following statement uses the and operator and the or operator -to connect three conditional statements. The statement is true only when the -value of $a is greater than the value of $b, and either $a or $b is less than -20. +Statements that use the logical operators return boolean (TRUE or FALSE) +values. + +The PowerShell logical operators evaluate only the statements required to +determine the truth value of the statement. If the left operand in a statement +that contains the `-and` operator is FALSE, the right operand isn't evaluated. +If the left operand in a statement that contains the `-or` statement is TRUE, +the right operand isn't evaluated. As a result, you can use these statements in +the same way that you would use the `if` statement. + +> [!IMPORTANT] +> The `-and`, `-or` and `-xor` operators have equal precedence. They are +> evaluated from left to right as they appear within the expression. For more +> information, see [about_Operator_Precedence][01]. + +## Syntax + +The syntax of the logical operators is as follows: + +```Syntax + {-and | -or | -xor} +{! | -not} +``` + +## Examples + +The following example uses the `-and` and `-or` operators to connect three +conditional statements. The result is TRUE only when the value of `$a` is +greater than the value of `$b`, and either `$a` or `$b` is less than `20`. ```powershell ($a -gt $b) -and (($a -lt 20) -or ($b -lt 20)) @@ -46,38 +71,29 @@ PowerShell supports the following logical operators. (1 -eq 1) -xor (2 -eq 2) # Result is False ``` -- Logical not (`-not`) or (`!`) - Negates the statement that follows. +- Logical NOT (`-not`) or (`!`) - Negates the statement that follows. ```powershell -not (1 -eq 1) # Result is False !(1 -eq 1) # Result is False ``` -The previous examples also use the equal to comparison operator `-eq`. For more -information, see [about_Comparison_Operators](about_Comparison_Operators.md). -The examples also use the Boolean values of integers. The integer 0 has a value -of FALSE. All other integers have a value of TRUE. - -The syntax of the logical operators is as follows: - -```Syntax - {-and | -or | -xor} -{! | -not} -``` - -Statements that use the logical operators return Boolean (TRUE or FALSE) -values. - -The PowerShell logical operators evaluate only the statements required to -determine the truth value of the statement. If the left operand in a statement -that contains the and operator is FALSE, the right operand isn't evaluated. If -the left operand in a statement that contains the or statement is TRUE, the -right operand isn't evaluated. As a result, you can use these statements in -the same way that you would use the `if` statement. +The previous examples also use the equality comparison operator, `-eq`. For +more information, see [about_Comparison_Operators][03]. The examples also use +the boolean values of integers. The integer `0` has a boolean value of FALSE. +All other integers have a value of TRUE. ## See also -- [about_Operators](about_Operators.md) -- [about_Comparison_operators](about_Comparison_Operators.md) -- [about_If](about_If.md) -- [Compare-Object](xref:Microsoft.PowerShell.Utility.Compare-Object) +- [about_Operators][02] +- [about_Operator_Precedence][01] +- [about_Comparison_Operators][03] +- [about_If][04] +- [Compare-Object][05] + + +[01]: about_Operator_Precedence.md +[02]: about_Operators.md +[03]: about_Comparison_Operators.md +[04]: about_If.md +[05]: xref:Microsoft.PowerShell.Utility.Compare-Object diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 4aea6b79599..b0791c861a6 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -1,7 +1,7 @@ --- description: Lists the PowerShell operators in precedence order. Locale: en-US -ms.date: 06/29/2021 +ms.date: 12/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operator_precedence?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Operator_Precedence @@ -33,8 +33,8 @@ evaluated. Operators on the same line, or in the same group, have equal precedence. The Operator column lists the operators. The Reference column lists the -PowerShell Help topic in which the operator is described. To display the topic, -type `Get-Help `. +PowerShell Help topic in which the operator is described. To display the topic +interactively, use `Get-Help -Name `. | OPERATOR | REFERENCE | | --------------------------- | ------------------------------------ | @@ -85,8 +85,8 @@ that happens. | ------------------------------------------------------- | ------------------------------------ | | `.` (dot-source) | [about_Operators][ops] | | `&` (call) | [about_Operators][ops] | -| `? : ` (Ternary operator) | [about_Operators][ops] | -| `??` (null-coalese operator) | [about_Operators][ops] | +| `? : ` (ternary operator) | [about_Operators][ops] | +| `??` (null-coalescing operator) | [about_Operators][ops] | | | (pipeline operator) | [about_Operators][ops] | | `> >> 2> 2>> 2>&1` | [about_Redirection][redir] | | && || (pipeline chain operators) | [about_Operators][ops] | @@ -94,7 +94,7 @@ that happens. ## Examples -The following two commands show the arithmetic operators and the effect of +The following two examples show the arithmetic operators and the effect of using parentheses to force PowerShell to evaluate the enclosed part of the expression first. @@ -107,28 +107,28 @@ PS> (2 + 3) * 4 ``` The following example gets the read-only text files from the local directory -and saves them in the `$read_only` variable. +and saves them in the `$readOnly` variable. ```powershell -$read_only = Get-ChildItem *.txt | Where-Object {$_.IsReadOnly} +$readOnly = Get-ChildItem -Path *.txt | Where-Object { $_.IsReadOnly } ``` It is equivalent to the following example. ```powershell -$read_only = ( Get-ChildItem *.txt | Where-Object {$_.IsReadOnly} ) +$readOnly = (Get-ChildItem -Path *.txt | Where-Object { $_.IsReadOnly }) ``` Because the pipeline operator (`|`) has a higher precedence than the assignment operator (`=`), the files that the `Get-ChildItem` cmdlet gets are sent to the `Where-Object` cmdlet for filtering before they are assigned to the -`$read_only` variable. +`$readOnly` variable. The following example demonstrates that the index operator takes precedence over the cast operator. This expression creates an array of three strings. Then, it uses the index -operator with a value of 0 to select the first object in the array, which is +operator with a value of `0` to select the first object in the array, which is the first string. Finally, it casts the selected object as a string. In this case, the cast has no effect. @@ -163,7 +163,7 @@ PS> (2 -gt 4) -and 1 False ``` -If the -and operator had higher precedence, the answer would be TRUE. +If the `-and` operator had higher precedence, the result would be TRUE. ```powershell PS> 2 -gt (4 -and 1) @@ -176,6 +176,27 @@ parentheses to force the evaluation order, even when it forces the default operator precedence. The parentheses make your intentions clear to people who are reading and maintaining your scripts. +The following example demonstrates the precedence between the `-and` and `-or` +logical operators. + +```powershell +PS> $true -or $false -and $false +False +``` + +In other languages such as C#, logical AND typically has a higher precedence +than logical OR, so you may expect the above expression to yield TRUE. + +However, the `-and` and `-or` operators have equal precedence in PowerShell. +They are evaluated from the left to right as they appear within the expression. +As `$true -or $false` is TRUE and `$true -and $false` is FALSE, the result of +the expression is FALSE. + +> [!IMPORTANT] +> Other contexts within PowerShell such as [WMI Query Language (WQL)][wql] and +> the Active Directory filter have their own operator precedence that might +> differ from PowerShell logical operator precedence. + ## See also - [about_Operators][ops] @@ -189,7 +210,7 @@ are reading and maintaining your scripts. - [about_Split][split] - [about_Type_Operators][type] - + [math]: about_Arithmetic_Operators.md [assign]: about_Assignment_Operators.md [compare]: about_Comparison_Operators.md @@ -200,3 +221,4 @@ are reading and maintaining your scripts. [scopes]: about_Scopes.md [split]: about_Split.md [type]: about_Type_Operators.md +[wql]: about_WQL.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_WMI.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_WMI.md new file mode 100644 index 00000000000..762c4580d29 --- /dev/null +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_WMI.md @@ -0,0 +1,110 @@ +--- +description: Windows Management Instrumentation (WMI) uses the Common Information Model (CIM) to represent systems, applications, networks, devices, and other manageable components of the modern enterprise. +Locale: en-US +ms.date: 01/03/2018 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_wmi?view=powershell-7.4&WT.mc_id=ps-gethelp +schema: 2.0.0 +title: about_WMI +--- + +# about_WMI + +## Short description + +Windows Management Instrumentation (WMI) uses the Common Information Model +(CIM) to represent systems, applications, networks, devices, and other +manageable components of the modern enterprise. + +## Long description + +Windows Management Instrumentation (WMI) is Microsoft's implementation of +Web-Based Enterprise Management (WBEM), the industry standard. + +Classic WMI uses DCOM to communicate with networked devices to manage remote +systems. Windows PowerShell 3.0 introduces a CIM provider model that uses WinRM +to remove the dependency on DCOM. This CIM provider model also uses new WMI +provider APIs that enable developers to write Windows PowerShell cmdlets in +native code (C++). + +Don't confuse WMI providers with Windows PowerShell providers. Many Windows +features have an associated WMI provider that exposes their management +capabilities. To get WMI providers, run a WMI query that gets instances of the +**__Provider** WMI class, such as the following query. + +```powershell +Get-WmiObject -Class __Provider +``` + +## Three components of WMI + +The following three components of WMI interact with Windows PowerShell: +Namespaces, Providers, and Classes. + +WMI Namespaces organize WMI providers and WMI classes into groups of related +components. In this way, they're similar to .NET Framework namespaces. +Namespaces aren't physical locations, but are more like logical databases. All +WMI namespaces are instances of the __Namespace system class. The default WMI +namespace is **root/CIMV2** (since Microsoft Windows 2000). To use Windows +PowerShell to get WMI namespaces in the current session, use a command with the +following format. + +```powershell +Get-WmiObject -Class __Namespace +``` + +To get WMI namespaces in other namespaces, use the Namespace parameter to +change the location of the search. The following command finds WMI namespaces +that reside in the **root/CIMV2/Applications** namespace. + +```powershell +Get-WmiObject -Class __Namespace -Namespace root/CIMV2/Applications +``` + +WMI namespaces are hierarchical. Therefore, obtaining a list of all namespaces +on a particular system requires performing a recursive query starting at the +root namespace. + +WMI Providers expose information about Windows manageable objects. A provider +retrieves data from a component, and passes that data through WMI to a +management application, such as Windows PowerShell. Most WMI providers are +dynamic providers, which means that they obtain the data dynamically when it's +requested through the management application. + +## Finding WMI classes + +In a default Windows 8 installation, there are more than 1,100 WMI classes in +**root/CIMV2**. With this many WMI classes, the challenge becomes identifying +the appropriate WMI class to use to perform a specific task. Windows PowerShell +3.0 provides two ways to find WMI classes that are related to a specific topic. + +For example, to find WMI classes in the **root/CIMV2** WMI namespace that are +related to disks, you can use a query such as the one shown here. + +```powershell +Get-WmiObject -List *Disk* +``` + +To find WMI classes that are related to memory, you might use a query such as +the one shown here. + +```powershell +Get-WmiObject -List *Memory* +``` + +The CIM cmdlets also provide the ability to discover WMI classes. To do this, +use the `Get-CimClass` cmdlet. The command shown here lists WMI classes related +to video. + +```powershell +Get-CimClass *Video* +``` + +Tab expansion works when changing WMI namespaces, and therefore use of tab +expansion makes sub-WMI namespaces easily discoverable. In the following +example, the `Get-CimClass` cmdlet lists WMI classes related to power settings. +To find it, type the **root/CIMV2** namespace and then press the Tab key +several times until the **power** namespace appears. Here is the command: + +```powershell +Get-CimClass *Power* -Namespace root/CIMV2/power +``` diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_WQL.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_WQL.md new file mode 100644 index 00000000000..eaf841e8c92 --- /dev/null +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_WQL.md @@ -0,0 +1,719 @@ +--- +description: Describes WMI Query Language (WQL), which can be used to get WMI objects in Windows PowerShell. +Locale: en-US +ms.date: 01/06/2026 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_wql?view=powershell-7.4&WT.mc_id=ps-gethelp +schema: 2.0.0 +title: about_WQL +--- + +# about_WQL + +## Short description + +Describes WMI Query Language (WQL), which can be used to get WMI objects in +Windows PowerShell. + +## Long description + +WQL is the Windows Management Instrumentation (WMI) query language, which is +the language used to get information from WMI. + +You aren't required to use WQL to perform a WMI query in Windows PowerShell. +Instead, you can use the parameters of the `Get-WmiObject` or `Get-CimInstance` +cmdlets. WQL queries are somewhat faster than standard `Get-WmiObject` commands +and the improved performance is evident when the commands run on hundreds of +systems. However, be sure that the time you spend to write a successful WQL +query doesn't outweigh the performance improvement. + +The basic WQL statements you need to use WQL are `SELECT`, `WHERE`, and `FROM`. + +## When to use WQL + +When working with WMI, and especially with WQL, don't forget that you are +also using Windows PowerShell. Often, if a WQL query doesn't work as +expected, it's easier to use a standard Windows PowerShell command than to +debug the WQL query. + +Unless you are returning massive amounts of data from across +bandwidth-constrained remote systems, it's rarely productive to spend hours +trying to perfect a complicated WQL query when there is an acceptable +PowerShell cmdlet that does the same thing. + +## Using the SELECT statement + +A typical WMI query begins with a `SELECT` statement that gets all properties +or particular properties of a WMI class. To select all properties of a WMI +class, use an asterisk (`*`). The `FROM` keyword specifies the WMI class. + +A `SELECT` statement has the following format: + +``` +SELECT FROM +``` + +For example, the following `SELECT` statement selects all properties (`*`) from +the instances of the **Win32_BIOS** WMI class. + +``` +SELECT * FROM Win32_BIOS +``` + +> [!NOTE] +> PowerShell only displays the default object properties. These properties are +> defined in the `Types.ps1xml` file. Use the `Select-Object` cmdlet or a +> `Format-*` cmdlet to display additional properties. + +To select a particular property of a WMI class, place the property name +between the `SELECT` and `FROM` keywords. + +The following query selects only the name of the BIOS from the **Win32_BIOS** +WMI class. The command saves the query in the `$queryName` variable. + +``` +SELECT Name FROM Win32_BIOS +``` + +To select more than one property, use commas to separate the property names. +The following WMI query selects the name and the version of the **Win32_BIOS** +WMI class. The command saves the query in the `$queryNameVersion` variable. + +```WQL +SELECT name, version FROM Win32_BIOS +``` + +## Using the WQL query + +There are three ways to use WQL query in Windows PowerShell command. + +- Use the `Get-WmiObject` cmdlet +- Use the `Get-CimInstance` cmdlet +- Use the `[wmisearcher]` type accelerator. + +## Using the Get-WmiObject cmdlet + +The most basic way to use the WQL query is to enclose it in quotation marks (as +a string) and then use the query string as the value of the **Query** parameter +of the `Get-WmiObject` cmdlet, as shown in the following example. + +```powershell +Get-WmiObject -Query "SELECT * FROM Win32_BIOS" +``` + +```output +SMBIOSBIOSVersion : 8BET56WW (1.36 ) +Manufacturer : LENOVO +Name : Default System BIOS +SerialNumber : R9FPY3P +Version : LENOVO - 1360 +``` + +You can also save the WQL statement in a variable and then use the variable as +the value of the **Query** parameter, as shown in the following command. + +```powershell +$query = "SELECT * FROM Win32_BIOS" +Get-WmiObject -Query $query +``` + +You can use either format with any WQL statement. The following command uses +the query in the `$queryName` variable to get only the **Name** and **Version** +properties of the system BIOS. + +```powershell +$queryNameVersion = "SELECT Name, Version FROM Win32_BIOS" +Get-WmiObject -Query $queryNameVersion +``` + +```output +__GENUS : 2 +__CLASS : Win32_BIOS +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 2 +__DERIVATION : {} +__SERVER : +__NAMESPACE : +__PATH : +Name : S03KT39A +Version : LENOVO - 1270 +PSComputerName : +``` + +Remember that you can use the parameters of the `Get-WmiObject` cmdlet to get +the same result. For example, the following command also gets the values of the +**Name** and **Version** properties of instances of the **Win32_BIOS** WMI +class. + +```powershell +Get-WmiObject -Class Win32_BIOS -Property Name, Version +``` + +```output +__GENUS : 2 +__CLASS : Win32_BIOS +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 2 +__DERIVATION : {} +__SERVER : +__NAMESPACE : +__PATH : +Name : S03KT39A +Version : LENOVO - 1270 +PSComputerName : +``` + +## Using the Get-CimInstance cmdlet + +Beginning in Windows PowerShell 3.0, you can use the `Get-CimInstance` cmdlet +to run WQL queries. + +`Get-CimInstance` gets instances of CIM-compliant classes, including WMI +classes. The CIM cmdlets, introduced Windows PowerShell 3.0, perform the same +tasks as the WMI cmdlets. The CIM cmdlets comply with WS-Management (WSMan) +standards and with the Common Information Model (CIM) standard, which enables +the cmdlets to use the same techniques to manage Windows computers and +computers that are running other operating systems. + +The following command uses the `Get-CimInstance` cmdlet to run a WQL query. + +Any WQL query that can be used with `Get-WmiObject` can also be used with +`Get-CimInstance`. + +```powershell +Get-CimInstance -Query "SELECT * FROM Win32_BIOS" +``` + +```output +SMBIOSBIOSVersion : S03KT39A +Manufacturer : LENOVO +Name : S03KT39A +SerialNumber : MJ0AETTX +Version : LENOVO - 1270 +``` + +`Get-CimInstance` returns a **CimInstance** object, instead of the +**ManagementObject** that `Get-WmiObject` returns, but the objects are quite +similar. + +```powershell +PS> (Get-CimInstance -Query "SELECT * FROM Win32_BIOS").GetType().FullName +Microsoft.Management.Infrastructure.CimInstance + +PS> (Get-WmiObject -Query "SELECT * FROM Win32_BIOS").GetType().FullName +System.Management.ManagementObject +``` + +## Using the wmisearcher type accelerator + +The `[wmisearcher]` type accelerator creates a **ManagementObjectSearcher** +object from a WQL statement string. The **ManagementObjectSearcher** object has +many properties and methods, but the most basic method is the Get method, which +invokes the specified WMI query and returns the resulting objects. + +Using `[wmisearcher]`, you gain easy access to the **ManagementObjectSearcher** +.NET class. This lets you query WMI and to configure the way the query is +conducted. + +To use the `[wmisearcher]` type accelerator: + +1. Cast the WQL string into a **ManagementObjectSearcher** object. +1. Call the Get method of the **ManagementObjectSearcher** object. + +For example, the following command casts the "select all" query, saves the +result in the `$bios` variable, and then calls the `Get()` method of the +**ManagementObjectSearcher** object in the `$bios` variable. + +```powershell +$bios = [wmisearcher]"SELECT * FROM Win32_BIOS" +$bios.Get() +``` + +```output +SMBIOSBIOSVersion : 8BET56WW (1.36 ) +Manufacturer : LENOVO +Name : Default System BIOS +SerialNumber : R9FPY3P +Version : LENOVO - 1360 +``` + +You can use the `[wmisearcher]` type accelerator to cast the query or the +variable. In the following example, the `[wmisearcher]` type accelerator is +used to cast the variable. The result is the same. + +```powershell +[wmisearcher]$bios = "SELECT * FROM Win32_BIOS" +$bios.Get() +``` + +```output +SMBIOSBIOSVersion : S03KT39A +Manufacturer : LENOVO +Name : S03KT39A +SerialNumber : MJ0AETTX +Version : LENOVO - 1270 +``` + +When you use the `[wmisearcher]` type accelerator, it changes the query string +into a **ManagementObjectSearcher** object, as shown in the following commands. + +```powershell +$a = "SELECT * FROM Win32_BIOS" +$a.GetType().FullName +System.String + +$a = [wmisearcher]"SELECT * FROM Win32_BIOS" +$a.GetType().FullName +System.Management.ManagementObjectSearcher +``` + +This command format works on any query. The following command gets the value +of the **Name** property of the **Win32_BIOS** WMI class. + +```powershell +$biosName = [wmisearcher]"Select Name from Win32_BIOS" +$biosName.Get() +``` + +```output +__GENUS : 2 +__CLASS : Win32_BIOS +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 +__DERIVATION : {} +__SERVER : +__NAMESPACE : +__PATH : +Name : S03KT39A +PSComputerName : +``` + +## Using the basic WQL WHERE statement + +A `WHERE` statement establishes conditions for the data that a `SELECT` +statement returns. + +The `WHERE` statement has the following format: + +``` +WHERE +``` + +For example: + +``` +WHERE Name = 'Notepad.exe' +``` + +The `WHERE` statement is used with the `SELECT` statement, as shown in the +following example. + +``` +SELECT * FROM Win32_Process WHERE Name = 'Notepad.exe' +``` + +When using the `WHERE` statement, the property name and value must be accurate. + +For example, the following command gets the Notepad processes on the local +computer. + +```powershell +Get-WmiObject -Query "SELECT * FROM Win32_Process WHERE name='Notepad.exe'" +``` + +However, the following command fails, because the process name includes the +`.exe` file extension. + +```powershell +Get-WmiObject -Query "SELECT * FROM Win32_Process WHERE name='Notepad'" +``` + +## WHERE statement comparison operators + +The following operators are valid in a WQL `WHERE` statement. + +``` +Operator Description +----------------------- += Equal +!= Not equal +<> Not equal +< Less than +> Greater than +<= Less than or equal +>= Greater than or equal +LIKE Wildcard match +IS Evaluates null +ISNOT Evaluates not null +ISA Evaluates a member of a WMI class +``` + +There are other operators, but these are the ones used for making comparisons. + +For example, the following query selects the **Name** and **Priority** +properties from processes in the **Win32_Process** class where the process +priority is greater than or equal to 11. The `Get-WmiObject` cmdlet runs the +query. + +```powershell +$highPriority = "Select Name, Priority from Win32_Process " + + "WHERE Priority >= 11" +Get-WmiObject -Query $highPriority +``` + +## Using the WQL operators in the -Filter parameter + +The WQL operators can also be used in the value of the **Filter** parameter of +the `Get-WmiObject` or `Get-CimInstance` cmdlets, as well as in the value of +the **Query** parameters of these cmdlets. + +For example, the following command gets the **Name** and **ProcessId** +properties of the last five processes that have **ProcessId** values greater +than 1004. The command uses the **Filter** parameter to specify the +**ProcessId** condition. + +```powershell +$getWmiObjectSplat = @{ + Class = 'Win32_Process' + Property = 'Name', 'ProcessId' + Filter = "ProcessId >= 1004" +} +Get-WmiObject @getWmiObjectSplat | + Sort-Object ProcessId | + Select-Object Name, ProcessId -Last 5 +``` + +```output +Name ProcessId +---- --------- +SROSVC.exe 4220 +WINWORD.EXE 4664 +TscHelp.exe 4744 +SnagIt32.exe 4748 +WmiPrvSE.exe 5056 +``` + +## Using the LIKE operator + +The `LIKE` operator lets you use wildcard characters to filter the results of a +WQL query. + +``` +Like Operator Description +-------------------------------------------------- +[] Character in a range [a-f] or a set + of characters [abcdef]. The items in + a set don't need to be consecutive or + listed in alphabetical order. + +^ Character not in a range [^a-f] or + not in a set [^abcdef]. The items in + a set don't need to be consecutive or + listed in alphabetical order. + +% A string of zero or more characters + +_ One character. +(underscore) NOTE: To use a literal underscore + in a query string, enclose it in + square brackets [_]. +``` + +When the `LIKE` operator is used without any wildcard characters or range +operators, it behaves like the equality operator (`=`) and returns objects only +when they're an exact match for the pattern. + +You can combine the range operation with the percent (`%`) wildcard character +to create simple, yet powerful filters. + +### LIKE operator examples + +#### Example 1: [\] + +The following commands start Notepad and then search for an instance of the +**Win32_Process** class that has a name that starts with a letter between "H" +and "N" (case-insensitive). + +The query should return any process from `Hotepad.exe` through `Notepad.exe`. + +```powershell +Notepad # Starts Notepad +$query = "SELECT * FROM Win32_Process WHERE Name LIKE '[H-N]otepad.exe'" +Get-WmiObject -Query $query | select Name, ProcessId +``` + +```output +Name ProcessId +---- --------- +notepad.exe 1740 +``` + +#### Example 2: [\] and % + +The following commands select all process that have a name that begins with a +letter between A and P (case-insensitive) followed by zero or more letters in +any combination. + +The `Get-WmiObject` cmdlet runs the query, the `Select-Object` cmdlet gets the +**Name** and **ProcessId** properties, and the `Sort-Object` cmdlet sorts the +results in alphabetical order by name. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE name LIKE '[A-P]%'" +Get-WmiObject -Query $query | + Select-Object -Property Name, ProcessId | + Sort-Object -Property Name +``` + +#### Example 3: Not in Range (^) + +The following command gets processes whose names don't begin with any of the +following letters: A, S, W, P, R, C, U, N + +and followed zero or more letters. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE name LIKE '[^ASWPRCUN]%'" +Get-WmiObject -Query $query | + Select-Object -Property Name, ProcessId | + Sort-Object -Property Name +``` + +#### Example 4: Any characters -- or none (%) + +The following commands get processes that have names that begin with `calc`. +The percent (`%`) symbol is the WQL wildcard character. It's equivalent to the +asterisk (`*`) wildcard in PowerShell. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE Name LIKE 'calc%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessId +``` + +```output +Name ProcessId +---- --------- +calc.exe 4424 +``` + +#### Example 5: One character (_) + +The following commands get processes that have names that have the following +pattern, `c_lc.exe` where the underscore character represents any one +character. This pattern matches any name from `calc.exe` through `czlc.exe`, or +`c9lc.exe`, but doesn't match names in which the "c" and "l" are separated by +more than one character. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE Name LIKE 'c_lc.exe'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessId +``` + +```output +Name ProcessId +---- --------- +calc.exe 4424 +``` + +#### Example 6: Exact match + +The following commands get processes named `WLIDSVC.exe`. Even though the query +uses the `LIKE` keyword, it requires an exact match, because the value doesn't +include any wildcard characters. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE name LIKE 'WLIDSVC.exe'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessId +```powershell + +```output +Name ProcessId +---- --------- +WLIDSVC.exe 84 +``` + +## Using the OR operator + +To specify multiple independent conditions, use the `OR` keyword. The `OR` +keyword appears in the `WHERE` clause. It performs an inclusive `OR` operation +on two (or more) conditions and returns items that meet any of the conditions. + +The `OR` operator has the following format: + +``` +WHERE OR ... +``` + +For example, the following commands get all instances of the **Win32_Process** +WMI class but returns them only if the process name is `winword.exe` or +`excel.exe`. + +```powershell +$q = "SELECT * FROM Win32_Process WHERE Name='winword.exe'" + + " OR Name='excel.exe'" +Get-WmiObject -Query $q +``` + +The `OR` statement can be used with more than two conditions. In the following +query, the `OR` statement gets `Winword.exe`, `Excel.exe`, or `powershell.exe`. + +```powershell +$q = "SELECT * FROM Win32_Process WHERE Name='winword.exe'" + + " OR Name='excel.exe' OR Name='powershell.exe'" +``` + +## Using the AND operator + +To specify multiple related conditions, use the `AND` keyword. The `AND` +keyword appears in the `WHERE` clause. It returns items that meet all the +conditions. + +The `AND` operator has the following format: + +``` +WHERE `AND` ... +``` + +For example, the following commands get processes that have a name of +`Winword.exe` and the process ID of 6512. + +Note that the commands use the `Get-CimInstance` cmdlet. + +```powershell +$q = "SELECT * FROM Win32_Process WHERE Name = 'winword.exe' " + + "AND ProcessId =6512" +Get-CimInstance -Query $q +``` + +```output +ProcessId Name HandleCount WorkingSetSize VirtualSize +--------- ---- ----------- -------------- ----------- +# 6512 WINWORD.EXE 768 117170176 633028608 +``` + +All operators, including the `LIKE` operators are valid with the `OR` and `AND` +operators. And, you can combine the `OR` and `AND` operators in a single query +with parentheses that tell WMI which clauses to process first. + +This command uses the Windows PowerShell continuation character (`` ` ``) +divide the command into two lines. + +## Searching for null values + +Searching for null values in WMI is challenging, because it can lead to +unpredictable results. `Null` isn't zero and it isn't equivalent to an empty +string. Some WMI class properties are initialized and others aren't, so a +search for null might not work for all properties. + +To search for null values, use the Is operator with a value of `null`. + +For example, the following commands get processes that have a null value for +the **IntallDate** property. The commands return many processes. + +```powershell +$q = "SELECT * FROM Win32_Process WHERE InstallDate is null" +Get-WmiObject -Query $q +``` + +In contrast, the following command, gets user accounts that have a null value +for the **Description** property. This command doesn't return any user +accounts, even though most user accounts don't have any value for the +**Description** property. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Description is null" +Get-WmiObject -Query $q +``` + +To find the user accounts that have no value for the **Description** property, +use the equality operator to get an empty string. To represent the empty +string, use two consecutive single quotation marks. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Description = '' " +``` + +## Using true or false + +To get boolean values in the properties of WMI objects, use `True` and `False`. +They aren't case sensitive. + +The following WQL query returns only local user accounts from a domain joined +computer. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE LocalAccount = True" +Get-CimInstance -Query $q +``` + +To find domain accounts, use a value of False, as shown in the following +example. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE LocalAccount = False" +Get-CimInstance -Query $q +``` + +## Using the escape character + +WQL uses the backslash (`\`) as its escape character. This is different from +Windows PowerShell, which uses the backtick character (`` ` ``). + +Quotation marks, and the characters used for quotation marks, often need to be +escaped so that they aren't misinterpreted. + +To find a user whose name includes a single quotation mark, use a backslash to +escape the single quotation mark, as shown in the following command. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Name = 'Tim O\'Brian'" +Get-CimInstance -Query $q +``` + +```output +Name Caption AccountType SID Domain +---- ------- ----------- --- ------ +Tim O'Brian FABRIKAM\TimO 512 S-1-5-21-1457... FABRIKAM +``` + +In some case, the backslash also needs to be escaped. For example, the +following commands generate an Invalid Query error due to the backslash in the +Caption value. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Caption = 'Fabrikam\TimO'" +Get-CimInstance -Query $q +``` + +```output +Get-CimInstance : Invalid query +At line:1 char:1 ++ Get-CimInstance -Query $q ++ ~~~~~~~~~~~ + + CategoryInfo : InvalidArgument: (:) [Get-CimInstance], CimExcep + + FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastr +``` + +To escape the backslash, use a second backslash character, as shown in the +following command. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Caption = 'Fabrikam\\TimO'" +Get-CimInstance -Query $q +``` + +## See also + +- [about_Special_Characters][02] +- [about_Quoting_Rules][01] +- [about_WMI][04] + + +[01]: about_Quoting_Rules.md +[02]: about_Special_Characters.md +[04]: about_WMI.md diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Logical_Operators.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Logical_Operators.md index 6a014362791..d9f48e19923 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Logical_Operators.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Logical_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that connect statements in PowerShell. Locale: en-US -ms.date: 08/29/2022 +ms.date: 12/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_logical_operators?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Logical_Operators @@ -17,10 +17,35 @@ Describes the operators that connect statements in PowerShell. The PowerShell logical operators connect expressions and statements, allowing you to use a single expression to test for multiple conditions. -For example, the following statement uses the and operator and the or operator -to connect three conditional statements. The statement is true only when the -value of $a is greater than the value of $b, and either $a or $b is less than -20. +Statements that use the logical operators return boolean (TRUE or FALSE) +values. + +The PowerShell logical operators evaluate only the statements required to +determine the truth value of the statement. If the left operand in a statement +that contains the `-and` operator is FALSE, the right operand isn't evaluated. +If the left operand in a statement that contains the `-or` statement is TRUE, +the right operand isn't evaluated. As a result, you can use these statements in +the same way that you would use the `if` statement. + +> [!IMPORTANT] +> The `-and`, `-or` and `-xor` operators have equal precedence. They are +> evaluated from left to right as they appear within the expression. For more +> information, see [about_Operator_Precedence][01]. + +## Syntax + +The syntax of the logical operators is as follows: + +```Syntax + {-and | -or | -xor} +{! | -not} +``` + +## Examples + +The following example uses the `-and` and `-or` operators to connect three +conditional statements. The result is TRUE only when the value of `$a` is +greater than the value of `$b`, and either `$a` or `$b` is less than `20`. ```powershell ($a -gt $b) -and (($a -lt 20) -or ($b -lt 20)) @@ -46,38 +71,29 @@ PowerShell supports the following logical operators. (1 -eq 1) -xor (2 -eq 2) # Result is False ``` -- Logical not (`-not`) or (`!`) - Negates the statement that follows. +- Logical NOT (`-not`) or (`!`) - Negates the statement that follows. ```powershell -not (1 -eq 1) # Result is False !(1 -eq 1) # Result is False ``` -The previous examples also use the equal to comparison operator `-eq`. For more -information, see [about_Comparison_Operators](about_Comparison_Operators.md). -The examples also use the Boolean values of integers. The integer 0 has a value -of FALSE. All other integers have a value of TRUE. - -The syntax of the logical operators is as follows: - -```Syntax - {-and | -or | -xor} -{! | -not} -``` - -Statements that use the logical operators return Boolean (TRUE or FALSE) -values. - -The PowerShell logical operators evaluate only the statements required to -determine the truth value of the statement. If the left operand in a statement -that contains the and operator is FALSE, the right operand isn't evaluated. If -the left operand in a statement that contains the or statement is TRUE, the -right operand isn't evaluated. As a result, you can use these statements in -the same way that you would use the `if` statement. +The previous examples also use the equality comparison operator, `-eq`. For +more information, see [about_Comparison_Operators][03]. The examples also use +the boolean values of integers. The integer `0` has a boolean value of FALSE. +All other integers have a value of TRUE. ## See also -- [about_Operators](about_Operators.md) -- [about_Comparison_operators](about_Comparison_Operators.md) -- [about_If](about_If.md) -- [Compare-Object](xref:Microsoft.PowerShell.Utility.Compare-Object) +- [about_Operators][02] +- [about_Operator_Precedence][01] +- [about_Comparison_Operators][03] +- [about_If][04] +- [Compare-Object][05] + + +[01]: about_Operator_Precedence.md +[02]: about_Operators.md +[03]: about_Comparison_Operators.md +[04]: about_If.md +[05]: xref:Microsoft.PowerShell.Utility.Compare-Object diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 76a9e5b7291..0948b5fe24d 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -1,7 +1,7 @@ --- description: Lists the PowerShell operators in precedence order. Locale: en-US -ms.date: 06/29/2021 +ms.date: 12/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operator_precedence?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Operator_Precedence @@ -33,8 +33,8 @@ evaluated. Operators on the same line, or in the same group, have equal precedence. The Operator column lists the operators. The Reference column lists the -PowerShell Help topic in which the operator is described. To display the topic, -type `Get-Help `. +PowerShell Help topic in which the operator is described. To display the topic +interactively, use `Get-Help -Name `. | OPERATOR | REFERENCE | | --------------------------- | ------------------------------------ | @@ -85,8 +85,8 @@ that happens. | ------------------------------------------------------- | ------------------------------------ | | `.` (dot-source) | [about_Operators][ops] | | `&` (call) | [about_Operators][ops] | -| `? : ` (Ternary operator) | [about_Operators][ops] | -| `??` (null-coalese operator) | [about_Operators][ops] | +| `? : ` (ternary operator) | [about_Operators][ops] | +| `??` (null-coalescing operator) | [about_Operators][ops] | | | (pipeline operator) | [about_Operators][ops] | | `> >> 2> 2>> 2>&1` | [about_Redirection][redir] | | && || (pipeline chain operators) | [about_Operators][ops] | @@ -94,7 +94,7 @@ that happens. ## Examples -The following two commands show the arithmetic operators and the effect of +The following two examples show the arithmetic operators and the effect of using parentheses to force PowerShell to evaluate the enclosed part of the expression first. @@ -107,28 +107,28 @@ PS> (2 + 3) * 4 ``` The following example gets the read-only text files from the local directory -and saves them in the `$read_only` variable. +and saves them in the `$readOnly` variable. ```powershell -$read_only = Get-ChildItem *.txt | Where-Object {$_.IsReadOnly} +$readOnly = Get-ChildItem -Path *.txt | Where-Object { $_.IsReadOnly } ``` It is equivalent to the following example. ```powershell -$read_only = ( Get-ChildItem *.txt | Where-Object {$_.IsReadOnly} ) +$readOnly = (Get-ChildItem -Path *.txt | Where-Object { $_.IsReadOnly }) ``` Because the pipeline operator (`|`) has a higher precedence than the assignment operator (`=`), the files that the `Get-ChildItem` cmdlet gets are sent to the `Where-Object` cmdlet for filtering before they are assigned to the -`$read_only` variable. +`$readOnly` variable. The following example demonstrates that the index operator takes precedence over the cast operator. This expression creates an array of three strings. Then, it uses the index -operator with a value of 0 to select the first object in the array, which is +operator with a value of `0` to select the first object in the array, which is the first string. Finally, it casts the selected object as a string. In this case, the cast has no effect. @@ -163,7 +163,7 @@ PS> (2 -gt 4) -and 1 False ``` -If the -and operator had higher precedence, the answer would be TRUE. +If the `-and` operator had higher precedence, the result would be TRUE. ```powershell PS> 2 -gt (4 -and 1) @@ -176,6 +176,27 @@ parentheses to force the evaluation order, even when it forces the default operator precedence. The parentheses make your intentions clear to people who are reading and maintaining your scripts. +The following example demonstrates the precedence between the `-and` and `-or` +logical operators. + +```powershell +PS> $true -or $false -and $false +False +``` + +In other languages such as C#, logical AND typically has a higher precedence +than logical OR, so you may expect the above expression to yield TRUE. + +However, the `-and` and `-or` operators have equal precedence in PowerShell. +They are evaluated from the left to right as they appear within the expression. +As `$true -or $false` is TRUE and `$true -and $false` is FALSE, the result of +the expression is FALSE. + +> [!IMPORTANT] +> Other contexts within PowerShell such as [WMI Query Language (WQL)][wql] and +> the Active Directory filter have their own operator precedence that might +> differ from PowerShell logical operator precedence. + ## See also - [about_Operators][ops] @@ -189,7 +210,7 @@ are reading and maintaining your scripts. - [about_Split][split] - [about_Type_Operators][type] - + [math]: about_Arithmetic_Operators.md [assign]: about_Assignment_Operators.md [compare]: about_Comparison_Operators.md @@ -200,3 +221,4 @@ are reading and maintaining your scripts. [scopes]: about_Scopes.md [split]: about_Split.md [type]: about_Type_Operators.md +[wql]: about_WQL.md diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_WMI.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_WMI.md new file mode 100644 index 00000000000..7e54a026935 --- /dev/null +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_WMI.md @@ -0,0 +1,110 @@ +--- +description: Windows Management Instrumentation (WMI) uses the Common Information Model (CIM) to represent systems, applications, networks, devices, and other manageable components of the modern enterprise. +Locale: en-US +ms.date: 01/03/2018 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_wmi?view=powershell-7.5&WT.mc_id=ps-gethelp +schema: 2.0.0 +title: about_WMI +--- + +# about_WMI + +## Short description + +Windows Management Instrumentation (WMI) uses the Common Information Model +(CIM) to represent systems, applications, networks, devices, and other +manageable components of the modern enterprise. + +## Long description + +Windows Management Instrumentation (WMI) is Microsoft's implementation of +Web-Based Enterprise Management (WBEM), the industry standard. + +Classic WMI uses DCOM to communicate with networked devices to manage remote +systems. Windows PowerShell 3.0 introduces a CIM provider model that uses WinRM +to remove the dependency on DCOM. This CIM provider model also uses new WMI +provider APIs that enable developers to write Windows PowerShell cmdlets in +native code (C++). + +Don't confuse WMI providers with Windows PowerShell providers. Many Windows +features have an associated WMI provider that exposes their management +capabilities. To get WMI providers, run a WMI query that gets instances of the +**__Provider** WMI class, such as the following query. + +```powershell +Get-WmiObject -Class __Provider +``` + +## Three components of WMI + +The following three components of WMI interact with Windows PowerShell: +Namespaces, Providers, and Classes. + +WMI Namespaces organize WMI providers and WMI classes into groups of related +components. In this way, they're similar to .NET Framework namespaces. +Namespaces aren't physical locations, but are more like logical databases. All +WMI namespaces are instances of the __Namespace system class. The default WMI +namespace is **root/CIMV2** (since Microsoft Windows 2000). To use Windows +PowerShell to get WMI namespaces in the current session, use a command with the +following format. + +```powershell +Get-WmiObject -Class __Namespace +``` + +To get WMI namespaces in other namespaces, use the Namespace parameter to +change the location of the search. The following command finds WMI namespaces +that reside in the **root/CIMV2/Applications** namespace. + +```powershell +Get-WmiObject -Class __Namespace -Namespace root/CIMV2/Applications +``` + +WMI namespaces are hierarchical. Therefore, obtaining a list of all namespaces +on a particular system requires performing a recursive query starting at the +root namespace. + +WMI Providers expose information about Windows manageable objects. A provider +retrieves data from a component, and passes that data through WMI to a +management application, such as Windows PowerShell. Most WMI providers are +dynamic providers, which means that they obtain the data dynamically when it's +requested through the management application. + +## Finding WMI classes + +In a default Windows 8 installation, there are more than 1,100 WMI classes in +**root/CIMV2**. With this many WMI classes, the challenge becomes identifying +the appropriate WMI class to use to perform a specific task. Windows PowerShell +3.0 provides two ways to find WMI classes that are related to a specific topic. + +For example, to find WMI classes in the **root/CIMV2** WMI namespace that are +related to disks, you can use a query such as the one shown here. + +```powershell +Get-WmiObject -List *Disk* +``` + +To find WMI classes that are related to memory, you might use a query such as +the one shown here. + +```powershell +Get-WmiObject -List *Memory* +``` + +The CIM cmdlets also provide the ability to discover WMI classes. To do this, +use the `Get-CimClass` cmdlet. The command shown here lists WMI classes related +to video. + +```powershell +Get-CimClass *Video* +``` + +Tab expansion works when changing WMI namespaces, and therefore use of tab +expansion makes sub-WMI namespaces easily discoverable. In the following +example, the `Get-CimClass` cmdlet lists WMI classes related to power settings. +To find it, type the **root/CIMV2** namespace and then press the Tab key +several times until the **power** namespace appears. Here is the command: + +```powershell +Get-CimClass *Power* -Namespace root/CIMV2/power +``` diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_WQL.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_WQL.md new file mode 100644 index 00000000000..365fbe9eb77 --- /dev/null +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_WQL.md @@ -0,0 +1,719 @@ +--- +description: Describes WMI Query Language (WQL), which can be used to get WMI objects in Windows PowerShell. +Locale: en-US +ms.date: 01/06/2026 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_wql?view=powershell-7.5&WT.mc_id=ps-gethelp +schema: 2.0.0 +title: about_WQL +--- + +# about_WQL + +## Short description + +Describes WMI Query Language (WQL), which can be used to get WMI objects in +Windows PowerShell. + +## Long description + +WQL is the Windows Management Instrumentation (WMI) query language, which is +the language used to get information from WMI. + +You aren't required to use WQL to perform a WMI query in Windows PowerShell. +Instead, you can use the parameters of the `Get-WmiObject` or `Get-CimInstance` +cmdlets. WQL queries are somewhat faster than standard `Get-WmiObject` commands +and the improved performance is evident when the commands run on hundreds of +systems. However, be sure that the time you spend to write a successful WQL +query doesn't outweigh the performance improvement. + +The basic WQL statements you need to use WQL are `SELECT`, `WHERE`, and `FROM`. + +## When to use WQL + +When working with WMI, and especially with WQL, don't forget that you are +also using Windows PowerShell. Often, if a WQL query doesn't work as +expected, it's easier to use a standard Windows PowerShell command than to +debug the WQL query. + +Unless you are returning massive amounts of data from across +bandwidth-constrained remote systems, it's rarely productive to spend hours +trying to perfect a complicated WQL query when there is an acceptable +PowerShell cmdlet that does the same thing. + +## Using the SELECT statement + +A typical WMI query begins with a `SELECT` statement that gets all properties +or particular properties of a WMI class. To select all properties of a WMI +class, use an asterisk (`*`). The `FROM` keyword specifies the WMI class. + +A `SELECT` statement has the following format: + +``` +SELECT FROM +``` + +For example, the following `SELECT` statement selects all properties (`*`) from +the instances of the **Win32_BIOS** WMI class. + +``` +SELECT * FROM Win32_BIOS +``` + +> [!NOTE] +> PowerShell only displays the default object properties. These properties are +> defined in the `Types.ps1xml` file. Use the `Select-Object` cmdlet or a +> `Format-*` cmdlet to display additional properties. + +To select a particular property of a WMI class, place the property name +between the `SELECT` and `FROM` keywords. + +The following query selects only the name of the BIOS from the **Win32_BIOS** +WMI class. The command saves the query in the `$queryName` variable. + +``` +SELECT Name FROM Win32_BIOS +``` + +To select more than one property, use commas to separate the property names. +The following WMI query selects the name and the version of the **Win32_BIOS** +WMI class. The command saves the query in the `$queryNameVersion` variable. + +```WQL +SELECT name, version FROM Win32_BIOS +``` + +## Using the WQL query + +There are three ways to use WQL query in Windows PowerShell command. + +- Use the `Get-WmiObject` cmdlet +- Use the `Get-CimInstance` cmdlet +- Use the `[wmisearcher]` type accelerator. + +## Using the Get-WmiObject cmdlet + +The most basic way to use the WQL query is to enclose it in quotation marks (as +a string) and then use the query string as the value of the **Query** parameter +of the `Get-WmiObject` cmdlet, as shown in the following example. + +```powershell +Get-WmiObject -Query "SELECT * FROM Win32_BIOS" +``` + +```output +SMBIOSBIOSVersion : 8BET56WW (1.36 ) +Manufacturer : LENOVO +Name : Default System BIOS +SerialNumber : R9FPY3P +Version : LENOVO - 1360 +``` + +You can also save the WQL statement in a variable and then use the variable as +the value of the **Query** parameter, as shown in the following command. + +```powershell +$query = "SELECT * FROM Win32_BIOS" +Get-WmiObject -Query $query +``` + +You can use either format with any WQL statement. The following command uses +the query in the `$queryName` variable to get only the **Name** and **Version** +properties of the system BIOS. + +```powershell +$queryNameVersion = "SELECT Name, Version FROM Win32_BIOS" +Get-WmiObject -Query $queryNameVersion +``` + +```output +__GENUS : 2 +__CLASS : Win32_BIOS +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 2 +__DERIVATION : {} +__SERVER : +__NAMESPACE : +__PATH : +Name : S03KT39A +Version : LENOVO - 1270 +PSComputerName : +``` + +Remember that you can use the parameters of the `Get-WmiObject` cmdlet to get +the same result. For example, the following command also gets the values of the +**Name** and **Version** properties of instances of the **Win32_BIOS** WMI +class. + +```powershell +Get-WmiObject -Class Win32_BIOS -Property Name, Version +``` + +```output +__GENUS : 2 +__CLASS : Win32_BIOS +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 2 +__DERIVATION : {} +__SERVER : +__NAMESPACE : +__PATH : +Name : S03KT39A +Version : LENOVO - 1270 +PSComputerName : +``` + +## Using the Get-CimInstance cmdlet + +Beginning in Windows PowerShell 3.0, you can use the `Get-CimInstance` cmdlet +to run WQL queries. + +`Get-CimInstance` gets instances of CIM-compliant classes, including WMI +classes. The CIM cmdlets, introduced Windows PowerShell 3.0, perform the same +tasks as the WMI cmdlets. The CIM cmdlets comply with WS-Management (WSMan) +standards and with the Common Information Model (CIM) standard, which enables +the cmdlets to use the same techniques to manage Windows computers and +computers that are running other operating systems. + +The following command uses the `Get-CimInstance` cmdlet to run a WQL query. + +Any WQL query that can be used with `Get-WmiObject` can also be used with +`Get-CimInstance`. + +```powershell +Get-CimInstance -Query "SELECT * FROM Win32_BIOS" +``` + +```output +SMBIOSBIOSVersion : S03KT39A +Manufacturer : LENOVO +Name : S03KT39A +SerialNumber : MJ0AETTX +Version : LENOVO - 1270 +``` + +`Get-CimInstance` returns a **CimInstance** object, instead of the +**ManagementObject** that `Get-WmiObject` returns, but the objects are quite +similar. + +```powershell +PS> (Get-CimInstance -Query "SELECT * FROM Win32_BIOS").GetType().FullName +Microsoft.Management.Infrastructure.CimInstance + +PS> (Get-WmiObject -Query "SELECT * FROM Win32_BIOS").GetType().FullName +System.Management.ManagementObject +``` + +## Using the wmisearcher type accelerator + +The `[wmisearcher]` type accelerator creates a **ManagementObjectSearcher** +object from a WQL statement string. The **ManagementObjectSearcher** object has +many properties and methods, but the most basic method is the Get method, which +invokes the specified WMI query and returns the resulting objects. + +Using `[wmisearcher]`, you gain easy access to the **ManagementObjectSearcher** +.NET class. This lets you query WMI and to configure the way the query is +conducted. + +To use the `[wmisearcher]` type accelerator: + +1. Cast the WQL string into a **ManagementObjectSearcher** object. +1. Call the Get method of the **ManagementObjectSearcher** object. + +For example, the following command casts the "select all" query, saves the +result in the `$bios` variable, and then calls the `Get()` method of the +**ManagementObjectSearcher** object in the `$bios` variable. + +```powershell +$bios = [wmisearcher]"SELECT * FROM Win32_BIOS" +$bios.Get() +``` + +```output +SMBIOSBIOSVersion : 8BET56WW (1.36 ) +Manufacturer : LENOVO +Name : Default System BIOS +SerialNumber : R9FPY3P +Version : LENOVO - 1360 +``` + +You can use the `[wmisearcher]` type accelerator to cast the query or the +variable. In the following example, the `[wmisearcher]` type accelerator is +used to cast the variable. The result is the same. + +```powershell +[wmisearcher]$bios = "SELECT * FROM Win32_BIOS" +$bios.Get() +``` + +```output +SMBIOSBIOSVersion : S03KT39A +Manufacturer : LENOVO +Name : S03KT39A +SerialNumber : MJ0AETTX +Version : LENOVO - 1270 +``` + +When you use the `[wmisearcher]` type accelerator, it changes the query string +into a **ManagementObjectSearcher** object, as shown in the following commands. + +```powershell +$a = "SELECT * FROM Win32_BIOS" +$a.GetType().FullName +System.String + +$a = [wmisearcher]"SELECT * FROM Win32_BIOS" +$a.GetType().FullName +System.Management.ManagementObjectSearcher +``` + +This command format works on any query. The following command gets the value +of the **Name** property of the **Win32_BIOS** WMI class. + +```powershell +$biosName = [wmisearcher]"Select Name from Win32_BIOS" +$biosName.Get() +``` + +```output +__GENUS : 2 +__CLASS : Win32_BIOS +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 +__DERIVATION : {} +__SERVER : +__NAMESPACE : +__PATH : +Name : S03KT39A +PSComputerName : +``` + +## Using the basic WQL WHERE statement + +A `WHERE` statement establishes conditions for the data that a `SELECT` +statement returns. + +The `WHERE` statement has the following format: + +``` +WHERE +``` + +For example: + +``` +WHERE Name = 'Notepad.exe' +``` + +The `WHERE` statement is used with the `SELECT` statement, as shown in the +following example. + +``` +SELECT * FROM Win32_Process WHERE Name = 'Notepad.exe' +``` + +When using the `WHERE` statement, the property name and value must be accurate. + +For example, the following command gets the Notepad processes on the local +computer. + +```powershell +Get-WmiObject -Query "SELECT * FROM Win32_Process WHERE name='Notepad.exe'" +``` + +However, the following command fails, because the process name includes the +`.exe` file extension. + +```powershell +Get-WmiObject -Query "SELECT * FROM Win32_Process WHERE name='Notepad'" +``` + +## WHERE statement comparison operators + +The following operators are valid in a WQL `WHERE` statement. + +``` +Operator Description +----------------------- += Equal +!= Not equal +<> Not equal +< Less than +> Greater than +<= Less than or equal +>= Greater than or equal +LIKE Wildcard match +IS Evaluates null +ISNOT Evaluates not null +ISA Evaluates a member of a WMI class +``` + +There are other operators, but these are the ones used for making comparisons. + +For example, the following query selects the **Name** and **Priority** +properties from processes in the **Win32_Process** class where the process +priority is greater than or equal to 11. The `Get-WmiObject` cmdlet runs the +query. + +```powershell +$highPriority = "Select Name, Priority from Win32_Process " + + "WHERE Priority >= 11" +Get-WmiObject -Query $highPriority +``` + +## Using the WQL operators in the -Filter parameter + +The WQL operators can also be used in the value of the **Filter** parameter of +the `Get-WmiObject` or `Get-CimInstance` cmdlets, as well as in the value of +the **Query** parameters of these cmdlets. + +For example, the following command gets the **Name** and **ProcessId** +properties of the last five processes that have **ProcessId** values greater +than 1004. The command uses the **Filter** parameter to specify the +**ProcessId** condition. + +```powershell +$getWmiObjectSplat = @{ + Class = 'Win32_Process' + Property = 'Name', 'ProcessId' + Filter = "ProcessId >= 1004" +} +Get-WmiObject @getWmiObjectSplat | + Sort-Object ProcessId | + Select-Object Name, ProcessId -Last 5 +``` + +```output +Name ProcessId +---- --------- +SROSVC.exe 4220 +WINWORD.EXE 4664 +TscHelp.exe 4744 +SnagIt32.exe 4748 +WmiPrvSE.exe 5056 +``` + +## Using the LIKE operator + +The `LIKE` operator lets you use wildcard characters to filter the results of a +WQL query. + +``` +Like Operator Description +-------------------------------------------------- +[] Character in a range [a-f] or a set + of characters [abcdef]. The items in + a set don't need to be consecutive or + listed in alphabetical order. + +^ Character not in a range [^a-f] or + not in a set [^abcdef]. The items in + a set don't need to be consecutive or + listed in alphabetical order. + +% A string of zero or more characters + +_ One character. +(underscore) NOTE: To use a literal underscore + in a query string, enclose it in + square brackets [_]. +``` + +When the `LIKE` operator is used without any wildcard characters or range +operators, it behaves like the equality operator (`=`) and returns objects only +when they're an exact match for the pattern. + +You can combine the range operation with the percent (`%`) wildcard character +to create simple, yet powerful filters. + +### LIKE operator examples + +#### Example 1: [\] + +The following commands start Notepad and then search for an instance of the +**Win32_Process** class that has a name that starts with a letter between "H" +and "N" (case-insensitive). + +The query should return any process from `Hotepad.exe` through `Notepad.exe`. + +```powershell +Notepad # Starts Notepad +$query = "SELECT * FROM Win32_Process WHERE Name LIKE '[H-N]otepad.exe'" +Get-WmiObject -Query $query | select Name, ProcessId +``` + +```output +Name ProcessId +---- --------- +notepad.exe 1740 +``` + +#### Example 2: [\] and % + +The following commands select all process that have a name that begins with a +letter between A and P (case-insensitive) followed by zero or more letters in +any combination. + +The `Get-WmiObject` cmdlet runs the query, the `Select-Object` cmdlet gets the +**Name** and **ProcessId** properties, and the `Sort-Object` cmdlet sorts the +results in alphabetical order by name. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE name LIKE '[A-P]%'" +Get-WmiObject -Query $query | + Select-Object -Property Name, ProcessId | + Sort-Object -Property Name +``` + +#### Example 3: Not in Range (^) + +The following command gets processes whose names don't begin with any of the +following letters: A, S, W, P, R, C, U, N + +and followed zero or more letters. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE name LIKE '[^ASWPRCUN]%'" +Get-WmiObject -Query $query | + Select-Object -Property Name, ProcessId | + Sort-Object -Property Name +``` + +#### Example 4: Any characters -- or none (%) + +The following commands get processes that have names that begin with `calc`. +The percent (`%`) symbol is the WQL wildcard character. It's equivalent to the +asterisk (`*`) wildcard in PowerShell. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE Name LIKE 'calc%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessId +``` + +```output +Name ProcessId +---- --------- +calc.exe 4424 +``` + +#### Example 5: One character (_) + +The following commands get processes that have names that have the following +pattern, `c_lc.exe` where the underscore character represents any one +character. This pattern matches any name from `calc.exe` through `czlc.exe`, or +`c9lc.exe`, but doesn't match names in which the "c" and "l" are separated by +more than one character. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE Name LIKE 'c_lc.exe'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessId +``` + +```output +Name ProcessId +---- --------- +calc.exe 4424 +``` + +#### Example 6: Exact match + +The following commands get processes named `WLIDSVC.exe`. Even though the query +uses the `LIKE` keyword, it requires an exact match, because the value doesn't +include any wildcard characters. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE name LIKE 'WLIDSVC.exe'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessId +```powershell + +```output +Name ProcessId +---- --------- +WLIDSVC.exe 84 +``` + +## Using the OR operator + +To specify multiple independent conditions, use the `OR` keyword. The `OR` +keyword appears in the `WHERE` clause. It performs an inclusive `OR` operation +on two (or more) conditions and returns items that meet any of the conditions. + +The `OR` operator has the following format: + +``` +WHERE OR ... +``` + +For example, the following commands get all instances of the **Win32_Process** +WMI class but returns them only if the process name is `winword.exe` or +`excel.exe`. + +```powershell +$q = "SELECT * FROM Win32_Process WHERE Name='winword.exe'" + + " OR Name='excel.exe'" +Get-WmiObject -Query $q +``` + +The `OR` statement can be used with more than two conditions. In the following +query, the `OR` statement gets `Winword.exe`, `Excel.exe`, or `powershell.exe`. + +```powershell +$q = "SELECT * FROM Win32_Process WHERE Name='winword.exe'" + + " OR Name='excel.exe' OR Name='powershell.exe'" +``` + +## Using the AND operator + +To specify multiple related conditions, use the `AND` keyword. The `AND` +keyword appears in the `WHERE` clause. It returns items that meet all the +conditions. + +The `AND` operator has the following format: + +``` +WHERE `AND` ... +``` + +For example, the following commands get processes that have a name of +`Winword.exe` and the process ID of 6512. + +Note that the commands use the `Get-CimInstance` cmdlet. + +```powershell +$q = "SELECT * FROM Win32_Process WHERE Name = 'winword.exe' " + + "AND ProcessId =6512" +Get-CimInstance -Query $q +``` + +```output +ProcessId Name HandleCount WorkingSetSize VirtualSize +--------- ---- ----------- -------------- ----------- +# 6512 WINWORD.EXE 768 117170176 633028608 +``` + +All operators, including the `LIKE` operators are valid with the `OR` and `AND` +operators. And, you can combine the `OR` and `AND` operators in a single query +with parentheses that tell WMI which clauses to process first. + +This command uses the Windows PowerShell continuation character (`` ` ``) +divide the command into two lines. + +## Searching for null values + +Searching for null values in WMI is challenging, because it can lead to +unpredictable results. `Null` isn't zero and it isn't equivalent to an empty +string. Some WMI class properties are initialized and others aren't, so a +search for null might not work for all properties. + +To search for null values, use the Is operator with a value of `null`. + +For example, the following commands get processes that have a null value for +the **IntallDate** property. The commands return many processes. + +```powershell +$q = "SELECT * FROM Win32_Process WHERE InstallDate is null" +Get-WmiObject -Query $q +``` + +In contrast, the following command, gets user accounts that have a null value +for the **Description** property. This command doesn't return any user +accounts, even though most user accounts don't have any value for the +**Description** property. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Description is null" +Get-WmiObject -Query $q +``` + +To find the user accounts that have no value for the **Description** property, +use the equality operator to get an empty string. To represent the empty +string, use two consecutive single quotation marks. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Description = '' " +``` + +## Using true or false + +To get boolean values in the properties of WMI objects, use `True` and `False`. +They aren't case sensitive. + +The following WQL query returns only local user accounts from a domain joined +computer. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE LocalAccount = True" +Get-CimInstance -Query $q +``` + +To find domain accounts, use a value of False, as shown in the following +example. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE LocalAccount = False" +Get-CimInstance -Query $q +``` + +## Using the escape character + +WQL uses the backslash (`\`) as its escape character. This is different from +Windows PowerShell, which uses the backtick character (`` ` ``). + +Quotation marks, and the characters used for quotation marks, often need to be +escaped so that they aren't misinterpreted. + +To find a user whose name includes a single quotation mark, use a backslash to +escape the single quotation mark, as shown in the following command. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Name = 'Tim O\'Brian'" +Get-CimInstance -Query $q +``` + +```output +Name Caption AccountType SID Domain +---- ------- ----------- --- ------ +Tim O'Brian FABRIKAM\TimO 512 S-1-5-21-1457... FABRIKAM +``` + +In some case, the backslash also needs to be escaped. For example, the +following commands generate an Invalid Query error due to the backslash in the +Caption value. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Caption = 'Fabrikam\TimO'" +Get-CimInstance -Query $q +``` + +```output +Get-CimInstance : Invalid query +At line:1 char:1 ++ Get-CimInstance -Query $q ++ ~~~~~~~~~~~ + + CategoryInfo : InvalidArgument: (:) [Get-CimInstance], CimExcep + + FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastr +``` + +To escape the backslash, use a second backslash character, as shown in the +following command. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Caption = 'Fabrikam\\TimO'" +Get-CimInstance -Query $q +``` + +## See also + +- [about_Special_Characters][02] +- [about_Quoting_Rules][01] +- [about_WMI][04] + + +[01]: about_Quoting_Rules.md +[02]: about_Special_Characters.md +[04]: about_WMI.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Logical_Operators.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Logical_Operators.md index dd3084d4723..af602ba734e 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Logical_Operators.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Logical_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that connect statements in PowerShell. Locale: en-US -ms.date: 08/29/2022 +ms.date: 12/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_logical_operators?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Logical_Operators @@ -17,10 +17,35 @@ Describes the operators that connect statements in PowerShell. The PowerShell logical operators connect expressions and statements, allowing you to use a single expression to test for multiple conditions. -For example, the following statement uses the and operator and the or operator -to connect three conditional statements. The statement is true only when the -value of $a is greater than the value of $b, and either $a or $b is less than -20. +Statements that use the logical operators return boolean (TRUE or FALSE) +values. + +The PowerShell logical operators evaluate only the statements required to +determine the truth value of the statement. If the left operand in a statement +that contains the `-and` operator is FALSE, the right operand isn't evaluated. +If the left operand in a statement that contains the `-or` statement is TRUE, +the right operand isn't evaluated. As a result, you can use these statements in +the same way that you would use the `if` statement. + +> [!IMPORTANT] +> The `-and`, `-or` and `-xor` operators have equal precedence. They are +> evaluated from left to right as they appear within the expression. For more +> information, see [about_Operator_Precedence][01]. + +## Syntax + +The syntax of the logical operators is as follows: + +```Syntax + {-and | -or | -xor} +{! | -not} +``` + +## Examples + +The following example uses the `-and` and `-or` operators to connect three +conditional statements. The result is TRUE only when the value of `$a` is +greater than the value of `$b`, and either `$a` or `$b` is less than `20`. ```powershell ($a -gt $b) -and (($a -lt 20) -or ($b -lt 20)) @@ -46,38 +71,29 @@ PowerShell supports the following logical operators. (1 -eq 1) -xor (2 -eq 2) # Result is False ``` -- Logical not (`-not`) or (`!`) - Negates the statement that follows. +- Logical NOT (`-not`) or (`!`) - Negates the statement that follows. ```powershell -not (1 -eq 1) # Result is False !(1 -eq 1) # Result is False ``` -The previous examples also use the equal to comparison operator `-eq`. For more -information, see [about_Comparison_Operators](about_Comparison_Operators.md). -The examples also use the Boolean values of integers. The integer 0 has a value -of FALSE. All other integers have a value of TRUE. - -The syntax of the logical operators is as follows: - -```Syntax - {-and | -or | -xor} -{! | -not} -``` - -Statements that use the logical operators return Boolean (TRUE or FALSE) -values. - -The PowerShell logical operators evaluate only the statements required to -determine the truth value of the statement. If the left operand in a statement -that contains the and operator is FALSE, the right operand isn't evaluated. If -the left operand in a statement that contains the or statement is TRUE, the -right operand isn't evaluated. As a result, you can use these statements in -the same way that you would use the `if` statement. +The previous examples also use the equality comparison operator, `-eq`. For +more information, see [about_Comparison_Operators][03]. The examples also use +the boolean values of integers. The integer `0` has a boolean value of FALSE. +All other integers have a value of TRUE. ## See also -- [about_Operators](about_Operators.md) -- [about_Comparison_operators](about_Comparison_Operators.md) -- [about_If](about_If.md) -- [Compare-Object](xref:Microsoft.PowerShell.Utility.Compare-Object) +- [about_Operators][02] +- [about_Operator_Precedence][01] +- [about_Comparison_Operators][03] +- [about_If][04] +- [Compare-Object][05] + + +[01]: about_Operator_Precedence.md +[02]: about_Operators.md +[03]: about_Comparison_Operators.md +[04]: about_If.md +[05]: xref:Microsoft.PowerShell.Utility.Compare-Object diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 4e1c51ac2a9..77a80a35ebb 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -1,7 +1,7 @@ --- description: Lists the PowerShell operators in precedence order. Locale: en-US -ms.date: 06/29/2021 +ms.date: 12/30/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operator_precedence?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Operator_Precedence @@ -33,8 +33,8 @@ evaluated. Operators on the same line, or in the same group, have equal precedence. The Operator column lists the operators. The Reference column lists the -PowerShell Help topic in which the operator is described. To display the topic, -type `Get-Help `. +PowerShell Help topic in which the operator is described. To display the topic +interactively, use `Get-Help -Name `. | OPERATOR | REFERENCE | | --------------------------- | ------------------------------------ | @@ -85,8 +85,8 @@ that happens. | ------------------------------------------------------- | ------------------------------------ | | `.` (dot-source) | [about_Operators][ops] | | `&` (call) | [about_Operators][ops] | -| `? : ` (Ternary operator) | [about_Operators][ops] | -| `??` (null-coalese operator) | [about_Operators][ops] | +| `? : ` (ternary operator) | [about_Operators][ops] | +| `??` (null-coalescing operator) | [about_Operators][ops] | | | (pipeline operator) | [about_Operators][ops] | | `> >> 2> 2>> 2>&1` | [about_Redirection][redir] | | && || (pipeline chain operators) | [about_Operators][ops] | @@ -94,7 +94,7 @@ that happens. ## Examples -The following two commands show the arithmetic operators and the effect of +The following two examples show the arithmetic operators and the effect of using parentheses to force PowerShell to evaluate the enclosed part of the expression first. @@ -107,28 +107,28 @@ PS> (2 + 3) * 4 ``` The following example gets the read-only text files from the local directory -and saves them in the `$read_only` variable. +and saves them in the `$readOnly` variable. ```powershell -$read_only = Get-ChildItem *.txt | Where-Object {$_.IsReadOnly} +$readOnly = Get-ChildItem -Path *.txt | Where-Object { $_.IsReadOnly } ``` It is equivalent to the following example. ```powershell -$read_only = ( Get-ChildItem *.txt | Where-Object {$_.IsReadOnly} ) +$readOnly = (Get-ChildItem -Path *.txt | Where-Object { $_.IsReadOnly }) ``` Because the pipeline operator (`|`) has a higher precedence than the assignment operator (`=`), the files that the `Get-ChildItem` cmdlet gets are sent to the `Where-Object` cmdlet for filtering before they are assigned to the -`$read_only` variable. +`$readOnly` variable. The following example demonstrates that the index operator takes precedence over the cast operator. This expression creates an array of three strings. Then, it uses the index -operator with a value of 0 to select the first object in the array, which is +operator with a value of `0` to select the first object in the array, which is the first string. Finally, it casts the selected object as a string. In this case, the cast has no effect. @@ -163,7 +163,7 @@ PS> (2 -gt 4) -and 1 False ``` -If the -and operator had higher precedence, the answer would be TRUE. +If the `-and` operator had higher precedence, the result would be TRUE. ```powershell PS> 2 -gt (4 -and 1) @@ -176,6 +176,27 @@ parentheses to force the evaluation order, even when it forces the default operator precedence. The parentheses make your intentions clear to people who are reading and maintaining your scripts. +The following example demonstrates the precedence between the `-and` and `-or` +logical operators. + +```powershell +PS> $true -or $false -and $false +False +``` + +In other languages such as C#, logical AND typically has a higher precedence +than logical OR, so you may expect the above expression to yield TRUE. + +However, the `-and` and `-or` operators have equal precedence in PowerShell. +They are evaluated from the left to right as they appear within the expression. +As `$true -or $false` is TRUE and `$true -and $false` is FALSE, the result of +the expression is FALSE. + +> [!IMPORTANT] +> Other contexts within PowerShell such as [WMI Query Language (WQL)][wql] and +> the Active Directory filter have their own operator precedence that might +> differ from PowerShell logical operator precedence. + ## See also - [about_Operators][ops] @@ -189,7 +210,7 @@ are reading and maintaining your scripts. - [about_Split][split] - [about_Type_Operators][type] - + [math]: about_Arithmetic_Operators.md [assign]: about_Assignment_Operators.md [compare]: about_Comparison_Operators.md @@ -200,3 +221,4 @@ are reading and maintaining your scripts. [scopes]: about_Scopes.md [split]: about_Split.md [type]: about_Type_Operators.md +[wql]: about_WQL.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_WMI.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_WMI.md new file mode 100644 index 00000000000..0ada683edd2 --- /dev/null +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_WMI.md @@ -0,0 +1,110 @@ +--- +description: Windows Management Instrumentation (WMI) uses the Common Information Model (CIM) to represent systems, applications, networks, devices, and other manageable components of the modern enterprise. +Locale: en-US +ms.date: 01/03/2018 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_wmi?view=powershell-7.6&WT.mc_id=ps-gethelp +schema: 2.0.0 +title: about_WMI +--- + +# about_WMI + +## Short description + +Windows Management Instrumentation (WMI) uses the Common Information Model +(CIM) to represent systems, applications, networks, devices, and other +manageable components of the modern enterprise. + +## Long description + +Windows Management Instrumentation (WMI) is Microsoft's implementation of +Web-Based Enterprise Management (WBEM), the industry standard. + +Classic WMI uses DCOM to communicate with networked devices to manage remote +systems. Windows PowerShell 3.0 introduces a CIM provider model that uses WinRM +to remove the dependency on DCOM. This CIM provider model also uses new WMI +provider APIs that enable developers to write Windows PowerShell cmdlets in +native code (C++). + +Don't confuse WMI providers with Windows PowerShell providers. Many Windows +features have an associated WMI provider that exposes their management +capabilities. To get WMI providers, run a WMI query that gets instances of the +**__Provider** WMI class, such as the following query. + +```powershell +Get-WmiObject -Class __Provider +``` + +## Three components of WMI + +The following three components of WMI interact with Windows PowerShell: +Namespaces, Providers, and Classes. + +WMI Namespaces organize WMI providers and WMI classes into groups of related +components. In this way, they're similar to .NET Framework namespaces. +Namespaces aren't physical locations, but are more like logical databases. All +WMI namespaces are instances of the __Namespace system class. The default WMI +namespace is **root/CIMV2** (since Microsoft Windows 2000). To use Windows +PowerShell to get WMI namespaces in the current session, use a command with the +following format. + +```powershell +Get-WmiObject -Class __Namespace +``` + +To get WMI namespaces in other namespaces, use the Namespace parameter to +change the location of the search. The following command finds WMI namespaces +that reside in the **root/CIMV2/Applications** namespace. + +```powershell +Get-WmiObject -Class __Namespace -Namespace root/CIMV2/Applications +``` + +WMI namespaces are hierarchical. Therefore, obtaining a list of all namespaces +on a particular system requires performing a recursive query starting at the +root namespace. + +WMI Providers expose information about Windows manageable objects. A provider +retrieves data from a component, and passes that data through WMI to a +management application, such as Windows PowerShell. Most WMI providers are +dynamic providers, which means that they obtain the data dynamically when it's +requested through the management application. + +## Finding WMI classes + +In a default Windows 8 installation, there are more than 1,100 WMI classes in +**root/CIMV2**. With this many WMI classes, the challenge becomes identifying +the appropriate WMI class to use to perform a specific task. Windows PowerShell +3.0 provides two ways to find WMI classes that are related to a specific topic. + +For example, to find WMI classes in the **root/CIMV2** WMI namespace that are +related to disks, you can use a query such as the one shown here. + +```powershell +Get-WmiObject -List *Disk* +``` + +To find WMI classes that are related to memory, you might use a query such as +the one shown here. + +```powershell +Get-WmiObject -List *Memory* +``` + +The CIM cmdlets also provide the ability to discover WMI classes. To do this, +use the `Get-CimClass` cmdlet. The command shown here lists WMI classes related +to video. + +```powershell +Get-CimClass *Video* +``` + +Tab expansion works when changing WMI namespaces, and therefore use of tab +expansion makes sub-WMI namespaces easily discoverable. In the following +example, the `Get-CimClass` cmdlet lists WMI classes related to power settings. +To find it, type the **root/CIMV2** namespace and then press the Tab key +several times until the **power** namespace appears. Here is the command: + +```powershell +Get-CimClass *Power* -Namespace root/CIMV2/power +``` diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_WQL.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_WQL.md new file mode 100644 index 00000000000..6d51104b608 --- /dev/null +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_WQL.md @@ -0,0 +1,719 @@ +--- +description: Describes WMI Query Language (WQL), which can be used to get WMI objects in Windows PowerShell. +Locale: en-US +ms.date: 01/06/2026 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_wql?view=powershell-7.6&WT.mc_id=ps-gethelp +schema: 2.0.0 +title: about_WQL +--- + +# about_WQL + +## Short description + +Describes WMI Query Language (WQL), which can be used to get WMI objects in +Windows PowerShell. + +## Long description + +WQL is the Windows Management Instrumentation (WMI) query language, which is +the language used to get information from WMI. + +You aren't required to use WQL to perform a WMI query in Windows PowerShell. +Instead, you can use the parameters of the `Get-WmiObject` or `Get-CimInstance` +cmdlets. WQL queries are somewhat faster than standard `Get-WmiObject` commands +and the improved performance is evident when the commands run on hundreds of +systems. However, be sure that the time you spend to write a successful WQL +query doesn't outweigh the performance improvement. + +The basic WQL statements you need to use WQL are `SELECT`, `WHERE`, and `FROM`. + +## When to use WQL + +When working with WMI, and especially with WQL, don't forget that you are +also using Windows PowerShell. Often, if a WQL query doesn't work as +expected, it's easier to use a standard Windows PowerShell command than to +debug the WQL query. + +Unless you are returning massive amounts of data from across +bandwidth-constrained remote systems, it's rarely productive to spend hours +trying to perfect a complicated WQL query when there is an acceptable +PowerShell cmdlet that does the same thing. + +## Using the SELECT statement + +A typical WMI query begins with a `SELECT` statement that gets all properties +or particular properties of a WMI class. To select all properties of a WMI +class, use an asterisk (`*`). The `FROM` keyword specifies the WMI class. + +A `SELECT` statement has the following format: + +``` +SELECT FROM +``` + +For example, the following `SELECT` statement selects all properties (`*`) from +the instances of the **Win32_BIOS** WMI class. + +``` +SELECT * FROM Win32_BIOS +``` + +> [!NOTE] +> PowerShell only displays the default object properties. These properties are +> defined in the `Types.ps1xml` file. Use the `Select-Object` cmdlet or a +> `Format-*` cmdlet to display additional properties. + +To select a particular property of a WMI class, place the property name +between the `SELECT` and `FROM` keywords. + +The following query selects only the name of the BIOS from the **Win32_BIOS** +WMI class. The command saves the query in the `$queryName` variable. + +``` +SELECT Name FROM Win32_BIOS +``` + +To select more than one property, use commas to separate the property names. +The following WMI query selects the name and the version of the **Win32_BIOS** +WMI class. The command saves the query in the `$queryNameVersion` variable. + +```WQL +SELECT name, version FROM Win32_BIOS +``` + +## Using the WQL query + +There are three ways to use WQL query in Windows PowerShell command. + +- Use the `Get-WmiObject` cmdlet +- Use the `Get-CimInstance` cmdlet +- Use the `[wmisearcher]` type accelerator. + +## Using the Get-WmiObject cmdlet + +The most basic way to use the WQL query is to enclose it in quotation marks (as +a string) and then use the query string as the value of the **Query** parameter +of the `Get-WmiObject` cmdlet, as shown in the following example. + +```powershell +Get-WmiObject -Query "SELECT * FROM Win32_BIOS" +``` + +```output +SMBIOSBIOSVersion : 8BET56WW (1.36 ) +Manufacturer : LENOVO +Name : Default System BIOS +SerialNumber : R9FPY3P +Version : LENOVO - 1360 +``` + +You can also save the WQL statement in a variable and then use the variable as +the value of the **Query** parameter, as shown in the following command. + +```powershell +$query = "SELECT * FROM Win32_BIOS" +Get-WmiObject -Query $query +``` + +You can use either format with any WQL statement. The following command uses +the query in the `$queryName` variable to get only the **Name** and **Version** +properties of the system BIOS. + +```powershell +$queryNameVersion = "SELECT Name, Version FROM Win32_BIOS" +Get-WmiObject -Query $queryNameVersion +``` + +```output +__GENUS : 2 +__CLASS : Win32_BIOS +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 2 +__DERIVATION : {} +__SERVER : +__NAMESPACE : +__PATH : +Name : S03KT39A +Version : LENOVO - 1270 +PSComputerName : +``` + +Remember that you can use the parameters of the `Get-WmiObject` cmdlet to get +the same result. For example, the following command also gets the values of the +**Name** and **Version** properties of instances of the **Win32_BIOS** WMI +class. + +```powershell +Get-WmiObject -Class Win32_BIOS -Property Name, Version +``` + +```output +__GENUS : 2 +__CLASS : Win32_BIOS +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 2 +__DERIVATION : {} +__SERVER : +__NAMESPACE : +__PATH : +Name : S03KT39A +Version : LENOVO - 1270 +PSComputerName : +``` + +## Using the Get-CimInstance cmdlet + +Beginning in Windows PowerShell 3.0, you can use the `Get-CimInstance` cmdlet +to run WQL queries. + +`Get-CimInstance` gets instances of CIM-compliant classes, including WMI +classes. The CIM cmdlets, introduced Windows PowerShell 3.0, perform the same +tasks as the WMI cmdlets. The CIM cmdlets comply with WS-Management (WSMan) +standards and with the Common Information Model (CIM) standard, which enables +the cmdlets to use the same techniques to manage Windows computers and +computers that are running other operating systems. + +The following command uses the `Get-CimInstance` cmdlet to run a WQL query. + +Any WQL query that can be used with `Get-WmiObject` can also be used with +`Get-CimInstance`. + +```powershell +Get-CimInstance -Query "SELECT * FROM Win32_BIOS" +``` + +```output +SMBIOSBIOSVersion : S03KT39A +Manufacturer : LENOVO +Name : S03KT39A +SerialNumber : MJ0AETTX +Version : LENOVO - 1270 +``` + +`Get-CimInstance` returns a **CimInstance** object, instead of the +**ManagementObject** that `Get-WmiObject` returns, but the objects are quite +similar. + +```powershell +PS> (Get-CimInstance -Query "SELECT * FROM Win32_BIOS").GetType().FullName +Microsoft.Management.Infrastructure.CimInstance + +PS> (Get-WmiObject -Query "SELECT * FROM Win32_BIOS").GetType().FullName +System.Management.ManagementObject +``` + +## Using the wmisearcher type accelerator + +The `[wmisearcher]` type accelerator creates a **ManagementObjectSearcher** +object from a WQL statement string. The **ManagementObjectSearcher** object has +many properties and methods, but the most basic method is the Get method, which +invokes the specified WMI query and returns the resulting objects. + +Using `[wmisearcher]`, you gain easy access to the **ManagementObjectSearcher** +.NET class. This lets you query WMI and to configure the way the query is +conducted. + +To use the `[wmisearcher]` type accelerator: + +1. Cast the WQL string into a **ManagementObjectSearcher** object. +1. Call the Get method of the **ManagementObjectSearcher** object. + +For example, the following command casts the "select all" query, saves the +result in the `$bios` variable, and then calls the `Get()` method of the +**ManagementObjectSearcher** object in the `$bios` variable. + +```powershell +$bios = [wmisearcher]"SELECT * FROM Win32_BIOS" +$bios.Get() +``` + +```output +SMBIOSBIOSVersion : 8BET56WW (1.36 ) +Manufacturer : LENOVO +Name : Default System BIOS +SerialNumber : R9FPY3P +Version : LENOVO - 1360 +``` + +You can use the `[wmisearcher]` type accelerator to cast the query or the +variable. In the following example, the `[wmisearcher]` type accelerator is +used to cast the variable. The result is the same. + +```powershell +[wmisearcher]$bios = "SELECT * FROM Win32_BIOS" +$bios.Get() +``` + +```output +SMBIOSBIOSVersion : S03KT39A +Manufacturer : LENOVO +Name : S03KT39A +SerialNumber : MJ0AETTX +Version : LENOVO - 1270 +``` + +When you use the `[wmisearcher]` type accelerator, it changes the query string +into a **ManagementObjectSearcher** object, as shown in the following commands. + +```powershell +$a = "SELECT * FROM Win32_BIOS" +$a.GetType().FullName +System.String + +$a = [wmisearcher]"SELECT * FROM Win32_BIOS" +$a.GetType().FullName +System.Management.ManagementObjectSearcher +``` + +This command format works on any query. The following command gets the value +of the **Name** property of the **Win32_BIOS** WMI class. + +```powershell +$biosName = [wmisearcher]"Select Name from Win32_BIOS" +$biosName.Get() +``` + +```output +__GENUS : 2 +__CLASS : Win32_BIOS +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 +__DERIVATION : {} +__SERVER : +__NAMESPACE : +__PATH : +Name : S03KT39A +PSComputerName : +``` + +## Using the basic WQL WHERE statement + +A `WHERE` statement establishes conditions for the data that a `SELECT` +statement returns. + +The `WHERE` statement has the following format: + +``` +WHERE +``` + +For example: + +``` +WHERE Name = 'Notepad.exe' +``` + +The `WHERE` statement is used with the `SELECT` statement, as shown in the +following example. + +``` +SELECT * FROM Win32_Process WHERE Name = 'Notepad.exe' +``` + +When using the `WHERE` statement, the property name and value must be accurate. + +For example, the following command gets the Notepad processes on the local +computer. + +```powershell +Get-WmiObject -Query "SELECT * FROM Win32_Process WHERE name='Notepad.exe'" +``` + +However, the following command fails, because the process name includes the +`.exe` file extension. + +```powershell +Get-WmiObject -Query "SELECT * FROM Win32_Process WHERE name='Notepad'" +``` + +## WHERE statement comparison operators + +The following operators are valid in a WQL `WHERE` statement. + +``` +Operator Description +----------------------- += Equal +!= Not equal +<> Not equal +< Less than +> Greater than +<= Less than or equal +>= Greater than or equal +LIKE Wildcard match +IS Evaluates null +ISNOT Evaluates not null +ISA Evaluates a member of a WMI class +``` + +There are other operators, but these are the ones used for making comparisons. + +For example, the following query selects the **Name** and **Priority** +properties from processes in the **Win32_Process** class where the process +priority is greater than or equal to 11. The `Get-WmiObject` cmdlet runs the +query. + +```powershell +$highPriority = "Select Name, Priority from Win32_Process " + + "WHERE Priority >= 11" +Get-WmiObject -Query $highPriority +``` + +## Using the WQL operators in the -Filter parameter + +The WQL operators can also be used in the value of the **Filter** parameter of +the `Get-WmiObject` or `Get-CimInstance` cmdlets, as well as in the value of +the **Query** parameters of these cmdlets. + +For example, the following command gets the **Name** and **ProcessId** +properties of the last five processes that have **ProcessId** values greater +than 1004. The command uses the **Filter** parameter to specify the +**ProcessId** condition. + +```powershell +$getWmiObjectSplat = @{ + Class = 'Win32_Process' + Property = 'Name', 'ProcessId' + Filter = "ProcessId >= 1004" +} +Get-WmiObject @getWmiObjectSplat | + Sort-Object ProcessId | + Select-Object Name, ProcessId -Last 5 +``` + +```output +Name ProcessId +---- --------- +SROSVC.exe 4220 +WINWORD.EXE 4664 +TscHelp.exe 4744 +SnagIt32.exe 4748 +WmiPrvSE.exe 5056 +``` + +## Using the LIKE operator + +The `LIKE` operator lets you use wildcard characters to filter the results of a +WQL query. + +``` +Like Operator Description +-------------------------------------------------- +[] Character in a range [a-f] or a set + of characters [abcdef]. The items in + a set don't need to be consecutive or + listed in alphabetical order. + +^ Character not in a range [^a-f] or + not in a set [^abcdef]. The items in + a set don't need to be consecutive or + listed in alphabetical order. + +% A string of zero or more characters + +_ One character. +(underscore) NOTE: To use a literal underscore + in a query string, enclose it in + square brackets [_]. +``` + +When the `LIKE` operator is used without any wildcard characters or range +operators, it behaves like the equality operator (`=`) and returns objects only +when they're an exact match for the pattern. + +You can combine the range operation with the percent (`%`) wildcard character +to create simple, yet powerful filters. + +### LIKE operator examples + +#### Example 1: [\] + +The following commands start Notepad and then search for an instance of the +**Win32_Process** class that has a name that starts with a letter between "H" +and "N" (case-insensitive). + +The query should return any process from `Hotepad.exe` through `Notepad.exe`. + +```powershell +Notepad # Starts Notepad +$query = "SELECT * FROM Win32_Process WHERE Name LIKE '[H-N]otepad.exe'" +Get-WmiObject -Query $query | select Name, ProcessId +``` + +```output +Name ProcessId +---- --------- +notepad.exe 1740 +``` + +#### Example 2: [\] and % + +The following commands select all process that have a name that begins with a +letter between A and P (case-insensitive) followed by zero or more letters in +any combination. + +The `Get-WmiObject` cmdlet runs the query, the `Select-Object` cmdlet gets the +**Name** and **ProcessId** properties, and the `Sort-Object` cmdlet sorts the +results in alphabetical order by name. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE name LIKE '[A-P]%'" +Get-WmiObject -Query $query | + Select-Object -Property Name, ProcessId | + Sort-Object -Property Name +``` + +#### Example 3: Not in Range (^) + +The following command gets processes whose names don't begin with any of the +following letters: A, S, W, P, R, C, U, N + +and followed zero or more letters. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE name LIKE '[^ASWPRCUN]%'" +Get-WmiObject -Query $query | + Select-Object -Property Name, ProcessId | + Sort-Object -Property Name +``` + +#### Example 4: Any characters -- or none (%) + +The following commands get processes that have names that begin with `calc`. +The percent (`%`) symbol is the WQL wildcard character. It's equivalent to the +asterisk (`*`) wildcard in PowerShell. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE Name LIKE 'calc%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessId +``` + +```output +Name ProcessId +---- --------- +calc.exe 4424 +``` + +#### Example 5: One character (_) + +The following commands get processes that have names that have the following +pattern, `c_lc.exe` where the underscore character represents any one +character. This pattern matches any name from `calc.exe` through `czlc.exe`, or +`c9lc.exe`, but doesn't match names in which the "c" and "l" are separated by +more than one character. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE Name LIKE 'c_lc.exe'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessId +``` + +```output +Name ProcessId +---- --------- +calc.exe 4424 +``` + +#### Example 6: Exact match + +The following commands get processes named `WLIDSVC.exe`. Even though the query +uses the `LIKE` keyword, it requires an exact match, because the value doesn't +include any wildcard characters. + +```powershell +$query = "SELECT * FROM Win32_Process WHERE name LIKE 'WLIDSVC.exe'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessId +```powershell + +```output +Name ProcessId +---- --------- +WLIDSVC.exe 84 +``` + +## Using the OR operator + +To specify multiple independent conditions, use the `OR` keyword. The `OR` +keyword appears in the `WHERE` clause. It performs an inclusive `OR` operation +on two (or more) conditions and returns items that meet any of the conditions. + +The `OR` operator has the following format: + +``` +WHERE OR ... +``` + +For example, the following commands get all instances of the **Win32_Process** +WMI class but returns them only if the process name is `winword.exe` or +`excel.exe`. + +```powershell +$q = "SELECT * FROM Win32_Process WHERE Name='winword.exe'" + + " OR Name='excel.exe'" +Get-WmiObject -Query $q +``` + +The `OR` statement can be used with more than two conditions. In the following +query, the `OR` statement gets `Winword.exe`, `Excel.exe`, or `powershell.exe`. + +```powershell +$q = "SELECT * FROM Win32_Process WHERE Name='winword.exe'" + + " OR Name='excel.exe' OR Name='powershell.exe'" +``` + +## Using the AND operator + +To specify multiple related conditions, use the `AND` keyword. The `AND` +keyword appears in the `WHERE` clause. It returns items that meet all the +conditions. + +The `AND` operator has the following format: + +``` +WHERE `AND` ... +``` + +For example, the following commands get processes that have a name of +`Winword.exe` and the process ID of 6512. + +Note that the commands use the `Get-CimInstance` cmdlet. + +```powershell +$q = "SELECT * FROM Win32_Process WHERE Name = 'winword.exe' " + + "AND ProcessId =6512" +Get-CimInstance -Query $q +``` + +```output +ProcessId Name HandleCount WorkingSetSize VirtualSize +--------- ---- ----------- -------------- ----------- +# 6512 WINWORD.EXE 768 117170176 633028608 +``` + +All operators, including the `LIKE` operators are valid with the `OR` and `AND` +operators. And, you can combine the `OR` and `AND` operators in a single query +with parentheses that tell WMI which clauses to process first. + +This command uses the Windows PowerShell continuation character (`` ` ``) +divide the command into two lines. + +## Searching for null values + +Searching for null values in WMI is challenging, because it can lead to +unpredictable results. `Null` isn't zero and it isn't equivalent to an empty +string. Some WMI class properties are initialized and others aren't, so a +search for null might not work for all properties. + +To search for null values, use the Is operator with a value of `null`. + +For example, the following commands get processes that have a null value for +the **IntallDate** property. The commands return many processes. + +```powershell +$q = "SELECT * FROM Win32_Process WHERE InstallDate is null" +Get-WmiObject -Query $q +``` + +In contrast, the following command, gets user accounts that have a null value +for the **Description** property. This command doesn't return any user +accounts, even though most user accounts don't have any value for the +**Description** property. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Description is null" +Get-WmiObject -Query $q +``` + +To find the user accounts that have no value for the **Description** property, +use the equality operator to get an empty string. To represent the empty +string, use two consecutive single quotation marks. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Description = '' " +``` + +## Using true or false + +To get boolean values in the properties of WMI objects, use `True` and `False`. +They aren't case sensitive. + +The following WQL query returns only local user accounts from a domain joined +computer. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE LocalAccount = True" +Get-CimInstance -Query $q +``` + +To find domain accounts, use a value of False, as shown in the following +example. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE LocalAccount = False" +Get-CimInstance -Query $q +``` + +## Using the escape character + +WQL uses the backslash (`\`) as its escape character. This is different from +Windows PowerShell, which uses the backtick character (`` ` ``). + +Quotation marks, and the characters used for quotation marks, often need to be +escaped so that they aren't misinterpreted. + +To find a user whose name includes a single quotation mark, use a backslash to +escape the single quotation mark, as shown in the following command. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Name = 'Tim O\'Brian'" +Get-CimInstance -Query $q +``` + +```output +Name Caption AccountType SID Domain +---- ------- ----------- --- ------ +Tim O'Brian FABRIKAM\TimO 512 S-1-5-21-1457... FABRIKAM +``` + +In some case, the backslash also needs to be escaped. For example, the +following commands generate an Invalid Query error due to the backslash in the +Caption value. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Caption = 'Fabrikam\TimO'" +Get-CimInstance -Query $q +``` + +```output +Get-CimInstance : Invalid query +At line:1 char:1 ++ Get-CimInstance -Query $q ++ ~~~~~~~~~~~ + + CategoryInfo : InvalidArgument: (:) [Get-CimInstance], CimExcep + + FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastr +``` + +To escape the backslash, use a second backslash character, as shown in the +following command. + +```powershell +$q = "SELECT * FROM Win32_UserAccount WHERE Caption = 'Fabrikam\\TimO'" +Get-CimInstance -Query $q +``` + +## See also + +- [about_Special_Characters][02] +- [about_Quoting_Rules][01] +- [about_WMI][04] + + +[01]: about_Quoting_Rules.md +[02]: about_Special_Characters.md +[04]: about_WMI.md