Microsoft Lync Server 2010: PowerShell Changes from Beta to Beta Refresh – Lite Version

The beta refresh version of Microsoft Lync Server 2010 (formerly known as Communications Server "14") is now out, and, as you might expect, the software – and its implementation of Windows PowerShell – have changed quite a bit in the past few months. What follows is a quick overview of some of the major PowerShell changes that have taken place from beta to beta refresh. To be honest, in this article we pretty much note the changes that have been made; we don’t spend much time explaining why the changes were made, or how those changes really affect you. If you’d prefer a little more information (as opposed to a little less information) then take a look at our comprehensive overview of the PowerShell changes from beta to beta refresh.

New Cmdlets

For the most part, there haven’t been that many changes between beta and beta refresh. A few cmdlets have been deleted (e.g., Install-CsClientUpdate and Get-CsConferenceAccessNumberList) and a few have been renamed (for example, Get-CsUserClusterInfo is now known as Get-CsUserPoolInfo). And there are a few new cmdlets, most notably:

· The new Kerberos cmdlets. In Office Communications Server 2007 R2, Internet Information Service (IIS) ran under a standard user account. That was fine, except that many organizations don’t allow standard user accounts to have non-expiring passwords. In turn, that meant that, sooner or later, your IIS password is going to expire and, when it does, you’re going to run into problems. The new Kerberos cmdlets help minimize this problem by enabling you to create a single account that all the IIS servers in a site can run under.

· The new audio conferencing provider cmdlets. An audio conferencing provider is a third-party company that provides organizations with conferencing services (including, in some cases, fancy stuff like live translation, transcription, and live per-conference operator-assistance). The new CsUserAcp cmdlets (like New-CsUserAcp and Set-CsUserAcp) make it easy for you to assign (and unassign) audio conferencing providers to your users.

· The new presence policy cmdlets. These new cmdlets (e.g., Set-CsPresencePolicy) let you manage the maximum number of prompted subscribers and category subscriptions a user can have.

New/Newly-Renamed Parameters

There have been far too many parameter changes (and name changes) for us to list in this article. However, there are at least two changes that affected scores of cmdlets, and that you should probably know about. We’d be very surprised if anyone out there made extensive use of either of these two parameters, but just in case keep in mind that:

· The LocalStore parameter has been deleted from most cmdlets. The LocalStore parameter tells a cmdlet to retrieve Lync Server data from the local replica rather than directly querying the Central Management database for the latest and most up-to-date version of that data. There are times when this can be useful, primarily when you’re working on an Edge Server that doesn’t have access to the Central Management database or when replication seems to have failed for some reason. However, for most cmdlets, and most occasions, LocalStore has no use. Therefore, the parameter has been deleted from all but a handful of Lync Server cmdlets.

· The Tenant parameter has been deleted from most cmdlets. The Tenant parameter was designed for working with the "in the cloud" version of Lync Server (Lync Server Online); that means it’s of no use to the on-premises Administrator. (That’s you.) Therefore, with one or two exceptions, the Tenant parameter has been deleted from all the core Lync Server cmdlet.

New Service Identities

Remember how much fun it used to be typing in service Identities? You know, cryptic identifiers similar to this one:

service:Redmond-Registrar-1

If you don’t remember how much fun it was typing in cryptic service Identities, well, don’t feel bad: we’ve yet to find anyone who did like the old service Identities. Which is one reason why service Identities now look like this:

Registrar:redmond-cs-001.litwareinc.com

As long as we’re on the subject, we should note that the service: prefix is now optional; if you really wanted to, you could type a service Identity like this:

service:Registrar:redmond-cs-001.litwareinc.com

Admittedly, you probably have no burning desire to do any extra typing. However, the fact that the service: prefix still exists does mean that you can still use the Filter parameter to filter for services configured at the service scope. For example:

Get-CsClientVersionPolicy –Filter "service:*"

New Behavior When Removing Per-User Policies

In the beta version of Lync Server 2010 you could delete a per-user policy by using a command similar to this:

Remove-CsConferencingPolicy –Identity "RedmondConferencingPolicy"

That command still works. However, if the policy in question (in this case, RedmondConferencingPolicy) is currently assigned to at least one user the policy won’t immediately be deleted. Instead, you’ll need to answer Yes to the following prompt before the policy will actually be removed:

