Templates
Microsoft Exchange Server 2007 will reach end of support on April 11, 2017. To stay supported, you will need to upgrade. For more information, see Resources to help you upgrade your Office 2007 servers and clients.
Applies to: Exchange Server 2007, Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3
This topic explains how you can use templates in the Exchange Management Shell to copy the configuration of an object to another object.
The examples in this topic explain how to use templates when you create a new mailbox by using the New-Mailbox and Set-Mailbox cmdlets. However, you can use templates with many cmdlets. Although the specific requirements for each cmdlet may be different, you use templates in the same manner for all cmdlets.
Why Are Templates Useful?
In Microsoft Exchange Server 2007, you can use the Exchange Management Shell to administer objects, such as mailboxes, Send connectors, and e-mail address list policies. These objects can contain many properties that you can configure. Examples of properties that can be configured by an administrator are the properties that determine a conditional custom attribute on an e-mail address list policy, whether a remote domain allows automatic replies to the Internet, and whether DNS routing is enabled on a Send connector.
If you want to create new objects that are based on the configuration of an existing object, you can use templates. When you use a template to create a new object, the Exchange Management Shell can't clone properties that are required and must be unique. Therefore, you must specify the properties that are required and the properties that must be unique when the new object is created.
Let's look at how you can use a template to save time when you want to create 100 mailboxes with the following customized configuration:
| Property | Customized value |
|---|---|
RetainDeletedItemsFor |
|
ProhibitSendQuota |
|
ProhibitSendReceiveQuota |
|
IssueWarningQuota |
|
UseDatabaseQuotaDefaults |
|
UseDatabaseRetentionDefaults |
|
The properties in this table are examples of the properties that you can set on mailboxes by using the Exchange Management Shell. When you create a new mailbox by using the New-Mailbox cmdlet, you can't configure these properties. To configure the properties, you must use the Set-Mailbox cmdlet. Without templates, you would have to create each new mailbox and then configure its properties. With templates, you can create one mailbox and configure its properties by using the Set-Mailbox cmdlet. Then you can use the first mailbox as a template and create the rest of the mailboxes by using that template.
Note
You could also use pipelining to pass the new mailbox object from the New-Mailbox cmdlet to the Set-Mailbox cmdlet. The Set-Mailbox cmdlet lets you set the properties of the new mailbox. The advantage of using templates is that you can use an existing object that is configured exactly the way you want to configure new objects. When you use an existing object, you make sure that you maintain a consistent configuration across those objects.
For more information about pipelining, see Pipelining.
How Does the Exchange Management Shell Implement Templates?
The Exchange Management Shell lets you use templates by supporting the TemplateInstance parameter on many cmdlets that have the verbs New, Add, and Enable. The TemplateInstance parameter accepts an object that is of the same type as the object you are trying to create. For example, if you want to create a new mailbox by using the New-Mailbox cmdlet, you must supply a mailbox object to the TemplateInstance parameter. For more information about cmdlets, see Understanding Cmdlets. For more information about objects, see Structured Data.
Note
You may want to create recipients, such as mailboxes or mail-enabled users, that are dedicated to acting as templates. For information about how to secure these dedicated recipient templates, see How to Secure Recipient Templates.
When you run a cmdlet with the TemplateInstance parameter, the cmdlet combines the configuration that is retrieved from the object that is specified in the TemplateInstance parameter with the values that you specified in the required parameters of the cmdlet. The combined configuration is used to create the new object. You can't configure the values on a required parameter by using the TemplateInstance parameter.
Note
If you specify a parameter and its value when you run a cmdlet, the value that you specify with that parameter overrides the value that is configured on the template object.
To use an object as a template, you must first create the object, and then configure its properties. After you've configured the object, you can then create additional objects by using that previously configured object as a template. For example, if you want to create a new mailbox with the configuration that is listed in the table in the earlier section, you first must create the mailbox with the New-Mailbox cmdlet, and then use the Set-Mailbox cmdlet to configure the properties of the mailbox object as in the following example:
$Password = ConvertTo-SecureString Pass@word1 -AsPlainText -Force
New-Mailbox -Name "Kim Akers" -Database "Mailbox Database" -UserPrincipalName kim@contoso.com -Password $Password
Set-Mailbox "Kim Akers" -RetainDeletedItemsFor 30.00:00:00 -ProhibitSendQuota 1GB -ProhibitSendReceiveQuota 1500MB -IssueWarningQuota 750MB -UseDatabaseQuotaDefaults $False -UseDatabaseRetentionDefaults $False
For more information about how to manage mailboxes, see Managing User Mailboxes.
After you have created and configured a mailbox object that you want to use as a template, you can create additional mailbox objects with the same configuration. You must first assign the mailbox object that you want to use as a template to a variable, as in the following example:
$Template = Get-Mailbox "Kim Akers"
It doesn't matter what the variable name is. For more information about variables, see User-Defined Variables.
Now that you have selected a mailbox object to use as a template, you can create a new mailbox by using that template, as in the following example:
$Password = ConvertTo-SecureString Pass@word1 -AsPlainText -Force
New-Mailbox -Name "David Simpson" -Database "Mailbox Database" -UserPrincipalName david@contoso.com -Password $Password -TemplateInstance $Template
After you create the new mailbox, you can use the following command to view the properties of the mailbox object that you configured by using the template to verify they have been set correctly:
Get-Mailbox "David Simpson" | Format-List Name, ProhibitSendQuota, ProhibitSendReceiveQuota, IssueWarningQuota, UseDatabaseQuotaDefaults, UseDatabaseRetentionDefaults, RetainDeletedItemsFor
Name : David Simpson
ProhibitSendQuota : 1GB
ProhibitSendReceiveQuota : 1500MB
IssueWarningQuota : 750MB
UseDatabaseQuotaDefaults : False
UseDatabaseRetentionDefaults : False
RetainDeletedItemsFor : 30.00:00:00
For more information about the Format-List cmdlet, see Working with Command Output.
Using Templates When You Want to Create Multiple Objects
Templates are very useful when you want to create many objects at the same time. For example, you may want to create mailboxes for every user who is listed in a comma-separated value (CSV) file and apply the same configuration to all the new mailboxes. By using the Import-CSV cmdlet and ForEach cmdlet, you can read in the data from the CSV file and then create a mailbox for each user who is listed in the file. For example, assume you want to create new mailboxes for the users in the following CSV file, and apply the mailbox object properties that are configured on the Kim Akers mailbox object. The CSV file, Users.csv, contains the following information:
Name,UPN,MailboxDatabase
Adam Bar,adam@contoso.com,Sales
Mike Ray,mike@contoso.com,Sales
Angela Barbariol,angela@contoso.com,Marketing
Chris Barry,chris@contoso.com,Marketing
Sanjay Jacob,sanjay@contoso.com,Marketing
First, assign the mailbox object that contains the configuration that you want to use with the template, as in the following example:
$Template = Get-Mailbox "Kim Akers"
Then, you can create the mailboxes by using the Import-CSV and ForEach cmdlets:
$Password = ConvertTo-SecureString Pass@word1 -AsPlainText -Force
Import-CSV C:\Users.CSV | ForEach { New-Mailbox -Name $_.Name -UserPrincipalName $_.UPN -Database $_.MailboxDatabase -Password $Password -Template $Template }
For more information about the ForEach cmdlet and how to add multiple recipients, see the following topics: