Creating Microsoft Lync Server 2010 Objects

[NextHop_Team]

First published on TECHNET on Jun 06, 2010

Windows PowerShell has some pretty strict standards when it comes to naming things. As you probably know by now, every PowerShell cmdlet consists of a verb and a noun. Not only that, but there are guidelines that define how a developer goes about choosing nouns, and some pretty strict guidelines that determine the verbs you can use. (Want to use the verb Assign? Nope, not on the list. However, the always-popular ForEach verb is up for grabs.)

The good thing about this? No matter what implementation of PowerShell you’re using (whether it’s the Microsoft Exchange Server implementation, the Microsoft Virtual Machine Manager implementation, the Microsoft Lync Server implementation, or any other implementation) if you want to create something new all you have to do is look for cmdlets that start with the verb New. (Why New and not Create? Because that’s what the Windows PowerShell team chose, so that’s what’s on the approved list. Besides, it’s shorter, and less typing is always good.)

Which is all just our way of saying that, in this section, we’ll show you how to use the New cmdlets to create objects in Microsoft Lync Server 2010.

Creating objects

Creating an object in Lync Server PowerShell can be very simple. Here’s an example of how to create a new Address Book configuration:

New-CsAddressBookConfiguration –Identity site:Redmond

That’s it. When you hit Enter, this is what you’ll see:

Identity                   : Site:Redmond

RunTimeOfDay               : 1:30 AM

KeepDuration               : 30

SynchronizePollingInterval : 00:05:00

MaxDeltaFileSizePercentage : 20

UseNormalizationRules      : True

IgnoreGenericRules         : False

EnableFileGeneration       : True

You now have a new configuration for Address Book servers found on the Redmond site. The configuration settings were assigned default values; all you had to do was run one simple cmdlet. To make sure things worked as expected, type Get-CsAddressBookConfiguration | Select-Object Identity and press ENTER. You should get back something that looks like this:

Identity

--------

Global

Site:Redmond

You should see two items: the Global collection of Address Book configuration settings (which is created when you install Lync Server), and the site collection we just added. Success!

Of course, if you don’t want your new Address Book configuration settings to use only the default values, you can customize the settings as part of the object creation process. For example, suppose you want to create new Address Book configuration settings for the Dublin site, but you want the Address Book servers to synchronize with Active Directory every 10 minutes instead of the default value of every 5 minutes. That’s easy enough; just add another parameter to your command:

New-CsAddressBookConfiguration –Identity site:Dublin –SynchronizePollingInterval 00:10:00

Press ENTER and you’ll have another new Address Book configuration, this time for the Dublin site.

Keep in mind that if you try to use the Identity for an object that already exists (for example, if you try to create a new collection of Address Book settings for the Dublin site, and the Dublin site already has a collection of Address Book settings) you’ll receive an error similar to this:

PS C:> New- CsAddressBookConfiguration site: Dublin

New-CsAddressBookConfiguration : “AddressBookConfiguration” with identity “Site: Dublin” already exists.

Note . For more on identities see the Identities article .

Creating without Committing

As we mentioned up front, we think this is a pretty good way of doing things – you say you want something new, and you get something new. But what if, for some reason, you don’t want this new object to be created immediately? For example, suppose you want to create the object in memory, change some properties, take a look at it, then commit it. Or what if you simply want to see what the default values would be if you did create this object? In either case, you can use the -InMemory parameter:

New-CsAddressBookConfiguration site:Dublin –InMemory

When you type the preceding command this will be your output:

Identity                   : Site:Dublin

RunTimeOfDay               : 1:30 AM

KeepDuration               : 30

SynchronizePollingInterval : 00:05:00

MaxDeltaFileSizePercentage : 20

UseNormalizationRules      : True

IgnoreGenericRules         : False

EnableFileGeneration       : True

The first thing to notice is that we didn’t get an error message. That’s because the New- CsAddressBookConfiguration cmdlet didn’t actually try to create the configuration in the system; as a result, it didn’t bother checking to see if that Identity was already in use. The next thing to notice is that the SynchronizePollingInterval is set to 5 minutes (00:05:00) rather than the 10 minutes we had specified when we created the Dublin site earlier. The reason is because, when you call a New cmdlet with the -InMemory parameter, PowerShell doesn’t try to create anything; instead, it simply shows you what would be created if you ran the cmdlet as-is without the InMemory parameter . Or, in this case, what would happen if you created a new collection of Address Book configuration settings for the Dublin site.

Let’s try it with a new site, just so we can really see how it works. For example, this time we’ll create a configuration for our Paris site, but only in memory:

New-CsAddressBookConfiguration site:Paris –InMemory

Now we’ll again run the command that retrieves all our Address Book configurations: Get-CsAddressBookConfiguration | Select-Object Identity . When we press Enter this is what we see:

Identity

--------

Global

Site:Redmond

Site:Dublin

As you can see, the Paris site isn’t there. That’s because we created it only in memory; we never officially committed the new settings to the system.

By default, any time you use the –InMemory parameter a new object is temporarily created in memory and then disappears the moment the command finishes running. If you want to save the object you just created you must assign the object to a variable, like this:

$a = New-CsAddressBookConfiguration site:Paris –InMemory

This time when you press ENTER you won’t see any output. That’s because the object (and its property values) is being stored in the variable $a instead of being displayed onscreen. If you want to see the property values for the new object just type the following at the Windows PowerShell prompt and then press ENTER:

$a

After your object is stored in a variable you can then make changes to that object. For example:

$a.KeepDuration = 10

$a.SynchronizePollingInterval = "00:15:00"

If you look at the value of $a now it should look like this, with new values for the KeepDuration and SynchronizePollingInterval properties:

Identity : Site:Paris

RunTimeOfDay : 1:30 AM

KeepDuration : 10

SynchronizePollingInterval : 00:15:00

MaxDeltaFileSizePercentage : 20

UseNormalizationRules : True

IgnoreGenericRules : False

What can you do with $a now? Well, that’s up to you. If you want to turn this virtual collection of settings into a real collection of Address Book configuration settings applied to the Paris site just type the following:

Set-CsAddressBookConfiguration -Instance $a

To be perfectly honest, we aren’t sure how useful this is, but it does let you create a new collection of Address Book configuration settings by using a series of commands like these:

$a = New-CsAddressBookConfiguration site:Paris –InMemory

$a.KeepDuration = 10

$a.SynchronizePollingInterval = "00:15:00"

Set-CsAddressBookConfiguration -Instance $a

Alternatively, you can accomplish the same thing with a single (albeit lengthier) command:

New-CsAddressBookConfiguration site:Paris -KeepDuration 10 -SynchronizePollingInterval "00:15:00"

It’s up to you. After all, there’s no accounting for taste.

Just ask the author, the one who painted her entire living room orange.