Creates a new client version policy rule. Client version policy rules help determine whether users can use a specific client application to log on to Microsoft Communications Server 2010.
Syntax
New-CsClientVersionPolicyRule -Identity <XdsIdentity> [-Action <Allow | AllowAndUpgrade | AllowWithUrl | Block | BlockAndUpgrade | BlockWithUrl>] [-ActionUrl <String>] [-BuildNumber <Nullable>] [-CompareOp <EQL | NEQ | GTR | GEQ | LSS | LEQ>] [-Confirm [<SwitchParameter>]] [-Description <String>] [-Enabled <$true | $false>] [-Force <SwitchParameter>] [-InMemory <SwitchParameter>] [-MajorVersion <UInt16>] [-MinorVersion <Nullable>] [-Priority <Int32>] [-QfeNumber <Nullable>] [-UserAgent <String>] [-UserAgentFullName <String>] [-WhatIf [<SwitchParameter>]] |
New-CsClientVersionPolicyRule -Id <String> -Parent <String> [-Action <Allow | AllowAndUpgrade | AllowWithUrl | Block | BlockAndUpgrade | BlockWithUrl>] [-ActionUrl <String>] [-BuildNumber <Nullable>] [-CompareOp <EQL | NEQ | GTR | GEQ | LSS | LEQ>] [-Confirm [<SwitchParameter>]] [-Description <String>] [-Enabled <$true | $false>] [-Force <SwitchParameter>] [-InMemory <SwitchParameter>] [-MajorVersion <UInt16>] [-MinorVersion <Nullable>] [-Priority <Int32>] [-QfeNumber <Nullable>] [-UserAgent <String>] [-UserAgentFullName <String>] [-WhatIf [<SwitchParameter>]] |
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
|
Identity |
Required |
Xds Identity |
Unique identifier for the client version policy rule to be created. 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. Instead of using the –Identity parameter you can use the –Parent and –Id parameters and have |
|
MajorVersion |
Required |
Integer |
Major version of the software. For example, if your copy of Office Communicator is version 2.0.6362.111 then the MajorVersion is 2. Major versions equate to primary releases of the software. |
|
MinorVersion |
Optional |
Integer |
Minor version of the software. For example, if your copy of Office Communicator is version 2.0.6362.111 then the MinorVersion is 0. Minor versions equate to interim releases of the software. |
|
UserAgent |
Required |
String |
Designator used to identify the software client. For example, OC is the user agent designation for Office Communicator. The Get-CsClientVersionConfiguration provides corresponding friendly names for each user agent designation. |
|
Parent |
Optional |
String |
Scope information for the new rule. To use the –Parent parameter and create a new rule for the global policy use this syntax: -Parent global. To create a new rule for a site policy, use syntax like this: -Parent "site:Redmond". To create a new rule for a service policy, use syntax similar to the following: -parent "service;Redmond-Registrar-1". And to create a new rule for a per-user policy use syntax like this: -Parent "RedmondClientVersionPolicy". You must use either the –Identity parameter or both the –Parent and –Id parameters when creating a new rule. |
|
Id |
Optional |
Guid |
Globally unique identifier (Guid) for the rule. In Windows PowerShell, you can create a Guid using the following command: $x = [guid]::NewGuid() |
|
Description |
Optional |
String |
Enables administrators to provide additional information about the client version rule. For example, the Description might include information about who to contact if you believe the rule should be changed. |
|
Action |
Optional |
PS List Modifier |
Action to be taken any time the rule is triggered (that is, any time someone attempts to log on using the specified software). Valid values are: Allow. The user will be allowed to log on. 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. 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. Block. The user will not be allowed to logon. 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. 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. |
|
ActionFolder |
Optional |
String |
Path on the server pointing to the latest version of Microsoft Communicator (for example, D:\Donwloads\Client\Update32.exe). This property is required if the Action is set to BlockWithUpgrade or AllowWithUpgrade |
|
ActionUrl |
Optional |
String |
URL where users can download the latest version of Microsoft Communicator. This property is required if the Action is set to BlockWithUrl or AllowWithUrl |
|
BuildNumber |
Optional |
Integer |
Build number of the software. For example, if your copy of Office Communicator is version 2.0.6362.111 then the BuildNumber is 6362. Build numbers represent internal versions of the software during the development process, and help to ensure that you are using the final release version as opposed to a pre-release version. |
|
QfeNumber |
Optional |
Integer |
Quick fix engineering number of the software. For example, if your copy of Office Communicator is version 2.0.6362.111 then the QfeNumber is 111. QFE numbers represent planned updates to an application that are made available after the software’s official release. |
|
UserAgentFullName |
Optional |
String |
Friendly name corresponding to the UserAgent. |
|
Enabled |
Optional |
Boolean |
Indicates whether or not the client version rule is to be used. If the Enabled property is set to False ($False) then the rule will be ignored any time a user attempts to log with the specified software. |
|
CompareOp |
Optional |
PS List Modifier |
Comparison operator used to determine if the client software attempting to log on was released before, after, or at the same time as the version specified in the rule. Valid values are: EQL (equal to) NEQ (not equal to) GTR (greater than) GEQ (greater than or equal to) LSS (less than) LEQ (less than or equal to) |
|
Priority |
Optional |
Integer |
Relative priority of the rule. Rules are processed in priority order, with the rule with priority 0 being processed first, the rule with priority 0 being processed second, and so on. If you assign a priority already in use, the new rule will use that priority and other rules will be renumbered accordingly. |
|
InMemory |
Optional |
Switch Parameter |
Creates an object reference without actually committing the object as a permanent change. If the output of the cmdlet is not assigned to a variable, the object will be lost and nothing will be created. |
|
Force |
Optional |
Switch Parameter |
|
|
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
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.
New client version rules are created using the New-CsClientVersionPolicyRule cmdlet. When you create a new rule you must also specify the Identity for that rule; that Identity consists of a scope (e.g., site:Redmond) and a globally unique identifier (Guid). You can either piece together an Identity yourself, or provide the scope (the –Parent parameter) and the Guid (the –Id parameter) and have New-CsClientVerisonPolicyRule create the Identity for you.
Return Types
New-CsClientVersionPolicyRule creates new instances of Microsoft.Rtc.Management.WritableConfig.Policy.ClientVersion.Rule object.
Examples
-------------------------- Example 1 ------------------------
 Copy Code |
