# 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](https://docs.lithnet.io/resource-management-powershell/usage/search-resources#description) cmdlet
* As an input to the [New-XPathQuery](https://docs.lithnet.io/resource-management-powershell/usage/cmdlet-reference/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 ](https://docs.lithnet.io/resource-management-powershell/usage/cmdlet-reference/new-xpathquery)or [New-XPathQueryGroup](https://docs.lithnet.io/resource-management-powershell/usage/cmdlet-reference/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](https://docs.lithnet.io/resource-management-powershell/help-and-support/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](https://docs.lithnet.io/resource-management-powershell/usage/cmdlet-reference/new-xpathquery) or [New-XPathQueryGroup](https://docs.lithnet.io/resource-management-powershell/usage/cmdlet-reference/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

```powershell
# 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](https://docs.lithnet.io/resource-management-powershell/usage/cmdlet-reference/search-resources) cmdlet to search for objects

```powershell
# 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](https://msdn.microsoft.com/en-us/library/windows/desktop/ee652287.aspx). The following example finds the manager of a user with the account name 'ryan'

```powershell
# 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

```powershell
# 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.

```powershell
$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

```xml
<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>
```