Adapt your Exchange Online scripts to use Get-ExoMailbox

Adapt your Exchange Online scripts to use Get-ExoMailbox

Forget Get-Mailbox, it’s had its day.

Recently, I wrote about the New-DistributionGroup cmdlet to explain why I think distribution lists are still so valuable, despite Microsoft’s efforts to convince the world that Microsoft 365 Groups are better. Today, I want to talk about a cmdlet that’s even more fundamental to many people’s experience working with Exchange via PowerShell: Get-Mailbox. Or, to be more precise, the new and improved Get-ExoMailbox .

Microsoft introduced Get-ExoMailbox as one of the nine initial cmdlets upgraded in 2019 to use REST APIs (like Microsoft Graph) instead of Remote PowerShell (RPS) for a very good reason. Retrieving sets of mailboxes to process is a fundamental activity for any Exchange administrator.  Get-Mailbox works, but it’s slow and error-prone, especially when dealing with large sets of objects. In this respect, it shares the same flaws as other remote PowerShell cmdlets. The fact that Get-Mailbox is used so frequently to process so much data makes it seem more problematic than its peers. This isn’t really the case. On the contrary, Get-Mailbox reveals all the flaws inherent in depending on a connection to a named remote server that may or may not remain available throughout an entire session.

Three Steps to Exchange Online PowerShell Bliss

Anyway, by now you should have converted the Exchange Online scripts to:

• Use the Exchange Online Management module instead of Remote PowerShell.
• Use the Connect-IPPSSession cmdlet to connect to the compliance endpoint. The current version of the Exchange Online Management module allows concurrent sessions connected to Exchange Management and Compliance.
• Replace Get-Mailbox with Get-ExoMailbox and change other important cmdlets at the same time. The three most urgent switches to make are Get-ExoMailboxStatistics, Get-ExoMailboxFolderStatistics, and Get-ExoMailboxPermission.

The Exchange Online Management Module and REST-based cmdlets don’t exist for on-premises Exchange. The way the Exchange Online infrastructure works has exposed some flaws in Remote PowerShell that don’t exist in on-premises deployments. So Microsoft hasn’t moved the new cmdlets into this area yet. Will it ever happen? I don’t know, but if I had to guess, I’d say no. But never say never.

Exchange Online Management Version 2.0.5

Speaking of versions, Microsoft released V2.0.5 of the Exchange Online Management Module on May 10th. They still haven’t updated the module’s release notes, so we don’t know what’s in the new version. In any case, I’ve been using 2.0.5 for a week, and everything seems stable. About 70,000 other people have downloaded 2.0.5, and I haven’t heard of any issues so far.

Mailbox Data Optimization

Coming back to Get-ExoMailbox, the big upgrade issue I keep hearing about is the need to specify properties when retrieving mailbox data. This is a change in behavior from Get-Mailbox, implemented to optimize mailbox data retrieval. The problem is that mailbox properties cover hundreds of different items, some of which need to be retrieved or validated with Azure AD. If you do something like:

Get-Mailbox -Identity TRedmond

You get all the mailbox properties back. But if you run:

Get-ExoMailbox -Identity TRedmond

Exchange Online only retrieves 15 properties. These are the most important ones, such as

• the display name,
• the user’s primary name,
• email addresses
• the very underused ExternalDirectoryObjectId.

This is the pointer (GUID) to the Azure AD account that owns the mailbox. All Exchange Online mail objects connected to Azure AD have this property to facilitate connection to Azure AD. Using GUIDs to reference objects is very common in Office 365, especially in every call to the Graph API to retrieve data about an object, so it’s good to get used to using GUIDs.

For example, I can do this:

Get-AzureADUser -ObjectId ((Get-ExoMailbox -Identity Tony.Redmond@office365itpros.com).ExternalDirectoryObjectId) | Select ObjectId, DisplayName
 
ObjectId                             DisplayName
--------                             -----------
f1dbb86a-69bf-4245-8bc7-5e1d09d9d8cc Tony Redmond (Office 365 for IT Pros)

I can take the ObjectId returned by Azure AD and use it with Get-ExoMailbox:

Get-ExoMailbox -Identity f1dbb86a-69bf-4245-8bc7-5e1d09d9d8cc

Because Get-ExoMailbox is careful about what it retrieves, you often need to include queries to retrieve individual properties or property sets in your calls (a property set is a collection of properties common to a certain purpose, such as quotas). For example, the WhenCreated property isn’t one of the 15 core properties, so if I want to use it, I need to include it in the call:

Get-ExoMailbox -Identity TRedmond -Properties WhenCreated

The big advantages

The benefits of switching to Get-ExoMailbox include:

• Better performance, especially when processing large numbers of mailboxes. Your mileage will vary depending on what you’re doing, but when I tested the new cmdlets publicly at Microsoft Ignite 2019, the speed increase was between three and four times faster for processing thousands of mailboxes. You won’t see much benefit if you only ever retrieve a few mailboxes. And at the other end of the scale, for processing very large quantities of mailboxes, graph APIs might be a better solution.
• Better reliability. Get-ExoMailbox and other REST-based cmdlets are better able to handle server issues. If you’re recovering thousands of mailboxes, the last thing you want is for Exchange Online to change domain controllers (it happens, even in the cloud). Remote PowerShell will fail. Get-ExoMailbox will likely complete successfully (errors are always unpredictable).

In summary, the short-term pain of converting scripts to use the new cmdlets will be far outweighed by long-term gains in performance and reliability. It’s simply the right thing to do, and anyone proposing to write code using the old cmdlets should be urged to reconsider their options with just a hint of force.

And did I mention that the Exchange Online Management Module supports Ubuntu Linux? Okay, maybe that’s not that important to this audience, but it’s true.