Beginning with Exchange Server 2007, Microsoft introduced PowerShell to enhance the Exchange Server product. PowerShell was a radical change at the time when Microsoft was known for its GUI interfaces. Yes, Microsoft had some command line access to its OS’s (think DOS). By adding a command line interface, Microsoft had suddenly put the gauntlet down and announced to the world that it was serious about it products and providing an enhancement that would appeal to those who would look down on Microsoft because of the GUI based approach.
While Exchange Server 2007 ran what was then known as PowerShell 1.0, and while it was a good addition to existing Exchange Server management it was not perfect. It was not as flexible as it is today and was sorely in need of enhancement. With the introduction of Exchange Server 2010 and Exchange Server 2013, PowerShell advanced from 2.0 to 4.0. Currently Exchange Online supports PowerShell version 4.0 and 5.0. We won’t cover the enhancements between versions, however suffice it to say that the product has changed drastically over the years since it was first introduced in 2007.
As PowerShell has advanced feature-wise, the commands that are exposed to Exchange Server have changed from 2007 to 2010 to 2013 to 2016 and now Exchange Online. This book is focused on Exchange Online, however a lot of the cmdlets, one-liners and scripts will work on Exchange 2016, 2013 and even Exchange 2010. We will make references to changes that have occurred in case you have written scripts in previous versions and are unaware of changes that need to be made in those scripts.
Why PowerShell and Not the Exchange Admin Center [a.k.a. the GUI]
There are many reasons to use PowerShell to manage and manipulate your Exchange Online Tenant. Some of the reasons are obvious while others may require some explanation. Let’s lay out why you should use and become familiar with when it comes to PowerShell for Exchange Online:
- PowerShell allows the use of standard Windows commands that you would run in the Command Prompt.
- PowerShell brings powerful commands to the table to enable you to work with a complex environment. These commands use a verb-noun based syntax.
- PowerShell is integrated with almost all of Microsoft’s on-premises and cloud applications.
- PowerShell allows for heavy automation. While this would seem to be geared to larger environments, smaller shops can utilize scheduling for common tasks – reporting, maintenance, bulk maintenance, etc. – to reduce the time needed and human errors in managing their Exchange server(s).
- Some things just cannot be done in the GUI. This is important. This is not advertised or spelled out by Microsoft. There are many options or configurations that can ONLY be performed with PowerShell. To make this clear, PowerShell is not limited in its management of Exchange as the GUI is. So it is important to learn it when learning about Exchange Servers in general.
- PowerShell works with objects. These objects can enable you to do powerful tasks in Exchange.
- PowerShell can get a task done in fewer lines than say VBScript. Some will find this to be an advantage as it can take less time to accomplish a task by writing it in PowerShell.
- PowerShell works with many technologies – XML, WMI, CIM, .NET, COM and Active Directory. The last one is important as you will see later, we can tie scripts together between Active Directory queries and Exchange commands.
- PowerShell provides a powerful help and search function. When working with PowerShell and a command is new to you, Get-Help is extremely useful as it can provide working examples of code. Searching for commands is easy as well and if you know what you want to manipulate (e.g. mailboxes), just searching for commands with a keyword of ‘mailbox’ can help direct your Get-Help query to find the relevant command.
As we get further into the book, we will cover these important features and more. One thing to remember about Exchange Server PowerShell is that it can be run local on an Exchange Server or remote (if PowerShell remoting is enabled). This can ease manageability of your messaging environment.
** Note ** For this book, we’ll access Exchange Online with PowerShell 5.0.
Simply put, the Exchange Management Shell is the original Windows PowerShell with a module loaded specifically with Exchange Server oriented cmdlets.
Cmdlet (definition) – is a single PowerShell command like Get-Mailbox. Pronunciation: ‘commandlet’.
Module (definition) – is a collection of additional PowerShell commands that are grouped together for one purpose or function. Example modules are Exchange Server, Active Directory and Windows Azure. There are many, many more, but these examples are relevant to this book.
PowerShell cmdlets come in two basic groupings - safe exploratory cmdlets (ones starting with ‘GET’ for example) and others that can configure or modify the Exchange configuration (SET, REMOVE, etc. - not as safe and can be dangerous to a production Exchange messaging environment).
Anatomy of a PowerShell Cmdlet:
Verb - The action part of the cmdlet. Whether this is Get, Remove, List, Set or Add and more that are less common. These words are the first word of the Cmdlet and to the left of the dash of the cmdlet name.
Noun - The word or words to the right of the dash of the PowerShell cmdlet name. These words help describe what is being affected in Exchange Server 2016. Examples include - FederationTrust, FocusedMailbox, AddressList and more.
Parameter(s) - These are the options which are selected and upon which the PowerShell cmdlet will act. To get an idea of what parameters are present for each cmdlet you will need to do run a Get-Help <cmdlet> -full. We will review that later in this chapter.
Switch - Options that can be toggled for a cmdlet that don’t need additional information (-WhatIf for example).
Get-UnifiedGroup
Provides a list of Unified Groups in the Exchange Online
Set-UnifiedGroup
Allows for the configuration of your Unified Groups in Exchange Online
When exploring PowerShell for Exchange for the first time, it is advisable to start with the Get cmdlets as these cmdlets will provide the beginner to PowerShell the following items:
- A view into Exchange and its configuration
- Practice with parameters, output, piping and more
- Non-destructive PowerShell practice
- A means to generating reports on Exchange
Get-cmdlets are benign in the sense that the current environment is not being changed or re-configured. This provides for safe learning or exploration not only for PowerShell but Exchange as well. It is highly recommended that you review some basic cmdlets like the following as a good starting point for your venture into Exchange PowerShell:
Get-AcceptedDomain Get-AddressBookPolicy Get-CASMailbox
Get-Clutter Get-DlpPolicy Get-MobileDevice
Get-QuarantineMessage Get-SyncRequest Get-UMMailbox
Single cmdlets are the meat and potatoes of PowerShell. However you can combine the results gathered by one cmdlet and feed this to another cmdlet in PowerShell which then processes results from the previous cmdlet. This process is known as piping. By combing two cmdlets together like this we now have a very powerful tool to use to construct one-liners. Caution should be used as not all cmdlets can be piped into another or vice versa.
One-liner (definition) – In PowerShell a one-liner literally is either a single command that performs a function or it is comprised of a set of cmdlets that are paired together with a pipe symbol ‘|’.
For an example of piping we are passing information from Get-Mailbox to Get-MailboxStatistics to produce results in a single table. If we did not use the pipelining feature, you would have to perform the Get-MailboxStatistics for each mailbox instead of using the pipeline method, which will run this for all mailboxes in one cmdlet. The pipe allows us to do that in bulk, which saves time and produces a single table of results.
Get-Mailbox | Get-MailboxStatistics
** Note ** Some cmdlets may return too many results and are often restricted to a set limit. In the above ‘Get-Mailbox’ example, the results are often limited to the first 1000. A way around this limit is to use ‘-ResultSize’ and specifying a larger number, like 2,000, or using ‘Unlimited’ which will provide as many results it can find without restrictions.
Sample output:
To see the advantage of this, if we needed to gather the same information using just Get-MailboxStatistics, we would need to run the command for each mailbox:
As you can see, the pipeline method enables us to move past a simple single line. What this also allows us to do is save time and allow us to work more efficiently in our scripting.
An alternative to piping would require quite a bit more effort, and some techniques we have not covered yet. The code would involve basically gathering all the mailboxes and storing their identities in a variable and the reading through the variable and running Get-MailboxStatistics for each mailbox stored in that variable:
$Mailboxes = Get-Mailbox
Foreach ($Mailbox in $Mailboxes) {
Get-MailboxStatistics $Mailbox.Alias
}
The results are the same, while the complexity has gone up substantially some combined cmdlets can save server resources in terms of CPU and memory usage.
For another example of pipeline, let’s take a more advanced topic like Mailbox Database health in a mailbox cluster. In order to get a complete picture of database health in a cluster we need to find all the databases and then get a status of each copy on each node that has that copy. How do we do this? We pipe Get-PublicFolder to the Get-PublicFolderStatistics cmdlet. These commands work in tandem to produce this:
Notice that we can see the status, as well as the ContentIndexStatus. Both of these are important in knowing the health of your mailbox databases.
Protecting Yourself and What If
PowerShell is powerful. PowerShell can thus do some serious damage to Exchange Online and Azure Active Directory. How can you protect your infrastructure from your missteps?
- Run Get cmdlets first to get a general familiarity of PowerShell in Exchange.
- Use the WhatIf switch when running cmdlets, this will show what would have occurred if a cmdlet was run.
An example of the WhatIf switch would be what would happen if you were to get all mailboxes in Exchange and remove the mailboxes:
Get-Mailbox testclouduser | Remove-Mailbox -WhatIf
What if: Removing the mailbox “testclouduser” will mark the mailbox and the archive, if present, for deletion. The associated Windows Live ID “[email protected]” will also be deleted and will not be available for any other Windows Live service.
The one caveat to this is if the mailbox is synchronized from Active Directory, you will see this error message instead:
Get-Mailbox User | Remove-Mailbox -WhatIf
Notice the WhatIf statement in front of each result. If this command was run in production, all mailboxes would be deleted. However, because we ran the same command with the WhatIf switch only a simulation was run, no mailboxes were removed.
A certain amount of discovery involves knowing Exchange. With this knowledge, finding commands that are necessary to perform actions becomes easier. For example users in your environment that receive email have mailboxes. This may seem like a simple example, but it will help illustrate the idea of knowing Exchange will help with PowerShell cmdlets.
So, going back to mailboxes. We need to manipulate some information or create a report on mailboxes in your Exchange Online tenant. If you don’t know what commands that can be run, we rely on a specific cmdlet called ‘Get-Command’. With this we can find cmdlets we need:
Get-Command *mailbox*
Running this will look for any PowerShell cmdlet that has the work mailbox in it. The wildcard ‘*’ that is located in front and behind the word ‘mailbox’ just means that we are searching for any command that may or may not have additional letters before or after the word ‘mailbox’. A small portion of the results are listed below:
Now, let’s say we actually need to look at Public Folders in the environment:
Get-Command *PublicFolder*
As you can see, the Get-Command is useful for finding cmdlets in PowerShell that you can use in Exchange Online.
When working with Exchange and because of its dependency on Azure Active Directory we may need other cmdlets in order to perform certain actions. When working in the default Exchange Management Shell, PowerShell cmdlets for Azure Active Directory are not preloaded. In order to load these cmdlets, we may need to install the module. With PowerShell 5.0 we can download modules of all sorts using the ‘Install-Module’ cmdlet like so:
Install-Module -Name AzureAD
** Note ** If this is the first time the Install-Module cmdlet has been run, you may receive a message about a ‘NuGet Provider’. This provider is what allows the interaction between PowerShell and the NuGet repository where the modules are stored. Make sure to answer yes as to whether to install it.
Once the NuGet module has installed, we can now install the AzureAD module via the NuGet provider:
Once the module is installed we can now to connect to AzureAD to work with this part of an Office 365 tenant:
Connect-AzureAD
After the PowerShell module has loaded, additional cmdlets are available.
Along with Get-Command, Get-Help will assist you in exploring PowerShell for Exchange Online.
When faced with running a new cmdlet in PowerShell or just figuring out what other options are available for a PowerShell cmdlet, the Get-Help and Get-Command are extremely helpful. If you’ve used Linux or Unix they are like the man pages of old where a description of what the command can do, where it can be run, various examples of how the command can be used and more. When using the Get-Help and Get-Command, just like other PowerShell commands, there are switches that you can use to help enhance the basic cmdlet. For example, take this cmdlet:
Get-Help Get-RetentionPolicy
The above command returns some information on the Get-Mailbox cmdlet:
Notice the main sections: Name, Synopsis, Syntax, Description, Related Links and Remarks. The command we ran provided us with a nice summary of what this command can do and the Related Link section points you to the online documentation for this cmdlet. However, what is missing is the switches or options that are available for the cmdlet as well as some examples on how to use the cmdlet as well. To get these, run the following:
Get-Help Get-RetentionPolicy -Full
The same first section appear: Name, Synopsis, Syntax and Description. However, a few addition sections appear now: Parameters, Inputs, Outputs and Examples:
When you work with a command that you are unfamiliar with, it would be advisable to start with the -Full switch to get all information on the cmdlet as well as some examples on how to use the command. The major weakness of the help command as well as the Online help is that some commands are very complex and have so many options that they don’t feel as complete as they might. This means that even after finding the right parameters, it may take some time to get the right results. If you find yourself in this situation, you can turn to your favorite Internet search engine to find the right syntax OR possibly get a close enough example that a bit of tweaking will make the cmdlet run the way you expect.
Let’s end this chapter on a cautionary note. We covered commands like Get-Help and Get-Command. These will come in handy as you build your own scripts. After writing scripts for a while you may notice that not everything in Exchange PowerShell is perfect or logical. This is especially true when it comes to PowerShell cmdlet naming conventions. Let’s take for example any cmdlet with the word ‘Mobile’ in it. Here is the list of all the cmdlets:
Get-Command *Mobile*
Which will give us this for results:
However, there is another set of cmdlets that appear for mobile devices, under their original name of Active Sync. These cmdlets were once the only available ones because the Active Sync protocol used to be THE way to connect to Exchange. With the advent of modern protocols, apps and the cloud, the cmdlet base is slowly changing. Here are all the cmdlets with ‘ActiveSync’ in their name:
Get-Command *ActiveSync*
As you can see this leaves a bit to be desired for consistency sake. The best way to handle these situations is to do what we did above to get all cmdlets that have a similar word or function to them.
Cloud-Only vs Synced Environments and PowerShell Cmdlets
For anyone who manages Exchange Online, knowing what PowerShell cmdlets will with their environment is a crucial piece of information. In that spirit we want to make sure that these differences are clearly delineated in the rest of the book and when we are working with PowerShell. The important thing to remember is that if your accounts, mailboxes and other objects are not synced to the cloud you will need to make your changes in Office 365 directly and not to anything on-premises like Active Directory. This is simply because Office 365 is in this scenario your source of truth and it is the master copy of these objects. If, however, you have Active Directory and you are syncing these objects to the cloud your on-premises Active Directory is the source of truth or Start of Authority. Those synced objects need to be changed in your on-premises Active Directory, to be more precise those synced attributes are actual only read-only in the cloud. This currently also means that if you have Exchange attributes that need to be changed in those synced objects, you require an Exchange server on-premises. This is currently the only supported way to achieve those changes (like adding an additional SMTP address to a synced object). You might find blog posts and well-intentioned advices to use third party tool or perhaps even ADSIedit, but those aren’t officially supported. This does not preclude you from running PowerShell cmdlets against your Exchange Online tenant. Or on fully cloud objects.
** Note ** Please note that the defining feature here is the synchronization of objects, NOT the fact that an Exchange environment is hybrid or not. AD synchronization is a prerequisite for an Exchange hybrid environment.
Hybrid environment (things to consider):
- Creation of Shared Mailbox - the process includes creating a remote mailbox and then converting this mailbox into a Shared Mailbox
- Creation of Archive Mailbox - PowerShell cmdlet run on-premises Exchange and attribute synced to Exchange Online
- Handling of self-management distribution lists - On by default in User Roles of Exchange Online
- We use a sync script to create copy lists in Exchange Online (ExO) so that both sides can be self-managed independent of the mailbox location.
Non-Synced Accounts (Cloud Only)
For those who do not want any infrastructure for their email services, this is a common setup. In this configuration, all your objects exist in Exchange Online only. All management tools and scripts will run against these cloud-only objects. The Admin Console for your tenant should show all of these objects as ‘Cloud-Only’ and this only manageable from Office 365’s connections.
Sample Management Scenarios
Creating a new mailbox
(1) Log into Exchange Online PowerShell with an account with the correct login privileges
(2) Create an account using the New-Mailbox cmdlet.
(3) Add license in Office 365
(4) Configure mailbox attributes - Retention policy, ActiveSync policy, OWA policy and more
** Note ** There is no need to wait for synchronization or for an object to be updated in two places. All changes are made in Exchange Online.
Create Mail Transport Rule
(1) Log into Exchange Online PowerShell
(2) Run New-TransportRule to create the new rule - refer to page 205 for more information.
It is common, but not entirely true of all of these environments, that a synced environment will have Exchange on-premises for management. This is simply because Microsoft does not support managing synced objects to the cloud with ADSIEdit. The supported method is to have an Exchange Server on-premises to serve as a management console. Due to this requirement and the nature of this server, Microsoft will also provide what is known as a Hybrid license key for you to license an Exchange 2010, 2013 or 2016 server to use it for Exchange Online management.
Sample Management Scenarios
Creating a new mailbox
(1) Log into an Exchange Server with an account with the correct login privileges
(2) Create an account using the New-RemoteMailbox cmdlet.
(3) Wait for Azure AD Connect to sync this newly created object to Exchange Online
(4) Log into Exchange Online PowerShell
(5) Add license in Office 365
(6) Configure mailbox attributes - retention policy, ActiveSync policy, OWA policy and more
** Note ** Notice that we are logging into both Exchange On-Premises and Exchange Online depending on what the task is to be performed.
Create Mail Transport Rule
For a synced environment this situation is one of ‘It Depends’. The reasoning behind that is, depending on your configuration, email may still be flowing through Exchange on-premises/ In this scenario, let assume that we need the rules in ExO because mail flow from internal and external recipients all flows through Exchange Online Protection (EOP).
(1) Log into Exchange Online PowerShell
(2) Run New-TransportRule to create the new rule - refer to page 205 for more information.
For most of the scenarios and cmdlets laid out, we are assuming that there is an Active Directory on-premises that has synced to Exchange Online. As such, we will assume that there will be some split management. Some will require modification from an on-premises Exchange server as well as connecting to ExO to make some changes. As such, we’ll try to point out when there is a deviation from this scenario.
What’s Next?
In this introduction we have just scratched the surface of what is available in PowerShell for Exchange Online. Let’s go ahead and get in deep with PowerShell in Chapter 1.