SummaryThe 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 cmdlet creates a predicate that forms part of an XPath expression. The query is the Attribute = ‘value’ component of the expression
Working with different attribute typesThe 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
|Integer||/Person[(unixGid <= 999999999999999)]|
|DateTime||/Person[(ExpiryDate <= '9999-12-31T23:59:59.997')]|
|Boolean||/Person[((AccountDisabled = true) or (AccountDisabled = false))]|
|Reference||/Person[(Manager = /*)]|
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 queryThe following example shows a simple query that checks for an AccountName of ‘ryan’
Combining queries into a groupYou 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 groupsQuery 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 expressionsWhen 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 expressionsCreating 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-ResourcesExpression 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 syntaxYou 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.
- 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
If you have an idea for a new feature, contact me using one of the methods below