SharePoint Online Management Shell – Part 3: Connecting and disconnecting to SPOnline

2017-12-11T10:34:26+00:00 July 30th, 2015|PowerShell, Sharepoint|

Introduction

Welcome to part two of my SharePoint Online Management Shell series. In this post, I’ll walk through how you manage connections to a SPOnline service using the SharePoint Online Management Shell, namely how to connect and disconnect. One goal of this series is to put together a script that achieves a real-world challenge and, in the name of speed, I will be storing passwords in plain-text today. However, I don’t expect anyone to actually do this, as securing them comes later (see part 7 of the series), I simply mean to set the scene today. If you don’t want to take the scripted approach, or intend to have interaction with your script, then you can substitute this section with the Get-Credential cmdlet instead.

Pre-Requisites

  • You must have the SharePoint Online Management Shell for Windows PowerShell installed
  • A SharePoint Online Management Shell session in PowerShell (see Part 2 of this series)
  • The SharePoint Online administration tenant URL
  • A set of valid credentials (username and password)

Process

The first thing we must do is create the local variables to store the username and password strings:

$O365User = "patrickf@risual.com";
$O365Password = "Password1";

Now we need to store this within the PowerShell session as a SecureString then create a PSCredential object, the latter is what we will use shortly to securely connect to our SPOnline service:

$Password = ConvertTo-SecureString -String $O365Password -AsPlainText -Force;
$Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $O365User, $Password;

Next, we need to set up a local variable to store the SharePoint Online administration tenant URL. This is your OnMicrosoft tenant account name suffixed with “-admin.sharepoint.com”. For example, our risual tenant is risual365-admin.sharepoint.com and you can also find the URL from My Apps loaded from the Office Portal.

$O365TenantAdminUrl = "https://risual365-admin.sharepoint.com";

Now we’re ready to connect! Using the Connect-SPOService cmdlet, we must pass our credential object we created previously and target the admin tenant URL:

Connect-SPOService -Url $O365TenantAdminUrl -Credential $Credential;

Sadly, the Connect-SPOService cmdlet doesn’t return anything if the connection was successful, nor can you query the state. Well, you can but not easily, maybe something to cover another day, but for now we must assume that if no error is returned, then the connection was successful. You might want to put Connect-SPOService cmdlet into a try…catch block and assign a variable which can be evaluated later, for example:

$connected = $null; # Set default behaviour
try {
  Connect-SPOService -Url $O365TenantAdminUrl -Credential $Credential -ErrorAction Stop;
  $connected = $true;
}
catch {
  Write-Host -ForegroundColor Red "Connection to SPOService threw an error" $($_.Exception.GetType().FullName) $($_.Exception.Message);
}
if ($connected -eq $true) { Write-Host "SPO is connected"; }

At this stage, you’ll be going off doing your actual work against SPOnline. Once you’ve finished, we can go ahead and disconnect our session, then you’re all done!

Disconnect-SPOService;

As a final note, and please make of it what you will, but I tend to connect before executing workloads, then subsequently disconnect. If I’ve more than one workload, I’ll logically split it up and connect/disconnect between. It’s not really essential, but for overall stability it works best for me. That said, I’ve seen people just running the Connect-SPOService before each execution, regardless of existing state and disconnects, but (and really if you only take one thing on board, please make it this) be conscious that each “Connection” will cost you wasted time if the connection is already open. This is due to the second (and subsequent) connection executions implicitly terminate previous connections. That said, when you’re working across multiple tenants from the same session, there made be a justification to do it.

Next up, a working example doing something with our connection to SPOnline via the SharePoint Management Shell. Let’s enumerate all our Site Collections in part 4.

References

  • Connect-SPOService – https://technet.microsoft.com/en-us/library/fp161392.aspx
  • Disconnect-SPOService – https://technet.microsoft.com/en-us/library/fp161396.aspx