The policy "Tag:RedmondConferencingPolicy" is currently assigned to one or more users. Assign a different policy to the users before removing this one.

The policy is in use.

[Y] Yes [N] No [S] Suspend [?] Help (default is “Y”):

If you’d prefer not to have to deal with a confirmation prompt like that simply add the Force parameter when calling the command that deletes the policy. For example:

Remove-CsConferencingPolicy –Identity "RedmondConferencingPolicy" -Force

New Uses for the Force Parameter

If you take a careful look at the parameter set for a cmdlet there’s a good chance you’ll see a Force parameter. Keep in mind, however, that the Force parameter has different meanings depending on the cmdlet. In fact, the Force parameter can do any one of three things:

· Suppress the confirmation prompt that appears when you try to remove a per-user policy currently assigned to one or more users. If you aren’t sure what we’re talking about, see the preceding section of this article.

· Allow you to remove something even if it’s still being used elsewhere. For example, by default the Disable-CsAdDomain cmdlet will not roll back Active Directory domain settings if it detects that there’s still a Lync Server front end server, Conferencing server, or Web server running in the domain. But if you include the Force parameter? You got it: domain settings will be removed even if you still have, say, a Lync Server front end machine running in the domain.

· Suppress the display of any non-fatal errors that might pop up when you run a cmdlet. This is probably the most common use of the Force parameter. From time-to-time you might run a command and get assorted error messages that essentially say, “Well, there was a little problem. The command still ran, but we thought you’d like to know about this little issue.” If you’d prefer not to know about that little issue then simply add the Force parameter to the command.

New Way to Create Static Routes

If you tried to create a static route in the beta version of Lync Server 2010 there’s a pretty good chance that you gave up long before the route was actually created. It’s not that creating a static route was necessarily hard; it’s just that creating a static route required the use of several million cmdlets and several million child objects. Fortunately, things are a little easier in the beta refresh version. To create a static route in the beta refresh version all you need is one command and one cmdlet:

$x = New-CsStaticRoute –TLSRoute –Destination "atl-proxy-001.litwareinc.com" –Port 8025 –MatchUri "sip:*@litwareinc.com" –UseDefaultCert $True

New Behavior for the New-CsRgs Cmdlets

In the beta version of Lync Server the New-CsRgs cmdlets (cmdlets that created new Response Group objects) exhibited an interesting behavior: they didn’t actually create any new Response Group objects. Or, to be fair, they didn’t directly create any new Response Group objects. Instead, the New-CsRgs cmdlets would create an object that existed only in memory; you’d then have to use a corresponding Set-CsRgs cmdlet to actually create something.

With the beta refresh version of Lync Server you no longer have to worry about that; now you can create a Response Group agent group with just one command:

New-CsRgsAgentGroup –Parent ApplicationServer:atl-cs-001.litwareinc.com –Name "Help Desk"

New Behavior for the New-CsVoiceNormalizationRule Cmdlet

In Lync Server, voice normalization rules have to be associated with a dial plan; a voice normalization rule cannot exist on its own. So what happens if you try to create a new normalization rule and you associate that rule with a dial plan that doesn’t exist? Well, in the beta version of Lync Server the New-CsVoiceNormalizationRule cmdlet would go ahead and create the dial plan for you. For example, suppose you gave a voice normalization rule the Identity site:Redmond/TestRule but no dial plan actually existed for the Redmond site. No problem; New-CsVoiceNormalizationRule would create a new dial plan with the Identity site:Redmond.

That is definitely not the case in the beta refresh version of Lync Server. If you try the same thing now – that is, you try to create a new normalization rule and you associate that rule with a dial plan that doesn’t exist – then your command will fail. New-CsVoiceNormalizationRule will no longer create dial plans for you.

New Naming Behavior for Dial Plans

While we’re on the topic of dial plans, there are a couple of changes that have been made to the dial plan cmdlets. The first is a simple parameter rename: in beta you gave the dial plan a name by putting a value in the Name parameter. Now you give the dial plan a name by putting a value in the SimpleName parameter. Name has been renamed to SimpleName.

Another change is that the SimpleName property of a dial plan must be unique across all dial plans. For example, if you have a per-user dial plan with the Identity RedmondDialPlan and the SimpleName DialPlan1, you can’t also have a dial plan with the Identity site:Redmond (or any other Identity) and the SimpleName DialPlan1.