|
|---|---|
$y = [guid]::NewGuid() $x = "site:Redmond/" + $y.ToString() New-CsClientVersionPolicyRule -Identity $x -MajorVersion 4 -UserAgent Inhouse |
|
Example 1 demonstrates how you can create a new client version policy rule. Policy rules have Identities that are composed of two parts: the scope where the announcement is to be assigned, and a 36-character GUID (globally unique identifier). Creating an Identity for a new client version policy rule thus requires two steps. In the first command, the .NET Framework method NewGuid creates a new GUID and stores that value in the variable $y. In the second command, the location site:Redmond is combined with a forward slash (/) and the string value of the GUID in order to create an Identity for the new announcement. That Identity will be similar to this: site:Redmond/1951f734-c80f-4fb2-965d-51807c792b90. This value is stored in the variable $x.
After the Identity has been created you can then use New-CsClientVersionPolicyRule to create the new rule. New-CsClientVersionPolicyRule has three mandatory parameters, all of which are shown in this example: Identity; MajorVersion; and UserAgent. In this case, the UserAgent parameter is assigned the value Inhouse, representing an in-house client application.
-------------------------- Example 2 ------------------------
| Copy Code |
|
|---|---|
$y = [guid]::NewGuid() $x = "site:Redmond/" + $y.ToString() $z = New-CsClientVersionPolicyRule -Identity $x -InMemory $z.MajorVersion = 4 $z.UserAgent = "Inhouse" Set-CsClientVersionPolicyRule $z |
|
The commands shown in Example 2 represent a variation of the command shown in Example 1: in this case, however, the new command is initially created in memory only, and only later added to Microsoft Communications Server. To carry out this task, the first two commands in the example create a new Identity for the rule, using the .NET Framework method NewGuid to create the GUID portion of the Identity. In command 3, a new in-memory-only client version policy rule is created; the -InMemory parameter ensures that the rule exists only in memory and is not immediately added to the Microsoft Communications Server infrastructure.
After the virtual rule has been created, the next two commands are used to assign values to the MajorVersion and UserAgent properties, respectively. When those tasks are complete, the final command in the example (and the Set-CsClientVersionPolicyRule cmdlet) is used to create the actual client version policy rule and assign the rule to the Redmond site.