Using Windows PowerShell with Staged Migrations: Part 1


Summary: Use Windows PowerShell to add and verify email domains in Office 365.

Note  This is a five-part series that includes the following posts:

Honorary Scripting Guy, Sean Kearney, is here. This week we’re going to touch on something that should be useful to many IT professionals who are trying to get themselves on to Office 365—that is a staged migration.

When you are moving to Office 365, a staged migration is the preferable option if you’re starting from an Exchange Server 2007 or 2003 environment. It allows you to build out mailboxes in Office 365 without really needing to interfere will mail flow while the process occurs.

It’s not a perfect process because you still need to re-create permissions and reconnect your users to the remote online environment, but it does allow for “staging.” It offers the opportunity to see what does or does not work after a migration and to move staff in groups because you can move them back and forth pretty seamlessly while this process occurs.

To establish a staged migration, of course you’ll need the standard stuff running for Office 365 such as:

  • Online tenant with a “.onmicrosoft.com” address
  • DirSync (or another directory synchronization tool to populate the accounts remotely)

One of the key things you’ll need to do in your tenant is add the domains that you want to manage and receive email. When you log in to the Office 365 portal, you’ll do this by clicking the Domains tab in the left pane.

Image of menu

Then next screen shows your default domain, which will be something like contoso.onmicrosoft.com. Click + Add domain to begin adding a new domain for receiving email. Even if you don't flip the MX records, this process is needed to create an accepted domain for the Office 365 Exchange system.

Today we’re going to pick on EnergizedTech.com as my sample.

Image of menu

You’ll get a simple little 3-point wizard to help you create the addition in Office 365. Start by clicking Let’s get started. (Yes, thank you, Captain Obvious!)

Image of menu

Enter the name of the domain where you want to receive email. In our example, it will be EnergizedTech.com. Then click Next to continue.

Image of menu

We could automatically sign-in to the Registrar to complete this process if we had the credentials, but in many cases, we’ll be working for clients. So verification can be done with a TXT record added on to the DNS servers. We’ll click here to get the details for the client.

Image of menu

You will receive a screen that indicates the data you can communicate back to your client. This will be a TXT record with a value of MS=xxxxxx (where xxxxxx is some number assigned by Microsoft).

Image of menu

At this point, you would normally communicate the information to the client, and log in to the portal occasionally to check if the status of the domain has been updated from Setup not started, which indicates that the domain has not yet been verified as yours by Microsoft (the TXT record did not get created).

Image of menu

This is where Windows PowerShell comes in. Logging and constantly refreshing a webpage is slow and tedious. If you needed to create multiple domains for the client, and you had to continuously check the status, the process would eat your time.

You’ll need to have the Microsoft Online cmdlets installed to perform this. For a great reference about getting and installing the necessary binaries, see Manage Azure AD using Windows PowerShell.

After you have them installed, authenticate to Office 365 by using the Connect-MSolservice cmdlet. Then use the following line to add a domain. In our example, we are adding the Contoso.com domain to Office 365.

New-MsolDomain –name Contoso.com

Image of command output

You can see the current status is Unverified. By using the Get-MsolDomain cmdlet, you can check the status of a domain as follows:

Get-MsolDomain –DomainName Contoso.com

This will currently echo the same output as the previous cmdlet because nothing has changed. When the change is made on the DNS servers and it cascades through the Internet, you will see the status change to Verified as shown here:

Image of command output

You can also use Windows PowerShell to get the information required for the DNS records. You can use the Get-MsolDomainVerificationDns cmdlet to extract this information:

Get-MsolDomainVerificationDns –DomainName Contoso.com

Image of command output

The object label contains the actual properties for the TXT record. We can use a little magic with Windows Powershell to pull the information and format it for the client.

Why?

With one record I could simply copy the needed information. But what if I am dealing with multiple domains? Would it not be far nicer to get a list from the client and then email the required changes to them?

First we grab the Label property from the object:

(Get-MsolDomainVerificationDns –DomainName Contoso.com).label

Image of command output

Then run a Split method against the period character ( ‘.’ ) to make it into an array:

(Get-MsolDomainVerificationDns –DomainName Contoso.com).label.split(‘.’)

Image of command output

We can then easily access the data we need for the TXT record through the first array element and leverage a substring to pull out the remaining information:

(Get-MsolDomainVerificationDns –DomainName Contoso.com).label.split(‘.’)[0].substring(2)

Image of command output

With some simple Windows PowerShell string magic, we can build this into a line of information to deliver to the client:

“DNS Record TXT, Value MS=$((Get-MsolDomainVerificationDns –DomainName Contoso.com).label.split(‘.’)[0].substring(2))”

If you had a list of domains, we could target all domains that were not verified like this:

Get-MsolDomain –status Unverified

….and then run that against our previous magic to capture a complete list for our client on the Clipboard and to paste it into an email:

Get-MsolDomain –status Unverified | Foreach { “DNS Record TXT,
Value MS=$((Get-MsolDomainVerificationDns –DomainName $_.Name).label.split(‘.’)[0].substring(2))”} | clip

Now you have an easy way in Office 365 to make these changes and track them!

Pop in tomorrow when we look further into our staged migration and learn how Windows PowerShell can make it easier!

I invite you to follow The Scripting Guys on Twitter and Facebook. If you have any questions, send an email to The Scripting Guys at scripter@microsoft.com or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then remember eat your cmdlets every day with a taste of creativity.

Sean Kearney, Windows PowerShell MVP and Honorary Scripting Guy 


Comments (1)

  1. Roel Baan says:

    Hi Sean,

    Nice blog on adding domains to Office 365
    Maybe a small improvement is to make use of the "-mode DnsTxtRecord" parameter in Get-MsolDomainVerificationDns cmdlet.

    Also verifying domains after they are added can be done through powershell.

    Below I added code frequently use to perform these tasks.

    # Get information on all unverified domains
    Get-MsolDomain -Status Unverified | foreach { Get-MsolDomainVerificationDns -DomainName $_.Name -Mode DnsTxtRecord | Select Label,Text,TTL}

    # Try domain verification for all unverified domains
    $domains = Get-MsolDomain -Status Unverified

    foreach ($domain in $domains) {

    Try {

    Confirm-MsolDomain -DomainName $domain.Name -ErrorAction Stop | Out-Null
    write-host "Verified domain: `t `t $($domain.Name)" -ForegroundColor Green

    }

    Catch {

    write-host "Unable to verify domain: `t $($domain.Name)" -ForegroundColor Red

    }

    }

Skip to main content