7 min read

Microsoft Exchange 2010 PowerShell Cookbook

Microsoft Exchange 2010 PowerShell Cookbook

Manage and maintain your Microsoft Exchange 2010 environment with the Exchange Management Shell and Windows PowerShell 2.0 using this book and eBook

Performing some basic steps

To work with the code samples in this article, follow these steps to launch the Exchange Management Shell:

  1. Log onto a workstation or server with the Exchange Management Tools installed
  2. Open the Exchange Management Shell by clicking on Start | All Programs | Exchange Server 2010
  3. Click on the Exchange Management Shell shortcut

Reporting on distribution group membership

One of the common requests you are likely to receive as an Exchange administrator is to generate a report detailing which recipients are members of one or more distribution groups. In this recipe, we’ll take a look at how to retrieve this information from the Exchange Management Shell.

How to do it…

To view a list of each distribution group member interactively, use the following code:

foreach($i in Get-DistributionGroup -ResultSize Unlimited) {
Get-DistributionGroupMember $i -ResultSize Unlimited |
Select-Object @{n=”Member”;e={$_.Name}},
RecipientType,
@{n=”Group”;e={$i.Name}}
}


This will generate a list of Exchange recipients and their associated distribution group membership.

How it works…

This code loops through each item returned from the Get-DistributionGroup cmdlet. As we process each group, we run the Get-DistributionGroupMember cmdlet to determine the member list for each group and then use Select-Object to construct a custom object that provides Member, RecipientType, and Group properties. Notice that, when running both Exchange cmdlets, we’re setting the -ResultSize parameter to Unlimited to ensure that the details will be retrieved in the event that there are more than 1,000 groups or group members.

There’s more…

The previous code sample will allow you to view the output in the shell. If you want to export this information to a CSV file, use the following code:

$report=foreach($i in Get-DistributionGroup -ResultSize Unlimited) {
Get-DistributionGroupMember $i -ResultSize Unlimited |
Select-Object @{n=”Member”;e={$_.Name}},
RecipientType,
@{n=”Group”;e={$i.Name}}
}


The difference this time is that the output from our code is being saved in the $report variable. Once the report has been generated, the $report object is then exported to a CSV file that can be opened in Excel.

Adding members to a distribution group from an external file

When working in large or complex environments, performing bulk operations is the key to efficiency. Using PowerShell core cmdlets such as Get-Content and Import-CSV, we can easily import external data into the shell and use this information to perform bulk operations on hundreds or thousands of objects in a matter of seconds. Obviously, this can vastly speed up the time we spend on routine tasks and greatly increase our efficiency. In this recipe, we’ll use these concepts to add members to distribution groups in bulk from a text or CSV file using the Exchange Management Shell.

How to do it…

  1. Create a text file called c:users.txt that lists the recipients in your organization that you want to add to a group. Make sure you enter them one line at a time, as shown in the following screen shot:

    Microsoft Exchange Server 2010 Windows PowerShell tutorial

  2. Next, execute the following code to add the list of recipients to a distribution group:

    Get-Content c:users.txt | ForEach-Object {
    Add-DistributionGroupMember -Identity Sales -Member $_
    }

    
    

When the code runs, each user listed in the c:users.txt file will be added to the Sales distribution group.

How it works…

When importing data from a plain text file, we use the Get-Content cmdlet, which will read the content of the file into the shell one line at a time. In this example, we pipe the content of the file to the ForEach-Object cmdlet, and as each line is processed we execute the Add-DistributionGroupMember.

Inside the For-EachObject script block we use the Add-DistributionGroupMember cmdlet and assign the $_ object, which is the current recipient item in the pipeline, to the -Member parameter.

To remove recipients from a distribution group, you can use the Remove-DistributionGroupMember cmdlet.

Keep in mind that this text file does not have to contain the SMTP address of the recipient. You can also use the Active Directory account name, User Principal Name, Distinguished Name, GUID, or LegacyExchangeDN values. The important thing is that the file contains a valid and unique value for each recipient. If the identity of the recipient cannot be determined, the Add-DistributionGroupMember command will fail.