New Names: Get-CsPstnUsage and Set-CsPstnUsage

This is a relatively minor change, but definitely one you need to be aware of: the CsPhoneUsage cmdlets have been given new names in the beta refresh version of Lync Server:

New Look for the RBAC Cmdlets

RBAC (Role Based Access Control) has been introduced in Lync Server 2010 as a way to help delegate administrative control of the software; for example, rather than making a user a full-fledged, and all-powerful, Administrator you can give that user the right just to manage user accounts or just to manage archiving activities. In addition, you can also limit the scope of these administrative rights: for example, you might give someone the right to manage users, but only users in the Redmond site or in the Finance OU.

As you might expect, there have been a couple of major changes to RBAC since the beta version of Lync Server was released. First, the RBAC roles have been modified: the beta refresh version does not use the same RBAC roles as the beta version, and the cmdlets assigned to some of those roles have changed as well.

The second major change involves custom roles. You can still create custom roles in the beta version of Lync Server; for example, you might create a custom Server Administrator role (based on the CsServerAdministrator role) and then give that custom role management rights only to a specified site or a specified OU. Nothing has changed there. However, the one thing that has changed is that you can no longer add new cmdlets to a custom role nor can you remove any of the cmdlets assigned to a custom role.

New Way to Unassign a Per-User Policy

Although it has always been possible to unassign per-user policies assigned to a user, the way you went about carrying out this task was never very intuitive. How did you carry out this task? By calling the appropriate Grant-Cs cmdlets, but without specifying a policy name. For example, in beta this command unassigns the per-user conferencing policy assigned to Ken Myer:

Grant-CsConferencingPolicy –Identity "Ken Myer"

In order to make things a little bit clearer this behavior has been changed in the beta refresh version of Lync Server. Now the only way to unassign a per-user policy assigned to a user is to use the PolicyName parameter but set the parameter value to null ($Null). For example:

Grant-CsConferencingPolicy –Identity "Ken Myer" –PolicyName $Null

New Priority Property Added to the Dial-In Conferencing Cmdlets

You can’t really call it a problem, but one minor issue with dial-in conferencing for the beta version of Lync Server was this: when you created new dial-in conferencing access numbers you couldn’t control the order in which these numbers appeared on the Dial-In Conferencing Settings and PIN Management Web page. Instead, these numbers just showed up in the order they were created.

In the beta version of Lync Server there wasn’t much you could do about that. That’s not true in the beta refresh version, however. Now, thanks to the Priority and ReorderedRegion parameters, you can run a command like this one:

Get-CsDialConferencingAccessNumber | Where-Object {$_.DisplayNumber –eq "1-425-555-1298"} | Set-CsDialinConferencingAccessNumber –Priority 0 –ReorderedRegion "Bellevue"

The net effect of running this command? The phone number 1-425-555-1298 will be listed first on the dial-in conferencing Web page for the Bellevue region. (How do we know it will be listed first? Because we assigned it a Priority of 0. When it comes to dial-in conferencing, the first phone number listed for a region will be the number with Priority 0. The second number listed will be the number with the Priority 1; the third number listed will be the one with the Priority 2; and so on.)

Newly-Updated Cmdlet Help

Help is now available for all the PowerShell cmdlets that ship with the beta refresh version of Lync Server 2010. (Well, there might be one or two exceptions: they may have slipped a cmdlet or two into the build at the last moment.) Be forewarned, however, that a technical glitch is currently preventing a few help topics from showing up within PowerShell itself. (To see what we mean, type Get-Help New-CsSipDomain –Full from the PowerShell prompt.) Fortunately, the TAP program makes a documentation pack available that includes help files named RTCCmdlets.chm and RGSCmdlets.chm. RTCCmdlets.chm contains all the help for the Lync Server cmdlets, except for the Response Group cmdlets. Help for those cmdlets can be found in RGSCmdlets.chm.

If you have the beta refresh version of Lync Server but for some reason don’t have access to the TAP downloads, send an email to cspshell@microsoft.com and we’ll see what we can do for you.

New Requirements for Simple URL Configurations

