Creates a new collection of client version configuration settings. Client version configuration settings determine whether or not Microsoft Communications Server 2010 checks the version number of each client application that logs on to the system; if this "client version filtering" is enabled then the ability of that client application to access the system will be based on settings configured in the appropriate client version policy. New settings can only be created, and applied, at the site scope.
Syntax
New-CsClientVersionConfiguration -Identity <XdsIdentity> [-Confirm [<SwitchParameter>]] [-DefaultAction <Allow | AllowWithUrl | Block | BlockWithUrl>] [-DefaultURL <String>] [-Enabled <$true | $false>] [-Force <SwitchParameter>] [-InMemory <SwitchParameter>] [-WhatIf [<SwitchParameter>]] |
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
|
Identity |
Required |
XdsIdentity |
Represents the unique identifier to be assigned to the new collection of client version configuration settings. Because you can only create new collections at the site scope the Identity will always be the prefix "site:" followed by the site name; for example "site:Redmond". Note that the preceding command will fail if a collection of settings with the Identity site:Redmond already exists. |
|
DefaultAction |
Optional |
String |
Indicates the action to be taken if a user tries to log on from a client application whose version number cannot be found in the appropriate client version policy. DefaultAction must be set to one of the following values: Allow. The client application will be allowed to log on. Block. The client application will be prevented from logging on. BlockWithUrl. The client application will be prevented from logging on. However, the "Access denied" message box displayed to the user will include the URL of a Web page where that user can download an approved client application. The URL for this Web page should be specified as the value for the DefaultUrl property. This property is ignored if the Enabled property is set to False. When the Enabled property is set to False then no client version filtering of any kind takes place. |
|
DefaultUrl |
Optional |
String |
Specifies the URL of the Web page where users can download an approved client application. If specified, and if the DefaultAction is set to BlockWithURL, this URL will appear in the "Access denied" message box displayed any time a user tries to log on from an unsupported client application. |
|
Enabled |
Optional |
Boolean |
Indicates whether client version filtering is enabled or disabled. If the Enabled property is True then the server will check the version number of each client application that attempts to log on; the server will then allow or deny access based on the appropriate client version policy. If the Enabled property is False then any client application capable of logging on will be allowed to log on. The default value is True. |
|
UserAgentMapping |
Optional |
PS List Modifier |
|
|
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. If the output is stored in a variable, that object can be committed by passing the variable to this same cmdlet without the -InMemory parameter. |
|
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
Communications Server 2010 gives administrators considerable leeway when it comes to specifying the client software (and, equally important, the version number of that software) that users can use to log on to the system. For example, users do not have to use Microsoft Communicator "14" in order to log on; there is no technical reason to prevent people from logging on using Microsoft Office Communicator 2007 R2.
On the other hand, there might be some non-technical reasons why you would prefer that your users do not try to log on using Office Communicator 2007 R2. After all, Office Communicator 2007 R2 does not support all the features and capabilities found in Communicator "14"; as a result, users who log on with Office Communicator 2007 R2 will have a different experience than users who log on using Communicator "14". This can create difficulties for your users; it can also create difficulties for help desk personnel, who must provide support for a number of different client applications.
That might or might not be a problem in your organization. If it is a problem, then you can employ client version filtering in order to specify which client applications (and which versions of those client applications) can be used to log on to Communications Server 2010. When you install Communications Server 2010, a global set of client version configuration settings is installed and enabled. These settings are used to determine whether or not client version filtering is enabled. If the Enabled property is set to True, two things happen. First, Communications Server 2010 will check the version number of each client application that accesses the system. If there is a client version policy that calls out that version of that application (for example, Office Communicator 2007 R2), then that policy will be enforced; depending on how you have configured the policy, that means the application will be granted access; will be denied access; or will be denied access but referred to a URL where a valid client application can be downloaded. If the Enabled property is set to False, then client version filtering will not be employed. That means that any client application that has the ability to log on to the system will be allowed to log on.
In addition to the global settings, the New-CsClientVersionConfiguration cmdlet enables you to create client version configuration settings at the site scope. (You will get an error message if you try to create a settings collection at the global scope; that’s because there can only be one collection at the global scope.) When client version configuration settings are applied at the site scope those settings take precedence over the global settings. For example, suppose you have enabled client version filtering at the global scope, then create a separate collection of settings for the Redmond site, a collection of settings where client version filtering is disabled. In that case, client version filtering will be disabled for all the users who have accounts on the Redmond site.
Return Types
Creates new instances of the Microsoft.Rtc.Management.WriteableConfig.Policy.ClientVersionFilter object.
Examples
-------------------------- Example 1 ------------------------
 Copy Code |
|
|---|---|
New-CsClientVersionConfiguration -Identity site:Redmond-Enabled $False |
|
The command shown in Example 1 creates a new collection of client version configuration settings for the Redmond site (hence the Identity "site:Redmond"). In this command, the -Enabled parameter is set to False ($False); that means that client filtering is disabled for the Redmond site. In turn, that means that users can log on to Communications Server 2010 using any client application capable of logging on to the system.
-------------------------- Example 2 ------------------------
| Copy Code |
|
|---|---|
$x = New-CsClientVersionConfiguration -Identity site:Redmond -InMemory $x.DefaultAction = "Block" Set-CsClientVersionConfiguration -Instance $x |
|
Example 2 shows how you can create a new collection of client version configuration settings in memory, modify that collection, and then turn these virtual settings into an actual collection of settings applied to the Redmond site. To do this, the first command uses New-CsClientVersionConfiguration and the -InMemory parameter to create an in-memory-only collection of settings with the Identity site:Redmond. This collection is stored in a variable named $x and, as noted, exists in memory only: if you terminate your Windows PowerShell session or delete the variable $x these client version configuration settings will disappear and will never be applied to the Redmond site.
In command 2 the value of the DefaultAction property for the virtual settings is set the Block. In command 3, the Set-CsClientVersionConfiguration cmdlet is used to transform the virtual settings into an actual collection of client version configuration settings, a collection that is applied to the Redmond site.