Managing SharePoint Online with PowerShell

SharePoint Online PowerShell Module in PowerShell Gallery

SharePoint Online PowerShell Module Helps Automate Common Tasks

The SharePoint Online Management Shell is a Windows PowerShell module designed for command-line operations and inclusion in PowerShell scripts. The module makes it possible to perform batch processing for tasks like reports and is the only way to achieve some management tasks in SharePoint and OneDrive.

Like with many other cloud components, Microsoft updates the SharePoint Online Management Shell almost every month to align with the release cadence of the SharePoint Client-Side Object Model (CSOM) API libraries. The updates include new cmdlets, new parameters for cmdlets, and other tweaks. If you use PowerShell to work with SharePoint Online, it’s important that you use the latest module.

Installing the Latest SharePoint Online Module

You can download an MSI (installable package) for the latest SharePoint Online Management Shell module. Once downloaded, you run the executable to install the module, remembering to uninstall any previous version first. The MSI version is the traditional method to distribute updated modules, but since Microsoft released the Microsoft.Online.SharePoint.PowerShell module in the PowerShell Gallery, it’s more convenient to install it from there.

To install the SharePoint Online module, run PowerShell as an administrator and run this command:

Install-Module -Name Microsoft.Online.SharePoint.PowerShell

To update to the latest version, run:

Update-Module -Name Microsoft.Online.SharePoint.PowerShell

Connecting to SharePoint Online with PowerShell

The Connect-SPOService cmdlet is used to connect to the SharePoint administration endpoint for a tenant. (the same as used for the SharePoint Admin Center) To build the endpoint, take the normal SharePoint root for your tenant (like https://office365itpros.sharepoint.com/) and insert an “-admin” after the tenant name. For example:

# Connect to SharePoint Online administration endpoint
Connect-SPOService -URL "https://office365itpros-admin.sharepoint.com"

The SharePoint Online module is designed for administrative tasks, so you should always connect with an account that has Global Administrator or SharePoint Administrator rights for the tenant.

As part of the connection to the administration endpoint, the SharePoint Online module is loaded into your PowerShell session and you can check the version of the installed module installed:

Get-Module |? {$_.Name -eq "Microsoft.Online.SharePoint.PowerShell"}| Format-Table Name, Version   

Name                                   Version
----                                   -------
Microsoft.Online.Sharepoint.PowerShell 16.0.19724.12000

In your scripts, it’s a good idea to include a test to make sure that a connection is available to SharePoint Online before running any other code. Here’s a very simple test for a connection:

Try {
    $TestSPO = Get-SPOTenant }
Catch
    { Write-Host "Error accessing SharePoint Online - please connect to the service before retrying"; break } 

Basic SharePoint PowerShell Cmdlets

To see the available SharePoint Online cmdlets, run:

Get-Command -Module "Microsoft.Online.SharePoint.PowerShell"

The current SharePoint Online Management Shell module includes 179 cmdlets. Theses cmdlets can be divided into several types, including:

  • Tenant-Level cmdlets like Get-SPOTenant and Set-SPOTenant.
  • Site-Level cmdlets like Get-SPOSite and Set-SPOSite.
  • Cmdlets for specific operations like Start-SPOSiteRename and Test-SPOSite.

It’s very common to want to retrieve information about the sites in a tenant. To do this, run the Get-SPOSite cmdlet. The Limit parameter specifies that all sites are to be returned.

Get-SPOSite -Limit All 

Note that this command returns all types of sites found in the tenant, including redirect sites (created because of site URL renames), hub sites, the app catalog, and sites used by Teams private channels. In most cases, it is best to be more precise when using Get-SPOSite to find sites by specifying the template for the type of sites you want to process. For instance, this command only returns the sites used by Teams private channels.

Get-SPOSite -Limit All -Template "TEAMCHANNEL#0"

SharePoint and Other Office 365 Elements

Sometimes you need to retrieve information about a SharePoint Online site for use elsewhere inside Office 365. For example, if you want to include a document library belonging to an Office 365 group, team, or team private channel on an eDiscovery case or content search, you need to specify the site’s URL as a search location.

If you use PowerShell to examine the properties of an Office 365 group, you will see three SharePoint Online URLs returned for the site, the document library, and the shared OneNote notebook. The value returned in SharePointSiteUrl property is the one needed when you wish to add a site to content searches, found using the Get-UnifiedGroup PowerShell cmdlet:

Get-UnifiedGroup –Identity "Office 365 for IT Pros" | Format-List Share*Url

SharePointSiteUrl	: https://Office365ITPros.sharepoint.com/sites/O365ITPros
SharePointDocumentsUrl	: https://Office365ITPros.sharepoint.com/sites/O365ITPros/Shared Documents
SharePointNotebookUrl	: https://Office365ITPros.sharepoint.com/sites/O365ITPros/SiteAssets/Office 365 for IT Pros Notebook

The URL retrieved from the Office 365 Group can be used with Get-SPOSite to find further information about the site belonging to the group.

It’s also possible to discover what Office 365 Group a site belongs to by using the GroupId property stored for the site. For example:

Get-UnifiedGroup -Identity (Get-SPOSite -id https://office365itpros.sharepoint.com/sites/O365ExchPro).GroupId.Guid  | Format-Table DisplayName, SharePointSiteURL                 
  
DisplayName            SharePointSiteUrl
-----------            -----------------
Office 365 for IT Pros https://office365itpros.sharepoint.com/sites/O365ITPros

SharePoint PnP Module

The functionality available through the SharePoint Online PowerShell module is limited and restricted to basic administration tasks performed by a SharePoint Online administrator, such as managing sites and tenant settings. To get extra functionality, use the cmdlets available in the SharePoint PnP PowerShell cmdlets project in GitHub, part of the Patterns & Practices community initiative. To go further and be able to access all the aspects of SharePoint, you will need to use the CSOM API in your PowerShell scripts. To install the PnP PowerShell module, run this command:

Install-Module SharePointPnPPowerShellOnline -Force

Many good examples of using the SharePoint PnP cmdlets are available on the web.


This information is an example of the kind of text you’ll find in the Office 365 for IT Pros eBook. Don’t you think you should be a subscriber?

2 Replies to “Managing SharePoint Online with PowerShell”

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.