In the beta version of Lync Server the New-CsSimpleUrlConfiguration cmdlet provided a way for you to create simple URL configuration settings; the only stipulation was that your new settings had to specify a URL for meetings (the Meet component). The stipulations have changed in the beta refresh version of Lync Server. You can still create your own simple URL settings at the site scope; however, that new collection of simple URL settings must meet the following criteria:

· You must have an active meeting URL.

· You must have an active dial-in URL.

· The domain property for the initial dial-in URL must be set to this: *. (Strange, but true!)

In other words, the only way to create a new collection of simple URL configuration settings is to use a series of commands similar to these:

$simpleUrlEntry1 = New-CsSimpleUrlEntry -Url "https://dialin.litwareinc.com"

$simpleUrlEntry2 = New-CsSimpleUrlEntry -Url "https://meet.litwareinc.com"

$simpleURL1 = New-CsSimpleUrl -Component "dialin" -Domain "*" -SimpleUrlEntry $simpleUrlEntry1 -ActiveUrl "https://dialin.litwareinc.com"

$simpleURL2 = New-CsSimpleUrl -Component "meet" -Domain "litwareinc.com" -SimpleUrlEntry $simpleUrlEntry2 -ActiveUrl "https://meet.litwareinc.com"

New-CsSimpleUrlConfiguration -Identity site:Redmond -SimpleUrl @{Add=$simpleUrl1, $simpleUrl2}

Note that these changes were made right before the beta refresh version shipped, and before the help could be updated; as a result, the help for New-CsSimpleUrlConfiguration isn’t really all that helpful. If you want to create a new collection of simple URLs settings, you can use the existing help topic for an explanation of the different parameters. However, you should use the preceding set of commands as an example of how to create a collection of simple URL configuration settings that actually work.

Newly-Departed: Disconnect-CsUser

To be honest, we’re can’t remember whether the Disconnect-CsUser cmdlet appeared in the beta version of Lync Server or not; because of that, we should make it clear that Disconnect-CsUser is definitely not in the beta refresh version. Instead, we’re now down to two ways to disable Lync Server user accounts:

· If you want to permanently disable a user account (that is, if you want to wipe out all the Lync Server attributes associated with that account) then run the Disable-CsUser cmdlet.

· If you want to temporarily disable a user account (leaving all the policy assignments and other Lync Server attributes as-is) then run the Set-CsUser cmdlet and set the CsEnabled property to False:

Set-CsUser –Identity "Ken Myer" –CsEnabled $False

To re-enable Ken Myer for Lync Server just flip the switch and set CsEnabled back to True:

Set-CsUser –Identity "Ken Myer" –CsEnabled $True

New Requirement for the Cmdlets Using the InMemory Parameter

Here’s another change that might actually have been made before beta but, since we can’t remember one way or the other, we thought we should make note of it. As you probably know, the InMemory parameter provides a way for you to create a new object that, in the beginning, exists only in memory. For example, the following command creates a new client policy that doesn’t actually get applied to the Redmond site; instead, it simply gets stored in the variable $x:

$x = New-CsClientPolicy –Identity "site:Redmond" –InMemory

So how do you turn that virtual policy into a real policy, a policy applied to the Redmond site? Well, back in the old days, you’d run a command similar to this:

Set-CsClientPolicy $x

That was then, however, and this is now. Now (that is, in the beta refresh version), any time you try to turn an in-memory-only object into a real object you need to include the Instance parameter, like so:

Set-CsClientPolicy –Instance $x

New Report Format: HTML

Reports generated by Lync Server cmdlets are now saved in HTML format rather than XML format. Is that important to know? Yes, assuming you’re using the Report parameter to provide a file path for the generated report. If you are, then just make sure you use a .htm or .html file extension. For example:

Test-CsComputer –Report C:\Logs\ComputerTest.html

Is That Everything You Need to Know About Windows PowerShell and Beta Refresh?

Probably not. But that’s OK; if you have questions or if you run into problems using the beta refresh software just drop us a line: cspshell@microsoft.com.

Comments

• Anonymous
  January 01, 2003
  Sorry, it's not publicly available yet, it's only availale to registered Beta customers right now. As soon as it's available to the public we'll update this blog with more info. Stay tuned.

• Anonymous
  August 20, 2010
  So where's the Beta Refresh? Where can we get it?