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

Returns the client version policy rules configured for use in your organization.

Syntax

Get-CsClientVersionPolicyRule [-Identity <XdsIdentity>] [-LocalStore <SwitchParameter>]
Get-CsClientVersionPolicyRule [-Filter <String>] [-LocalStore <SwitchParameter>]

Parameters

Parameter Required Type Description

Identity

Optional

Xds Identity

Unique identifier for the client version policy rule to be retrieved. The Identity of a client version rule consists of the scope where the rule has been configured plus a globally unique identifier (GUID). That means that a rule will have an Identity similar to this: site:Redmond/1987d3c2-4544-489d-bbe3-59f79f530a83. Because GUIDs are so difficult to remember, and to work with, the Examples section lists alternate ways that you can identify the rules to be returned.

If this parameter is not specified then all the client version policy rules configured for use will be returned.

Filter

Optional

String

Enables you to use wildcard characters when specifying the client policy rules to be returned. For example, to return all the rules configured for the Redmond site, use this syntax: -Filter "site:Redmond/*".

You cannot use both the –Filter and the –Identity parameters in the same command.

LocalStore

Optional

Switch Parameter

This parameter is for testing purposes only.

Detailed Description

Client version rules are used to determine which client applications are allowed to log on to Microsoft Communications Server and which client applications are not allowed to log on. When a user attempts to log on to Communications Server, his or her client application sends a SIP header to the server; this header includes detailed information about the application itself, including the software’s major version, minor version, and build number. The version information included in the SIP header is then checked against a collection of client version rules to see if any rules apply to that particular application. For example, suppose a user attempts to log on using Office Communicator version 2.0. Before logon can take place, the system will check to see if there is a client version rule that applies to Office Communicator 2.0. If such a rule exists, Microsoft Communications Server will then take the action specified by the rule. That action must be one of the following:

Allow. The user will be allowed to log on.

AllowAndUpgrade. The user will be allowed to log on, and his or her copy of Office Communicator will automatically be upgraded to the latest version of Microsoft Communicator.

AllowWithUrl. The user will be allowed to log on, and a message will be displayed pointing him or her to a URL where the latest version of Microsoft Communicator can be downloaded and installed.

Block. The user will not be allowed to logon.

BlockAndUpgrade. The user will not be allowed to logon, but his or her copy of Office Communicator will automatically be upgraded to the latest version of Microsoft Communicator. The user can then try to logon on using the new client application.

BlockWithUrl. The user will not be allowed to log on, but a message will be displayed pointing him or her to a URL where the latest version of Microsoft Communicator can be downloaded and installed.

Client version rules are collected in client version policies, policies that can be configured at the global scope, the site scope, the service scope (Registrar service), or the per-user scope. This enables you to provide different users with different rules regarding the client applications they can or cannot use to log on to Microsoft Communications Server. For example, as a general rule you might want to prevent users from logging on using Office Communicator; after all, Office Communicator does not support the same features and capabilities as Microsoft Communicator. However, due to hardware or software conflicts you might also have a select group of users who cannot upgrade to Microsoft Communicator. In that case, you can create a separate rule – and a separate client version policy – that allows those users to log on from within Office Communicator.

The Get-CsClientVersionPolicyRule cmdlet provides a way for administrators to view detailed information about each of the policy rules configured for use in their organization.

Return Types

Get-CsClientVersionPolicyRule returns instances of the Microsoft.Rtc.Management.WriteableConfig.Policy.ClientVersion.Rule object.

Examples

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

Copy Code
Get-CsClientVersionPolicyRule

Example 1 returns information about all the client version policy rules currently in use in the organization.

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

Copy Code
Get-CsClientVersionPolicyRule -Identity "Global/2336c611-a243-4c5d-994b-eea8a524d0e4"

In Example 2, information about a single client version policy rule is returned: the policy rule that has the Identity Global/2336c611-a243-4c5d-994b-eea8a524d0e4.

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

Copy Code
Get-CsClientVersionPolicyRule -Filter "Global/*"

The preceding command returns all the client version policy rules that have been configured at the global scope. To do this, the command uses the -Filter parameter and the filter value "Global/*". That filter value returns only those policy rules that have an Identity that begins with the string value "Global/".

-------------------------- Example 4 ------------------------

Copy Code
Get-CsClientVersionPolicyRule | Where-Object {$_.Enabled -eq $False}

The command shown in Example 4 returns all the client version policy rules that are currently disabled. To carry out this task, the command first calls Get-CsClientVersionPolicy in order to return a collection of all the available client policy rules. This collection is then piped to the Where-Object cmdlet, which picks out the rules where the Enabled property is equal to (-eq) False ($False).

-------------------------- Example 5 ------------------------

Copy Code
Get-CsClientVersionPolicyRule | Where-Object {$_.Action -eq "Block"}

The preceding command returns all the client version policy rules that block a client application from logging on. To do this, the command first calls Get-CsClientVersionPolicy without any parameters; that returns a collection of all the policy rules currently in use. This collection is then piped to the Where-Object cmdlet, which selects only those rules where the Action property is equal to Block.

-------------------------- Example 6 ------------------------

Copy Code
Get-CsClientVersionPolicyRule | Where-Object {$_.UserAgent -like "*OC*"}

Example 6 returns all the client version policy rules pertaining to Office Communicator (OC). To achieve this, the command first uses Get-CsClientVersionPolicy to return a collection of all the policy rules. Those rules are then piped to Where-Object, which picks out only the items where the UserAgent property includes (-like) the string value "OC".