Windows PowerShell provides a large number of built-in cmdlets (pronounced command-lets) that perform specific operations. The Exchange Management Shell adds an additional set of PowerShell cmdlets used specifically for managing Exchange. We can also run these cmdlets interactively in the shell, or through automated scripts. When executing a cmdlet, parameters can be used to provide information, such as which mailbox or server to work with, or which attribute of those objects should be modified. In this recipe, we'll take a look at basic PowerShell command syntax and how parameters are used with cmdlets.
When running a PowerShell command, you type the cmdlet name, followed by any parameters required. Parameter names are preceded by a hyphen (-
) followed by the value of the parameter. Let's start with a basic example. To get mailbox information for a user named testuser
, use the following command syntax:
Get-Mailbox –Identity testuser
Alternatively, the following syntax also works and provides the same output, because the –Identity
parameter is a positional parameter:
Get-Mailbox testuser
Most cmdlets support a number of parameters that can be used within a single command. We can use the following command to modify two separate settings on the testuser
mailbox:
Set-Mailbox testuser –MaxSendSize 5mb –MaxReceiveSize 5mb
All cmdlets follow a standard verb-noun naming convention. For example, to get a list of mailboxes, you use the Get-Mailbox
cmdlet. You can change the configuration of a mailbox using the Set-Mailbox
cmdlet. In both examples, the verb (Get
or Set
) is the action you want to take on the noun (Mailbox
). The verb is always separated from the noun using the hyphen (-
) character. With the exception of a few Exchange Management Shell cmdlets, the noun is always singular.
Cmdlet names and parameters are not case-sensitive. You can use a combination of upper and lowercase letters to improve the readability of your scripts, but it is not required.
Parameter input is either optional or required, depending on the parameter and cmdlet you are working with. You don't have to assign a value to the –Identity
parameter since it is not required when running the Get-Mailbox
cmdlet. If you simply run Get-Mailbox
without any arguments, the first 1,000 mailboxes in the organization will be returned.
Tip
If you are working in a large environment with more than 1,000 mailboxes, you can run the Get-Mailbox
cmdlet, setting the –ResultSize
parameter to -Unlimited
to retrieve all of the mailboxes in your organization.
Notice that in the first two examples, we ran Get-Mailbox
for a single user. In the first example, we used the -Identity
parameter, but in the second example we did not. The reason we don't need to explicitly use the -Identity
parameter in the second example is because it is a positional parameter. In this case, -Identity
is in position 1
, so the first argument received by the cmdlet is automatically bound to this parameter. There can be a number of positional parameters supported by a cmdlet, and they are numbered starting from one. Other parameters that are not positional are known as named parameters, which means that we need to use the parameter name to provide input for the value.
The –Identity
parameter is included with most of the Exchange Management Shell cmdlets, and it allows you to classify the object you want to take an action on.
Tip
The –Identity
parameter used with the Exchange Management Shell cmdlets can accept different value types. In addition to the alias, the following values can be used: ADObjectID, Distinguished name, Domain\Username, GUID, LegacyExchangeDN, SmtpAddress, and UserPrincipalName (UPN).
When you run a cmdlet without providing an input for a required parameter, you will be prompted to enter the information before execution. This is because the cmdlet needs to know which mailbox it should modify when the command is executed.
Tip
In order to determine whether a parameter is required, named or positional, supports wildcards, or accepts input from the pipeline, you can use the Get-Help
cmdlet, which is covered in the next recipe in this chapter.
Multiple data types are used for input, depending on the parameter you are working with. Some parameters accept string values, while others accept integers or Boolean values. Boolean parameters are used when you need to set a parameter value to either true
or false
. PowerShell provides built-in shell variables for each of these values using the $true
and $false
automatic variables. For a complete list of PowerShell v5 automatic variables, run Get-Help about_automatic_variables
. Also see Appendix A, Common Shell Information for a list of automatic variables added by the Exchange Management Shell.
For example, you can enable or disable a send connector using the Set-SendConnector
cmdlet with the –Enabled
parameter:
Set-SendConnector Internet -Enabled $false
Switch parameters don't require a value. Instead, they are used to turn something on or off, or to either enable or disable a feature or setting. One common example of when you might use a switch parameter is when creating an archive mailbox for a user:
Enable-Mailbox testuser -Archive
PowerShell also provides a set of common parameters that can be used with every cmdlet. Some of the common parameters, such as the risk mitigation parameters (-Confirm
and -Whatif
), only work with cmdlets that make changes.
Risk mitigation parameters allow you to preview a change or confirm a change that may be destructive. If you want to see what will happen when executing a command without actually executing it, use the –WhatIf
parameter:
![](https://static.packt-cdn.com/products/9781785288074/graphics/4180EN_01_04.jpg)
While making a change, such as removing a mailbox, you'll be prompted for confirmation, as shown in the following screenshot:
![](https://static.packt-cdn.com/products/9781785288074/graphics/4180EN_01_05.jpg)
To suppress this confirmation, set the –Confirm
parameter to false
:
Remove-Mailbox testuser -Confirm:$false
Notice here that when assigning the $false
variable to the -Confirm
parameter, we had to use a colon immediately after the parameter name and then the Boolean value. This is different to how we assigned this value earlier with the -Enabled
parameter, when using the Set-SendConnector
cmdlet. Remember that the –Confirm
parameter always requires this special syntax, and while most parameters that accept a Boolean value generally do not require this, it depends on the cmdlet with which you are working. Fortunately, PowerShell has a great built-in help system that we can use when we run into these inconsistencies. When in doubt, use the help system, which is covered in detail in the next recipe.
Cmdlets and parameters support tab completion. You can start typing the first few characters of a cmdlet or a parameter name and hit the Tab key to automatically complete the name or tab through a list of available names. This is very helpful in terms of discovery and can serve as a bit of a time saver.
In addition, you only need to type enough characters of a parameter name to differentiate it from another parameter name. The following command using a partial parameter name is completely valid:
Set-Mailbox -id testuser –Office Sales
Here, we used -id
as a shortcut for the -Identity
parameter. The cmdlet does not provide any other parameters that start with -id
, so it automatically assumes that you want to use the –Identity
parameter.
Another helpful feature that some parameters support is the use of wildcards. When running the Get-Mailbox
cmdlet, the -Identity
parameter can be used with wildcards to return multiple mailboxes that match a certain pattern:
Get-Mailbox -id t*
In this example, all mailboxes starting with the letter t
will be returned. Although this is fairly straightforward, you can refer to the help system for details on using wildcard characters in PowerShell by running Get-Help about_Wildcards
.
Parameter values containing a space need to be enclosed in either single or double quotation marks. The following command would retrieve all of the mailboxes in the Sales Users
OU in Active Directory. Notice that since the OU name contains a space, it is enclosed in single quotes:
Get-Mailbox -OrganizationalUnit 'testlabs.se/Sales Users/Seattle'
Use double quotes when you need to expand a variable within a string:
$City = 'Seattle' Get-Mailbox -OrganizationalUnit "testlabs.se/Sales Users/$City"
You can see here that we first create a variable containing the name of the city, which represents a sub OU under Sales Users
. Next, we include the variable inside the string used for the organizational unit, when running the Get-Mailbox
cmdlet. PowerShell automatically expands the variable name inside the double quoted string, where the value should appear, and all mailboxes inside the Seattle
OU are returned by the command.
Quoting rules are documented in detail in the PowerShell help system. Run Get-Help about_Quoting_Rules
for more information.