Working with recipient filters
Starting with Exchange 2007 and continuing with Exchange 2010, address lists, dynamic distribution groups, e-mail address policies, and global address lists can be customized with recipient filters that use OPATH filtering syntax. This replaces the LDAP filtering syntax that was used in earlier versions of Exchange. We can also perform server-side searches using filters, which can greatly speed up our work. In this recipe, you'll learn how to work with these filters in the Exchange Management Shell.
How to do it...
- We can filter the results from the recipient
Get-*cmdlets using the-Filterparameter:Get-Mailbox -Filter {Office -eq 'Sales'} - In addition, we can use attribute filters to create distribution groups, e-mail address policies, and address lists using the
-RecipientFilterparameter:New-DynamicDistributionGroup -Name DL_Accounting ` -RecipientFilter { (Department -eq 'Accounting') -and (RecipientType -eq 'UserMailbox') }
How it works...
In our first example, you can see that we've used the Get-Mailbox cmdlet to retrieve only the users that have the Office property set to the value Sales. This is more efficient then performing the following command, which would return the same results:
Get-Mailbox | ?{$_.Office -eq 'Sales'}
This command uses the Where-Object cmdlet (using the ? alias) to retrieve only the mailboxes with their Office property set to Sales.We get back the same results, but it is less efficient than our original example. When filtering with Where-Object, every mailbox in the organization must be retrieved and evaluated before any results are returned. The benefit of using the -Filter parameter with the Get-Mailbox cmdlet is that the filtering is done on the server and not our client machines.
There are a number of cmdlets that support this parameter. You can get an entire list with a simple one-liner:
get-excommand | ?{$_.parameters.keys -eq 'filter'}
This uses the shell function get-excommand to retrieve a list of Exchange Management Shell cmdlets that support the -Filter parameter. If you are writing scripts or functions that need to query a large amount of recipients, you'll want to try to use server-side filtering whenever possible.
Unfortunately, there are only a certain set of properties that can be filtered. For instance, we were able to filter using the Office property when using the Get-Mailbox cmdlet. Based on that, you may assume that, since OrganizationalUnit is a property of a mailbox object, that you can filter on that as well, but that is not the case. The Get-Mailbox cmdlet provides an -OrganizationalUnit parameter that can be used to accomplish that task, so it's not always safe to assume that a particular property can be used within a filter. To view a list of common filterable properties that can be used with the –Filter parameter, see Appendix A at the end of this book.
In our second example, we used the New-DynamicDistributionGroup cmldet to create a query-based group. The membership of this group is determined using the OPATH filter defined with the –RecipientFilter parameter. The syntax is similar and the same PowerShell operators can be used. Based on the settings used with our filter when we created the DL_Accounting group, only mailboxes with their Department attribute set to Accounting will be included. Other recipient types, such as mail contacts and mail users, will not be included in the group, even though they may be in the Accounting department.
Dynamic distribution groups, address lists, and e-mail address policies can be configured with these filters. Again, to get the list of cmdlets that support this functionality, use the get-excommand shell variable:
get-excommand | ?{$_.parameters.keys -eq 'recipientfilter'}
These cmdlets also have a limited number of filterable properties that can be used. To view a list of the most common properties used with the –RecipientFilter parameter, see Appendix A at the end of this book.
There's more…
Instead of using the -RecipientFilter parameter, you have the option of using pre-canned filters. In some cases this may be easier, as it allows you to simply use a set of parameters and values as opposed to an OPATH filter. The following command would create our DL_Accounting distribution group with the same members using the pre-canned filter parameters:
New-DynamicDistributionGroup -Name DL_Accounting ` -IncludedRecipients MailboxUsers ` -ConditionalDepartment Accounting
As you can see, this is a little easier to read and probably easier to type into the shell. Although, there are only a few pre-canned parameters available and they may not always be useful depending on what you are trying to do, but it helps to be aware of this functionality. You can use Get-Help to view the entire list of available parameters for each cmdlet that supports recipient filters.
Understanding variables in filters
One of the issues you may run into when working in the shell is the expansion of variables used within a filter. For example, this syntax is completely valid but will not currently work correctly in the Exchange Management Shell:
$office = "sales"
Get-Mailbox -Filter {Office -eq $office}
You might get some results from this command, but they will probably not be what you are expecting. This is because, when running the Get-Mailbox cmdlet, the value of the $office variable will not be expanded prior to the command being executed through the remote shell. What you end up with instead is a filter checking for a $null value. In order to fix this, you'll need to use syntax similar to the following:
$office = "sales" Get-Mailbox -Filter "Office -eq '$office'"
This syntax will force any variables assigned within the -Filter parameter to be expanded before sending the command through the remote session, and you should get back the correct results.