Recently I was asked to rename some distribution groups in Exchange. Not so tough of a problem, but painstaking to do one at a time and there were a few of these to do. So I did what any good admin should do, I wrote a script to take care of this.
The issues
To properly rename a distribution group, you need to not only change the name of the group, but also the Alias, DisplayName and entries in the EmailAddresses field. The first two are easy but if you’re like me, you need to add a handful of emailaddresses to these fields. In our environment, we tend to add records when a name is changed rather than swap the old for the new. This way, if someone uses the old address, it still goes to where they want it too. Probably a better answer would be to create a mailbox with the old address and setup an auto reply that says “Hey, use the new address for this list.” That’ll be for another day.
Anyways, here is the script…
I should note, that I’m keeping this function (along with some other Exchange functions on github. you can get the most recent version of this script here: https://github.com/glaisne/PowerShellExchangeFunctions/archive/master.zip
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 |
function Rename-DistributionGroup { <# .SYNOPSIS Renames distribution groups .DESCRIPTION Changes the old name of the distribution group to the new name. Specifically, the fields that are changed are 'Name', 'Alias', 'DisplayName'. Also, for each smtp domain the added new alias address will be added. For example, if the old distribution list had an EmailAddresses field containing smtp:OldName@contoso.com and smtp:OldName@microsoft.com, this cmdlet would add 'smtp:NewName@contoso.com and 'smtp:NewName@Microsoft.com. .EXAMPLE Rename-DistributionGroup -OldName "OldDistributionGroup" -NewName "NewDistribtuionGroup" This would rename the distribution group named "OldDistributionGroup" to "NewDistributionGroup" .PARAMETER OldName The old (or current) name of the distribution group .PARAMETER NewName The new name of the distribution group. This is the name this script will change the distribution group to. .Parameter Confirm Use this to force or remove confirmation. #> [CmdletBinding(SupportsShouldProcess=$true)] param( [Parameter(Mandatory=$true)] [string] $OldName, [Parameter(Mandatory=$true)] [string] $NewName, [Boolean] $Confirm = $True ) write-verbose "Fields that contain ""$OldName""" try { Get-DistributionGroup $OldName -ErrorAction "Stop" |fl * | out-string -stream | select-string $OldName | Where {$_ -ne "" } | ForEach { write-verbose $_ } } catch [System.Management.Automation.RuntimeException] { Write-Verbose "There was an error accessing Distribution Group $OldName" write-host ("Exception: " + $Error[0].Exception.GetType().FullName) write-host $Error[0].Exception.Message return } catch { Write-Verbose "There was an error accessing Distribution Group $OldName" throw $_ } Write-Verbose "Getting the Distribution Group $OldName" $group = Get-DistributionGroup $OldName if ( $PSCmdlet.ShouldProcess($OldName, "Setting Name, Alias and DisplayName to $NewName") ) { if ( -Not $Confirm -or $($PSCmdlet.ShouldContinue("Are you sure you want to make this change?","Setting Name, Alias and DisplayName to $NewName on target $OldName" )) ) { Set-DistributionGroup $OldName -alias $NewName -DisplayName $NewName -ForceUpgrade } } Write-Verbose "EmailAddresses listed on the original group:" $group.EmailAddresses |ft -auto | out-string -stream | Where {$_ -ne "" } | ForEach { write-verbose $_ } foreach ($EmailAddress in $($group.EmailAddresses)) { if ($EmailAddress -notmatch "^smtp:.*@.*$") { Write-Verbose "Skipping processing of EmailAddress $EmailAddress" Continue } $domain = $EmailAddress.split('@')[1] Write-Verbose "Current Emailaddress ($EmailAddress) domain = $Domain" Write-Verbose "Adding new smtp address (smtp:$NewName@$Domain) to the EmailAddresses field" $group.EmailAddresses += "smtp:$NewName@$Domain" } Get-DistributionGroup $OldName -ErrorAction "Stop" |fl * | out-string -stream | select-string $OldName | Where {$_ -ne "" } | ForEach { write-verbose $_ } if ( $PSCmdlet.ShouldProcess($OldName, "Adding new alias to the old address' smtp addresses.") ) { if ( -Not $Confirm -or $($PSCmdlet.ShouldContinue("Are you sure you want to make this change?","Adding $NewName addresses on target $OldName" )) ) { if ($($group.EmailAddressPolicyEnabled)) { Write-Verbose "Turning off the Email Address Policy for this distribution group." Set-DistributionGroup $NewName -EmailAddressPolicyEnabled:$false } Write-Verbose "Setting the distribution groups new EmailAddresses setting." Set-DistributionGroup $NewName -EmailAddresses $($group.EmailAddresses) if ($($group.EmailAddressPolicyEnabled)) { Write-Verbose "Turning Back on the Email Address Policy for this distribution group." Set-DistributionGroup $NewName -EmailAddressPolicyEnabled:$True } } } Write-Verbose "New EmailAddresses listed on the original group:" (get-distributiongroup $NewName).EmailAddresses | out-string -stream | Where {$_ -ne "" } | ForEach { write-verbose $_ } } |
Some things worth noting
First of all, I’m working trying to make every bit of code I write more of a tool for others rather than something I use in my environment only. As a result, I’m utilizing ShouldContinue and ShouldProcess more. In this script I use them twice. First when I change the Name, Alias and DisplayName fields
|
1 2 3 4 5 6 7 |
if ( $PSCmdlet.ShouldProcess($OldName, "Setting Name, Alias and DisplayName to $NewName") ) { if ( -Not $Confirm -or $($PSCmdlet.ShouldContinue("Are you sure you want to make this change?","Setting Name, Alias and DisplayName to $NewName on target $OldName" )) ) { Set-DistributionGroup $OldName -alias $NewName -DisplayName $NewName -ForceUpgrade } } |
The second time I use ShouldProcess and ShouldContinue is when I set the EmailAddresses field.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
if ( $PSCmdlet.ShouldProcess($OldName, "Adding new alias to the old address' smtp addresses.") ) { if ( -Not $Confirm -or $($PSCmdlet.ShouldContinue("Are you sure you want to make this change?","Adding $NewName addresses on target $OldName" )) ) { if ($($group.EmailAddressPolicyEnabled)) { Write-Verbose "Turning off the Email Address Policy for this distribution group." Set-DistributionGroup $NewName -EmailAddressPolicyEnabled:$false } Write-Verbose "Setting the distribution groups new EmailAddresses setting." Set-DistributionGroup $NewName -EmailAddresses $($group.EmailAddresses) if ($($group.EmailAddressPolicyEnabled)) { Write-Verbose "Turning Back on the Email Address Policy for this distribution group." Set-DistributionGroup $NewName -EmailAddressPolicyEnabled:$True } } } |
Also, you’ll notice there isn’t much in the way of actual comments. This is a bit of a departure for me as I love my comments. But, rather than use comments, I’ve decided to use Write-Verbose so that everyone can share in “What should be happening.”
Let me know if you have any questions, or if you think there is a better way.
Thanks,
Gene