There’s more…

In addition to using plain text files, we can also import recipients from a CSV file and add them to a distribution group. Let’s say that you have a CSV file setup with multiple columns, such as FirstName, LastName, and EmailAddress. When you import the CSV file, the data can be accessed using the column headers as the property names for each object. Take a look at the following screenshot:

Microsoft Exchange Server 2010 Windows PowerShell tutorial

Here you can see that each item in this collection has an EmailAddress property. As long as this information corresponds to the recipient data in the Exchange organization, we can simply loop through each record in the CSV file and add these recipients to a distribution group:

Import-Csv C:users.csv | ForEach-Object {
Add-DistributionGroupMember Sales -Member $_.EmailAddress
}


The given code uses the Import-CSV cmdlet to loop through each item in the collection. As we process each record, we add the recipient to the Sales distribution group using the $_.EmailAddress object.

Previewing dynamic distribution group membership

The concept of the dynamic distribution group was introduced with the initial release of Exchange 2007 and included a new way to create and manage distribution groups. Unlike regular distribution groups whose members are statically defined, a dynamic distribution group determines its members based on a recipient filter. These recipient filters can be very complex, or they can be based on simple conditions, such as including all the users with a common value set for their Company or Department attributes in Active Directory. Since these dynamic groups are based on a query, they do not actually contain group members and if you want to preview the results of the groups query in the shell you need to use a series of commands. In this recipe, we’ll take a look at how to view the membership of dynamic distribution groups in the Exchange Management Shell.

How to do it…

Imagine that we have a dynamic distribution group named Legal that includes all of the users in Active Directory with a Department attribute set to the word Legal. We can use the following commands to retrieve the current list of recipients for this group:

$legal= Get-DynamicDistributionGroup -Identity legal
Get-Recipient -RecipientPreviewFilter $legal.RecipientFilter


How it works…

Recipient filters for dynamic distribution groups use OPATH filters that are accessible through the RecipientFilter property of a dynamic distribution group object. As you can see here, we have specified the Legal groups OPATH filter when running the Get-Recipient cmdlet with the –RecipientPreviewFilter parameter. Conceptually, this would be similar to running the following command:

Get-Recipient -RecipientPreviewFilter “Department -eq ‘Legal'”


Technically, there is a little bit more to it than that. If we were to actually look at the value for the RecipientFilter property of this dynamic distribution group, we would see much more information in addition to the filter defined for the Legal department. This is because Exchange automatically adds several additional filters when it creates a dynamic distribution group that excludes system mailboxes, discovery mailboxes, arbitration mailboxes, and more. This ends up being quite a bit of information, and creating an object instance of the dynamic distribution group gives us easy access to the existing OPATH filter that can be previewed with the Get-Recipient cmdlet.

There’s more…

When working with regular distribution groups, you may notice that there is a cmdlet called Get-DistributionGroupMember. This allows you to retrieve a list of every user that is a member of a distribution group. Unfortunately, there is no equivalent cmdlet for dynamic distribution groups, and we need to use the method outlined previously that uses the Get-Recipient cmdlet to determine the list of recipients in a dynamic distribution group.

If you find yourself doing this frequently, it probably makes sense to wrap these commands up into a function that can be added to your PowerShell profile. This will allow you to determine the members of dynamic distribution group using a single command that will be available to you every time you start the shell. Here is the code for a function called Get-DynamicDistributionGroupMember, which can be used to determine the list of recipients included in a dynamic distribution group:

function Get-DynamicDistributionGroupMember {
param(
[Parameter(Mandatory=$true)]
$Identity
)

$group = Get-DynamicDistributionGroup -Identity $Identity
Get-Recipient -RecipientPreviewFilter $group.RecipientFilter

}


Once this function is loaded into your shell session, you can run it just like a cmdlet:

Microsoft Exchange Server 2010 Windows PowerShell tutorial

You can see that the command returns the recipients that match the OPATH filter for the Legal distribution group and is much easier to type than the original example.

LEAVE A REPLY

Please enter your comment!
Please enter your name here