New-DynamicDistributionGroup

 

Applies to: Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3

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>]]

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

• ConditionalCustomAttributeN (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.

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: Name specifies the dynamic distribution group name in Active Directory Users and Computers and also in the Group Name field in the Exchange Management Console. DisplayName specifies the dynamic distribution group name in the Exchange Management Console, and in the Exchange global address list (GAL).
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: IncludedRecipients ConditionalCompany ConditionalCustomAttributeN (where N is a value from 1 through 15) ConditionalDepartment ConditionalStateOrProvince RecipientFilter uses OPath syntax to query Active Directory and filter recipients. 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	Note: This parameter is available only in Exchange Server 2007 SP2. 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.

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".

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"