New-XPathQuery

Description

The New-XPathQuery cmdlet create a new query object that can be used to create an XPath expression using [New-XPathExpression], or an element in an XPath query group using New-XPathQueryGroup. The resulting XPathExpression can be passed as a parameter to Search-Resources. An XPath query object contains the component of an expression that compares an attribute with a value.

For a list of examples filters generated by the XPath cmdlets, see the XPath expression examples page.

Syntax

New-XpathQuery [-AttributeName] <string> [-Operator] <ComparisonOperator> {Equals | NotEquals | GreaterThan | GreaterThanOrEquals | LessThan | LessThanOrEquals | IsPresent | IsNotPresent | Contains | StartsWith | EndsWith} [[-Value] <Object>] [[-Negate]]

Parameters

AttributeName

Required. The name of the attribute to compare

Operator

Required. The operator to apply to the attribute

Value

Optional if using the IsPresent or IsNotPresentOperator. Required for all other operators. The value to use in the comparison. This can be any value that can be converted to the data type of the attribute being searched. Reference attributes can also specify another XPath expression as the search value. See the dereferencing example below.

Negate

Optional. Negates the expression by inverting the comparison operation. For example, using the Negate switch, the LessThan operator becomes not LessThan. Note that the FIM XPath dialect does not support double negation. Therefore using the Negate parameter on IsNotPresent and NotEquals operators is not supported.

Examples

Viewing the query string

The New-XPathQuery does not return a usable query itself. It returns only a part of the query that is used in an XPath expression. You can view the query component itself as shown in the following example.

$query = New-XPathQuery -AttributeName "AccountName" -Operator Equals -Value "ryan"
$query.ToString()

This returns an string representing the query component

(AccountName = 'ryan')

Building a simple query

In order to use the query, it must be rendered by an XPath expression created with the [New-XPathExpression] cmdlet

$query = New-XPathQuery -AttributeName "AccountName" -Operator Equals -Value "ryan"
$expression = New-XPathExpression -ObjectType "Person" -QueryObject $query
$expression.ToString()

This returns an expression containing the query

/Person[(AccountName = 'ryan')]

You can also use the pipeline to pass the query to the [New-XPathExpression] cmdlet.

$expression =  New-XPathQuery -AttributeName "AccountName" -Operator Equals -Value "ryan" | New-XPathExpression -ObjectType "Person" 
$expression.ToString()

Testing for presence

The IsPresent and IsNotPresent operators work without the Value parameter

$query = New-XPathQuery -AttributeName "AccountName" -Operator IsPresent
$expression = New-XPathExpression -ObjectType "Person" -QueryObject $query
$expression.ToString()

This returns an expression containing the query

/Person[(starts-with(AccountName, '%'))]

Using another XPath expression to query a reference attribute

# Build an expression to find a user by its account name
$query = New-XpathQuery -AttributeName "AccountName" -Operator Equals -Value "ryan"
$expression = New-XpathExpression -ObjectType "Person" -Query $query

# Build a query to find all users with a manager who has the account name 'ryan'
$derefQuery = New-XpathQuery -AttributeName "Manager" -Operator Equals -Value $expression
$derefExpression = New-XpathExpression Person $derefQuery
$derefExpression.ToString()

This returns an expression containing the query

/Person[(Manager = /Person[(AccountName = 'ryan')])]