Working with Parameters
Topic Last Modified: 2013-08-15
When using the Identity parameter, you may notice that the parameter value email@example.com is enclosed in double quotation marks:
One of the questions that people new to Windows PowerShell invariably ask is this: when should I use double quotation marks and when should I not use double quotation marks? There is no simple answer to this question, but there are some general rules to follow:
Double quotation marks are typically not required when the parameter value is a number. For example, to limit the number of users returned by the Get-CsOnlineUser cmdlet, use this syntax:
Similarly, make sure that you do not include commas in a number. For example, if you wanted to set the result size to 10,000, this syntax would be incorrect:
Double quotation marks are typically also not required when the parameter value is a date:
-StartDate "6/1/2013 10:00AM"
Get-Host | Select-Object CurrentUICulture
String values (such as a person’s name) typically do not require double quotation marks. The main exceptions occur when that string value includes restricted characters, such as a blank space, a comma, or other punctuation marks. For example, this syntax works because the user’s identity does not include any of the restricted characters:
-Identity Ken Myer
Get-CsOnlineUser : A positional parameter cannot be found that accepts argument 'Myer'.
-Identity "Ken Myer"
-Identity 'Ken Myer'
-Identity "Ken Myer'
Double quotation marks should not be used with Boolean (True/False) values. Note, too, that you must use the Windows PowerShell variables $True and $False when specifying True/False values. For example:
There are also certain Windows PowerShell parameters known as switch parameters that do not accept parameter values:
Not only are parameter values not required when using a switch parameter, but including a parameter value will actually generate an error. For example, if you try to run this command:
That command will fail with an error message similar to this:
Set-CsUserAcp : A positional parameter cannot be found that accepts argument 'True'.
Your ability to manage Lync Online by using Windows PowerShell requires that you know which cmdlets are available for use. You must also know which parameters are available for each cmdlet, and you must know the data type of each parameter (that is, whether the parameter accepts a date value, a string value, a number, and so on). This information (along with numerous examples on how to use the cmdlets) can be found in the Help topics for the Lync Online cmdlets. For example, here are the parameters available for use with the Set-CsTenantPublicProvider cmdlet:
As you can see, the parameter table provides a description of the cmdlet; indicates whether the parameter is required (mandatory) or optional; and tells you the data type of each parameter. Note that the data type shown in the table is the official data type used by the .NET Framework. This means the data type is shown as System.Management.Automation.SwitchParameter instead of just Switch Parameter. Here’s a quick guide to the data types most commonly used by the Lync Online cmdlets:
A string value representing the Identity of a user. This is typically the user’s UPN or SIP address:
An FQDN is a fully qualified domain name. For example:
A Boolean value is a True/False value. Remember, you must use the Windows PowerShell variables $True and $False when specifying Boolean values:
-Enabled $True -EnterpriseVoiceEnabled $False
GUID is the acronym for globally unique identifier, a unique identifier which, in Lync Online, is assigned to each Lync Online tenant. For example:
You can retrieve the GUID assigned to your Lync Online tenants by using this command:
Get-CsTenant | Select-Object TenantId
Switch parameters are named this because they are either switched on or they off. If the parameter is present, then the switch is on, so to speak; if the parameter is not present, the switch is off. For example, to use the Confirm parameter to require confirmation before running a command, include the Confirm parameter (without a parameter value) as part of the command. For example:
Remove-CsUserAcp -Identity "Ken Myer" -Confirm
If you do not want to require confirmation, then do not include the Confirm parameter:
Remove-CsUserAcp -Identity "Ken Myer"
A string value is an alphanumeric value; that is, it can contain (in general) any character that can be typed on the keyboard. For example:
It’s a good idea to enclose string values in double quotation marks. This isn’t always required. However, it is required if your string value contains a blank space or comma, or if it happens to be a reserved Windows PowerShell keyword. (A keyword is a command or other element that is part of the Windows PowerShell language itself. For example, “If” and “End” are both Windows PowerShell keywords. For more information, type the following command from the Windows PowerShell command prompt: