Setting Property Values

If you’ve worked with Windows PowerShell in the past then you may have gotten used to changing a property value for an object by using commands like these:

$x = Get-ChildItem C:\Scripts\Test.ps1
$x.IsReadOnly = $True

What happens when you run a couple of commands like this? That’s easy: first you create an object reference (a variable that, in this case, points to the file C:\Scripts\Test.ps1), then change the value of the IsReadOnly property to True. Pretty simple, and pretty straightforward.

So how well does this knowledge of PowerShell transfer to Microsoft Lync Server 2010? Let’s take a look. First, let’s run a simple little command that returns information about the global Address Book server configuration settings:

Get-CsAddressBookConfiguration –Identity global

Now let’s take a peek at the information we get back:

Identity : Global
RunTimeOfDay : 1:30 AM
KeepDuration : 7
SynchronizePollingInterval : 00:00:20
MaxDeltaFileSizePercentage : 20
UseNormalizationRules : True
IgnoreGenericRules : False

Looks pretty good, doesn’t it? Well, except for one thing: we’ve decided to change the value of the property IgnoreGenericRules from False to True. How do we do that? Let’s use the tried-and-true PowerShell approach: we’ll create an object reference to the global Address Book configuration settings and then simply change the value of IgnoreGenericRules to True. In other words, let’s do this:

$x = Get-CsAddressBookConfiguration –Identity global
$x.IgnoreGenericRules = $True

When we execute those two commands, we don’t get an error message of any kind; that might lead you to believe that everything is hunky dory. Just to be on the safe side, however, let’s run the command Get-CsAddressBookConfiguration –Identity global and make sure everything really is hunky-dory. Here’s what we get back:

Identity : Global
RunTimeOfDay : 1:30 AM
KeepDuration : 7
SynchronizePollingInterval : 00:00:20
MaxDeltaFileSizePercentage : 20
UseNormalizationRules : True
IgnoreGenericRules : False

Perfect! Well, except for the fact that the value of the IgnoreGenericRules property remains unchanged. But other than the fact that the one thing we tried to do failed miserably, things went pretty well, don’t you think?

So what’s the deal here, why didn’t the property value change? Actually, there’s a good reason for that: although there might be an exception or two, this is simply not the way you modify property values in Microsoft Lync Server. Instead of creating an object reference and then using standard dot notation to modify property values, property values are modified by using the appropriate Set-Cs cmdlet.

Note. So what the heck is “dot notation?” Good question. You may have noticed that, in our failed example, we created an object reference named $x; an object reference is simply a variable that points to an object of some kind. (In this case, that object happens to be the global Address Book Configuration settings.) Dot notation simply involves taking the object name ($x), followed by a period (or dot) followed by a property name. Want to know the value of $x’s IgnoreGenericRules property? Then just type the following at the PowerShell prompt and press ENTER:

$x.IgnoreGenericRules

That’s what dot notation is.

Now, where were we? Ah, yes: modifying property values by using the appropriate Set-Cs cmdlet. To explain how this works, first type the following command at the PowerShell prompt and then press ENTER; PowerShell should respond by showing you the name of all the cmdlets that deal with Address Book configuration settings:

Get-Command *CsAddressBookConfiguration | Select-Object Name

Tip. Here’s another way to get at that information:

Get-Command –Noun CsAddressBookConfiguration | Select-Object Name

Just in case you like having options when it comes to retrieving cmdlet names.

We should get back to the following names:

Get-CsAddressBookConfiguration
New-CsAddressBookConfiguration
Remove-CsAddressBookConfiguration
Set-CsAddressBookConfiguration

Notice we have a cmdlet named Get-CsAddressBookConfiguration; that’s the cmdlet we use to get information about our Address Book configuration settings. And if we want to – well, you’re way ahead of us: yes, if we want to set Address Book configuration settings we use the Set-CsAddressBookConfiguration cmdlet. So then how, exactly, do we change the value of the IgnoreGenericRules property? Like this:

Set-CsAddressBookConfiguration –Identity –IgnoreGenericRules $True

See how that works? To modify an Address Book configuration setting we simply call Set-CsAddressBookConfiguration, along with the desired parameter (or parameters). We want to change the value of the IgnoreGenericRules property so we use the – well, whatta ya know: we use the –IgnoreGenericRules parameter.

By the way, that’s no coincidence: in the Lync Server implementation of Windows PowerShell there’s a very nice correlation between property names and parameter names. For example, let’s compare the properties returned by Get-CsAddressBookConfiguration with the parameters available when using Set-CsAddressBookConfiguration (we’ve left off some of the “ubiquitous” parameters such as –WhatIf and –Confirm):

Pretty nice, huh? If you want to change multiple property values then include multiple parameters in your command:

Set-CsAddressBookConfiguration –Identity global –IgnoreGenericRules $True –KeepDuration 10 –MaxDeltaFileSizePercentage 15

This is actually kind of nice, because it lets you change multiple property values with a single command. With dot notation you’d have to use multiple commands to change all these property values:

$x = Get-CsAddressBookConfiguration –Identity global
$x.IgnoreGenericRules = $True
$x.KeepDuration = 10
$x.MaxDeltaFileSizePercentage = 15

And don’t fret: if you really, really want to use dot notation you still can. Admittedly, there’s a little bit of a catch: you’ll still have to call the appropriate Set-Cs cmdlet (and the –Instance parameter) at the end in order to make the changes stick. Nevertheless, this set of commands will change the global Address Book configuration settings:

$x = Get-CsAddressBookConfiguration –Identity global
$x.IgnoreGenericRules = $True
$x.KeepDuration = 10
$x.MaxDeltaFileSizePercentage = 15
Set-CsAddressBookConfiguration –Instance $x

It’s entirely up to you.

Incidentally, what happens if there’s a property returned by a Get-Cs cmdlet which doesn’t have a corresponding parameter in a Set-Cs cmdlet? For example, compare the properties of Get-CsSite with the parameters of Set-CsSite:

How are you supposed to use Set-CsSite to change the SiteType or the ParentSite? Well, that’s the whole idea: you can’t change the SiteType or ParentSite using Set-CsSite. If a property doesn’t have a corresponding parameter then that’s a read-only property. And while there might be some exceptions, that either means that the property can’t be changed, period, or that you need to use a whole ‘nother tool (such as Topology Builder) to modify that property.

By the way, the same thing is true if a Get-Cs cmdlet doesn’t have a corresponding Set-Cs cmdlet. For example, there’s a Get-CsPool cmdlet, but there’s no Set-CsPool cmdlet. What does that mean? It means this: you can’t use Windows PowerShell to change the properties of a pool. That might sound like a bummer, but look on the bright side: the absence of a Set-CsPool cmdlet lets you know, right away, and before you waste your time trying, that you can’t use PowerShell to change the properties of a pool.

Well, that seemed like a pretty bright side to us.