[This is preliminary documentation and is subject to change. Blank topics are included as placeholders.]

Creates a new collection of settings for an Address Book server. Users query Address Book files any time they search for a new contact.

Syntax


New-CsAddressBookConfiguration -Identity <XdsIdentity> [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-IgnoreGenericRules <$true \| $false>] [-InMemory <SwitchParameter>] [-KeepDuration <UInt32>] [-MaxDeltaFileSizePercentage <UInt32>] [-RunTimeOfDay <DateTime>] [-SynchronizePollingInterval <TimeSpan>] [-UseNormalizationRules <$true \| $false>] [-WhatIf [<SwitchParameter>]]

New-CsAddressBookConfiguration -Identity <XdsIdentity> [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-IgnoreGenericRules <$true | $false>] [-InMemory <SwitchParameter>] [-KeepDuration <UInt32>] [-MaxDeltaFileSizePercentage <UInt32>] [-RunTimeOfDay <DateTime>] [-SynchronizePollingInterval <TimeSpan>] [-UseNormalizationRules <$true | $false>] [-WhatIf [<SwitchParameter>]]

Parameters

Parameter	Required	Type	Description
Identity	Required	XdsIdentity	Represents the unique identifier to be assigned to the new collection of Address Book settings. Because you can only create new collections at the site scope, the Identity will always be the prefix "site:" followed by the site name; for example "site:Redmond".
IgnoreGenericRules	Optional	Boolean	Indicates whether the Address Book server will ignore the generic normalization rules used when parsing phone numbers. Generic rules are the rules that are built into Communications Server 2010. These rules cannot be changed; however, by setting the value of this property to True you can instruct your Address Book servers not to use these rules, but to use custom rules that you create yourself. The default value is False.
KeepDuration	Optional	TimeSpan	Specifies the amount of time (in days) that Address Book servers will keep change files. Change files older than the value of the KeepDuration property will be deleted. Minimum value: 1.00:00:00 (1 Day) Maximum value: 90.00:00:00 (90 Days) Default value: 30.00:00:00 (30 Days)
MaxDeltaFileSizePercentage	Optional	Integer	When changes are made to Active Directory (such as a new user being enabled for Communications Server) the Address Book server typically records these changes in a "delta file," a file consisting only of the updated information; Communicator can then download the delta files rather than a complete Address Book file. The MaxDeltaFileSizePercentage property determines how large the delta files can get before they are incorporated into the complete Address Book file. By default, delta files can be as large as 20 percent of the complete Address Book file before a new Address Book file is generated. At that point, Communicator clients will download the complete file rather than a delta file. MaxDeltaFileSizePercentage must be entered as a percentage value, from 1 to 100, inclusive.
RunTimeOfDay	Optional	DateTime	Indicates the time of day when the servers generate new Address Book files. The RunTimeOfDay property is based on a 24-hour clock (hours:minutes:seconds), with 00:00:00 representing midnight and 23:59:00 representing 11:00 PM. The default value is 01:30:00 (1:30 AM).
SynchronizePollingInterval	Optional	TimeSpan	Indicates how often Address Book severs synchronize their information with the information stored in AD DS. Minimum value: 00:00:05 (5 seconds). Maximum value: 03:00:00 (3 hours). Default value: 00:05:00 (5 minutes).
UseNormalizationRules	Optional	Boolean	Indicates whether Address Book servers should use phone normalization rules when retrieving phone numbers. If set to False, phone numbers will be retrieved as-is and it will be up to the client application to apply normalization rules when displaying these numbers. The default value is True.
InMemory	Optional	Switch Parameter	Creates an object reference without actually committing the object as a permanent change. If you assign the output of this cmdlet called with this parameter to a variable, you can make changes to the properties of the object reference and then commit those changes by calling this cmdlet’s matching Set- cmdlet.
Force	Optional	Switch Parameter	Suppresses the display of any non-fatal error message that might arise when running the command.
WhatIf	Optional	Switch Parameter	Describes what would happen if you executed the command without actually executing the command.
Confirm	Optional	Switch Parameter	Prompts you for confirmation before executing the command.

Detailed Description

