Applies to: Exchange Server 2007 SP3, Exchange Server
2007 SP2, Exchange Server 2007 SP1
Topic Last Modified: 2009-05-12
Use the New-DynamicDistributionGroup cmdlet to create a new dynamic distribution group.
Syntax
New-DynamicDistributionGroup -Name <String>
-IncludedRecipients <Nullable> [-Alias <String>]
[-ConditionalCompany <MultiValuedProperty>]
[-ConditionalCustomAttribute1 <MultiValuedProperty>]
[-ConditionalCustomAttribute10 <MultiValuedProperty>]
[-ConditionalCustomAttribute11 <MultiValuedProperty>]
[-ConditionalCustomAttribute12 <MultiValuedProperty>]
[-ConditionalCustomAttribute13 <MultiValuedProperty>]
[-ConditionalCustomAttribute14 <MultiValuedProperty>]
[-ConditionalCustomAttribute15 <MultiValuedProperty>]
[-ConditionalCustomAttribute2 <MultiValuedProperty>]
[-ConditionalCustomAttribute3 <MultiValuedProperty>]
[-ConditionalCustomAttribute4 <MultiValuedProperty>]
[-ConditionalCustomAttribute5 <MultiValuedProperty>]
[-ConditionalCustomAttribute6 <MultiValuedProperty>]
[-ConditionalCustomAttribute7 <MultiValuedProperty>]
[-ConditionalCustomAttribute8 <MultiValuedProperty>]
[-ConditionalCustomAttribute9 <MultiValuedProperty>]
[-ConditionalDepartment <MultiValuedProperty>]
[-ConditionalStateOrProvince <MultiValuedProperty>] [-Confirm
[<SwitchParameter>]] [-DisplayName <String>]
[-DomainController <Fqdn>] [-OrganizationalUnit
<OrganizationalUnitIdParameter>] [-RecipientContainer
<OrganizationalUnitIdParameter>] [-TemplateInstance
<PSObject>] [-UseRusServer <String>] [-WhatIf
[<SwitchParameter>]]
|
New-DynamicDistributionGroup -Name <String>
-RecipientFilter <String> [-Alias <String>] [-Confirm
[<SwitchParameter>]] [-DisplayName <String>]
[-DomainController <Fqdn>] [-OrganizationalUnit
<OrganizationalUnitIdParameter>] [-RecipientContainer
<OrganizationalUnitIdParameter>] [-TemplateInstance
<PSObject>] [-UseRusServer <String>] [-WhatIf
[<SwitchParameter>]]
|
Parameters
| Parameter | Required | Type | Description | ||
|---|---|---|---|---|---|
|
IncludedRecipients |
Required |
System.Nullable |
The IncludedRecipients parameter filters the recipient types that are used to build the dynamic distribution group. The IncludedRecipients parameter cannot be used if the RecipientFilter parameter is specified. The available values for the IncludedRecipients parameter are AllRecipients, MailboxUsers, Resources, MailContacts, MailGroups, Mail Users, and None. AllRecipients can be used only by itself. When multiple values of IncludedRecipients are separated by commas, the OR Boolean operator is applied. |
||
|
Name |
Required |
System.String |
The Name parameter specifies the name of the dynamic distribution group. If the DisplayName parameter is not specified, the value of Name is also used for DisplayName. The Name value cannot exceed 64 characters. If the values of Name and DisplayName are different:
|
||
|
RecipientFilter |
Required |
System.String |
The RecipientFilter parameter filters the mail-enabled recipients that are used to build the dynamic distribution group. RecipientFilter cannot be used if any of the following parameters are specified:
RecipientFilter uses For more information about the filterable properties, see Filterable Properties for the -RecipientFilter parameter. |
||
|
Alias |
Optional |
System.String |
The Alias parameter specifies the alias of the dynamic distribution group. The value of Alias is used to generate the primary Simple Mail Transfer Protocol (SMTP) e-mail address for the dynamic distribution group. The value of Alias cannot contain spaces. If the Alias parameter is not specified, the value of the Name parameter is used for the value of the Alias parameter, with any spaces in the Name parameter converted to underscore characters (_). |
||
|
ConditionalCompany |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCompany parameter filters the mailbox users or mail-enabled contacts that are used to build the dynamic distribution group. When multiple values of the ConditionalCompany parameter are separated by commas, the OR Boolean operator is applied. |
||
|
ConditionalCustomAttribute1 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute1 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute10 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute10 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute11 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute11 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute12 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute12 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute13 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute13 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute14 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute14 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute15 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute15 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute2 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute2 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute3 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute3 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute4 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute4 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute5 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute5 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute6 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute6 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute7 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute7 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute8 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute8 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalCustomAttribute9 |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalCustomAttribute9 parameter specifies custom attributes. You can use these attributes to store additional information. |
||
|
ConditionalDepartment |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalDepartment parameter filters the mailbox users or mail-enabled contacts that are used to build the dynamic distribution group. ConditionalDepartment cannot be used if the RecipientFilter parameter is specified. When multiple values of ConditionalDepartment are separated by commas, the OR Boolean operator is applied. |
||
|
ConditionalStateOrProvince |
Optional |
Microsoft.Exchange.Data.MultiValuedProperty |
The ConditionalStateOrProvince parameter filters mailbox users or mail-enabled contacts that are used to build the dynamic distribution group. ConditionalStateOrProvince cannot be used if the RecipientFilter parameter is specified. When multiple values of ConditionalStateOrProvince are separated by commas, the OR Boolean operator is applied. |
||
|
Confirm |
Optional |
System.Management.Automation.SwitchParameter |
The Confirm parameter causes the command to pause processing and requires you to acknowledge what the command will do before processing continues. You don't have to specify a value with the Confirm parameter. |
||
|
DisplayName |
Optional |
System.String |
The DisplayName parameter specifies the name of the dynamic distribution group in the Exchange Management Console and in the Exchange global address list (GAL). If the DisplayName parameter is not specified, the value of the Name parameter is used for DisplayName. |
||
|
DomainController |
Optional |
Microsoft.Exchange.Data.Fqdn |
To specify the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory, include the DomainController parameter. |
||
|
OrganizationalUnit |
Optional |
Microsoft.Exchange.Configuration.Tasks.OrganizationalUnitIdParameter |
The OrganizationalUnit parameter specifies where to create the dynamic distribution group in Active Directory by using canonical name syntax. |
||
|
RecipientContainer |
Optional |
Microsoft.Exchange.Configuration.Tasks.OrganizationalUnitIdParameter |
The RecipientContainer parameter filters the recipients that are used to build the dynamic distribution group based on their location in Active Directory. The value of RecipientContainer can be the canonical name of an organizational unit (OU) or a domain. If you do not specify a value for RecipientContainer, the default search filter is the location of the dynamic distribution group in Active Directory. This location is specified by using the OrganizationalUnit parameter. |
||
|
TemplateInstance |
Optional |
System.Management.Automation.PSObject |
When an existing object is supplied to the TemplateInstance parameter, the command uses the configuration of that object to create a copy of the object. |
||
|
UseRusServer |
Optional |
System.String |
The UseRusServer parameter instructs the command to use the specified Mailbox server on which the Address List service is running to obtain and then set mailbox and Active Directory user attributes. The Address List service is a component in the Exchange System Attendant service. The Address List service creates and maintains Exchange-specific attribute values in Active Directory. You can use the Address List service to update recipient objects in a domain by using specific information, such as address list membership and e-mail addresses. |
||
|
WhatIf |
Optional |
System.Management.Automation.SwitchParameter |
The WhatIf parameter instructs the command to simulate the actions that it would take on the object. By using the WhatIf parameter, you can view what changes would occur without having to apply any of those changes. You don't have to specify a value with the WhatIf parameter. |
Note:Detailed Description
A dynamic distribution group queries Active Directory directory service mail-enabled objects and builds the group membership based on the results. The group membership is recalculated whenever an e-mail message is sent to the group. The query filters provided with Exchange are limited to any combination of the following parameters:
- ConditionalCompany
- ConditionalCustomAttribute N (where N is a
value from 1 through 15)
- ConditionalDepartment
- ConditionalStateOrProvince
- IncludedRecipients
You can also create any custom query using the RecipientFilter parameter.
To run the New-DynamicDistributionGroup cmdlet, the account you use must be delegated the following:
- Exchange Recipient Administrator role
For more information about permissions, delegating roles, and the rights that are required to administer Microsoft Exchange Server 2007, see Permission Considerations.
Input Types
Return Types
Errors
| Error | Description |
|---|---|
|
|
|
Exceptions
| Exceptions | Description |
|---|---|
|
|
|
Example
The following code examples show how to use the New-DynamicDistributionGroup command.
The first example creates a new dynamic distribution group that is named Marketing Group in the Users container in the Contoso.com domain. The Marketing Group dynamic distribution group contains all mailbox users or mail-enabled contacts found anywhere in the Contoso.com domain who have a Department field that contains "Marketing" or "Sales".
The second example uses the RecipientFilter parameter to create a dynamic distribution group that is named Pacific Northwest in the Users container in the Contoso.com domain. The Pacific Northwest dynamic distribution group contains all mailbox users found anywhere in the Contoso.com domain who have a State/Province field that contains "Washington" or "Oregon".
 Copy Code |
|
|---|---|
New-DynamicDistributionGroup -Name "Marketing Group" -Alias "Marketing_Group" -IncludedRecipients "MailboxUsers,MailContacts" -OrganizationalUnit "Contoso.com/Users" -ConditionalDepartment "Marketing","Sales" -RecipientContainer "Contoso.com"
New-DynamicDistributionGroup -Name "Pacific Northwest" -Alias "Pacific_Northwest" -OrganizationalUnit "Contoso.com/Users" -RecipientFilter {((RecipientType -eq 'UserMailbox') -and ((StateOrProvince -eq 'Washington' -or StateOrProvince -eq 'Oregon')))} -RecipientContainer "Contoso.com"
|
|