Take the guess work out of XPath with the Lithnet FIM Service PowerShell Module

Summary

The FIM Service allows you to query for resources using a subset of the XPath 2.0 dialect. It provides a quite powerful mechanism for searching for resources, but has more than a few curiosities when it comes to constructing queries for different attribute types.
The Lithnet FIM Service PowerShell module includes three cmdlets to help take the guess work out of constructing your XPath queries.

New-XPathQuery

The New-XPathQuery cmdlet creates a predicate that forms part of an XPath expression. The query is the Attribute = ‘value’ component of the expression

New-XPathQueryGroup

An XPath query group contains multiple XPath query objects, or other query groups, that are combined together with an ‘and’ or ‘or’ operator.

New-XPathExpression

The XPath expression wraps the query or query group with the appropriate syntax defining the object type (eg /Person[query])

Working with different attribute types

The cmdlets generate the correct syntax for each attribute type, without you have having to remember all the different ways the query needs to be expressed.
For example, lets have a look at the way we have to test for presence for each different attribute type

String	/Person[(starts-with(AccountName, '%'))]
Integer	/Person[(unixGid <= 999999999999999)]
DateTime	/Person[(ExpiryDate <= '9999-12-31T23:59:59.997')]
Boolean	/Person[((AccountDisabled = true) or (AccountDisabled = false))]
Reference	/Person[(Manager = /*)]

The New-XPathQuery cmdlet has a simple syntax, that is independent of the type of attribute.

The cmdlet will automatically generate the syntax that is appropriate for the attribute specified. It’s not just the IsPresent operator that is made simpler. The cmdlets support all the attribute types and operators that are supported by FIM. The underlying Lithnet RMC library used by the cmdlets has over 100 associated unit tests to ensure all combinations of operators and attributes generate the correct XPath syntax.

How do i use it?

Simple query

The following example shows a simple query that checks for an AccountName of ‘ryan’

Combining queries into a group

You can combine multiple queries together in a group using the New-XPathQueryGroup cmdlet. This allows you to join queries created by New-XPathQuery together with an And or Or operator. Searching for an AccountName of ‘bob’ or ‘ryan’ is shown in the example below.

Nested query groups

Query groups can contain child query groups as well. You can build complex nested expressions using  multiple groups. The following example looks for all users who have a display name starting with ‘ryan’ or ‘bob’ that also have an email address

Nested expressions

When querying a reference attribute, you can use another expression as a query parameter. This allows you to build dereferencing expressions with ease. The following example searches for all people who have a manager with the AccountName ‘ryan’

Dereferencing expressions

Creating a dereferencing expression is easy with the DereferenceAttribute parameter on the New-XPathExpression cmdlet. The following example gets the manager of the person with the AccountName ‘ryan’

Using the expression object

Passing the expression to Search-Resources

Expression objects can be passed to other cmdlets such as Search-Resources. Rather than providing an XPath string to Search-Resources, you can simply pass the expression object.

Filter syntax

You can also use the builder to create the Filter attribute used is sets and groups. The –WrapFilterXml parameter ensures that the <Filter> XML element is wrapped around your expression

Setting Filter attributes directly

The library supports setting the value of a Filter attribute to an expression object directly. Ensure you set the –WrapFilterXml parameter on your expression.

Further Reading

• The cmdlet reference documents the full set of features available in the PowerShell module.
  
• The XPath Expression Examples page shows all the possible resulting XPath expressions for each attribute type

Feedback

If you have an idea for a new feature, contact me using one of the methods below

Email: ryan@lithiumblue.com

Follow @RyanLNewington