When people use Microsoft Communicator to search for new contacts they typically do not search Active Directory itself; that’s because hundreds of simultaneous Active Directory searches run the risk of bogging down both your network and your domain controllers. Instead, users searching for contacts typically search through local files generated by an Address Book server.

Address Book servers are intermediaries between Active Directory Domain Services and Microsoft Communications Server 2010. The Address Book server ensures that the user information stored in Communications Server 2010 is in synch with the user information stored in Active Directory. In addition, Address Book servers periodically generate address book files that are downloaded to computers running Communicator. When a person uses Communicator to search for contacts, he or she will typically search through the address book files stored on the local computer. That makes searches much faster, and reduces wear on the network and on the domain controllers. This also explains why you can only search for contacts using a limited number of search fields: that’s because Address Book files contain only a relatively small subset of the information stored in Active Directory.

Address Book servers are governed using Address Book configuration settings; these settings determine such things as how often Address Book servers are synchronized with Active Directory and how often Address Book files are generated. When you install Communications Server, a set of global Address Book settings is created for you. You can also create custom configuration settings that can be applied to individual sites. These site configurations, if they exist, apply to any Address Book servers operating in the site, and always take precedence over the global settings.

Site-level settings are created using the New-CsAddressBookConfiguration cmdlet. You can only create settings at the site scope; trying to create new settings anywhere else, including at the global scope, will fail. Your command will also fail if the site in question already contains a collection of Address Book settings.

Return Types

Creates instances of the Microsoft.Rtc.Management.WriteableConfig.Settings.AddressBook.AddressBookSettings object.

Examples

-------------------------- Example 1 --------------------------

	Copy Code
New-CsAddressBookConfiguration -Identity site:Redmond -KeepDuration 15.0:00:00 -SynchronizePollingInterval 00:10:00

The preceding example creates a new collection of Address Book server settings with the identity site:Redmond. To create the new collection you must call the New-CsAddressBookConfiguration cmdlet along with the Identity parameter and any other optional parameters (for example, the KeepDuration parameter, which specifies the number of days that Address Book change files are retained).

-------------------------- Example 2 --------------------------

	Copy Code
$x = Get-CsAddressBookConfiguration -Identity site:Redmond New-CsAddressBookConfiguration -Identity site:Paris -KeepDuration $x.KeepDuration -SynchronizePollingInterval $x.SynchronizePollingInterval

Example 2 creates a new collection of Address Book settings for site:Paris; this new collection will share two values (KeepDuration and SynchronizePollingInterval) copied from the site:Redmond collection. To carry out this task, the first command uses Get-CsAddressBookConfiguration to return a collection of all the Address Book settings configured for site:Redmond; this information is stored in a variable named $x. The second command then uses New-CsAddressBookConfiguration to create Address Book settings for site:Paris. This second command includes two optional parameters--KeepDuration and SynchronizePollingInterval--that include values copied from site:Redmond. For example, KeepDuration uses the parameter value $x.KeepDuration. In other words, the value stored in the KeepDuration property of $x, the variable containing information copied from the Redmond site.

-------------------------- Example 3 --------------------------

	Copy Code
$x = New-CsAddressBookConfiguration -Identity site:Redmond -InMemory $x.KeepDuration = 15. $x.SynchronizePollingInterval = "00:10:00" Set-CsAddressBookConfiguration -Instance $x

Example 3 shows how you can use the InMemory parameter to create an in-memory-only instance of an Address Book settings collection, modify those settings in memory, then use Set-CsAddressBookConfiguration to create an actual collection with the Identity site:Redmond. To accomplish all that, the first command creates a new in-memory-only instance of an Address Book settings configuration, storing that instance in a variable named $x. The InMemory parameter ensures these Address Book settings will exist only in memory; if you were to terminate your Windows PowerShell session or delete the variable $x, the settings will disappear and will never be applied to the Redmond site.

In commands 2 and 3, two properties of this "virtual" Address Book settings collection are modified: command 2 sets the value of the KeepDuration property to 15 days (15.) and command 3 sets the SynchronizePollingInterval to 10 minutes (00:10:00). The fourth and final command then uses Set-CsAddressBookConfiguration and the Instance parameter to transform the virtual Address Book settings into an actual collection of setting configured at the Redmond site.