New-XPathExpression

Description

The New-XPathExpression cmdlet create an XPath expression that can be used in the following manners

• As an input to the Search-Resources cmdlet

• As an input to the New-XPathQuery cmdlet

• By using the ToString() method, you can generate an expression to use elsewhere in your script

• When setting a resource attribute that expects a Filter type

The cmdlet takes a query or group generated with the New-XPathQuery or New-XPathQueryGroup cmdlets and produces an XPath expression that can be used in the manners described above.

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

Syntax

New-XpathExpression [-ObjectType] <string> [-QueryObject] <IXPathQueryObject> [[-DereferenceAttribute] <string>] [[-WrapFilterXml]]

Parameters

ObjectType

Required. The type of object to query. To search on all object types, use the value *

QueryObject

Required. The query or group generated using the New-XPathQuery or New-XPathQueryGroup cmdlet

DereferenceAttribute

Optional. Specifies a reference-type attribute to query. See the example section for more information.

WrapFilterXml

Optional. Specifies that the resulting XPath expression should be wrapped in the filter XML element used when setting the Filter attribute on sets and groups.

Examples

Creating a basic expression

# Creates an expression that searches for users with the account name 'ryan'
$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')]

Passing the expression to the Search-Resources cmdlet

The expression can be passed directly to the Search-Resources cmdlet to search for objects

# Creates an expression that searches for users with the account name 'ryan'
$query = New-XPathQuery -AttributeName "AccountName" -Operator Equals -Value "ryan"
$expression = New-XPathExpression -ObjectType "Person" -QueryObject $query
Search-Resources $expression

Building an expression to dereference an object

The expression builder supports dereferencing expressions, as supported by the Resource Management Service. The following example finds the manager of a user with the account name 'ryan'

# Creates an expression that returns the manager of a user who has the account name 'ryan'
$query = New-XPathQuery -AttributeName "AccountName" -Operator Equals -Value "ryan"
$expression = New-XPathExpression -ObjectType "Person" -QueryObject $query -DereferenceAttribute "Manager"
$expression.ToString()

This returns the following expression

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

You can also use a nested expression to find all users who have the person with the account name of 'ryan' as their manager

# 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')])]

Building a filter expression

When using the expression builder to create an value to use in a Filter attribute in a set or group, you can specify that the resulting expression should be wrapped in the XML filter element.

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

The resulting string is as follows

<Filter xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Dialect="http://schemas.microsoft.com/2006/11/XPathFilterDialect" xmlns="http://schemas.xmlsoap.org/ws/2004/09/enumeration">/Person[(AccountName = 'ryan')]</Filter>