PowerShell can help you to automate administrative actions like managing permissions, creating and configuring site, lists, libraries and so on. In this post, you will find information on how to run PowerShell against SharePoint Online.
Available modules
Client Side Object Model
Running PowerShell against SharePoint Online is quite simple. With your SharePoint admin credentials in mind, you will have to run a PowerShell session as an admin and install a few tools:
Available modules
-SharePoint Online module: (Corresponding to the SharePoint Online management shell)
You can use this module to run actions on Sites, users and top-level administration tasks.
You can install this module on your machine directly within PowerShell.
Install-Module -Name Microsoft.Online.SharePoint.PowerShell #Get the commands available in this module Get-Command -Module Microsoft.Online.SharePoint.PowerShell
To start using this module, you have to connect the SharePoint admin endpoint of your tenant. You can find this Url by navigating to the SharePoint Admin center, it looks like https://[domain]-admin.sharepoint.com.
Connect-SPOService -Url 'https://btcstech-admin.sharepoint.com'
You will be prompted for SharePoint admin credentials and you are good to go 🙂
You can find the full documentation for every available cmdLet from Microsoft Docs.
While searching examples on the web, you can recognize cmdLets from this module with the syntax Verb-SPO Noun, like Get-SPOSite, Add-SPOHubSiteAssociation …
-SharePoint PNP PowerShell module : (Community based module)
This module has been developed over the years by the SharePoint community, it targets in depth actions like manipulating list, libraries, files and items.
You can install this module on your machine directly within PowerShell.
Install-Module SharePointPnPPowerShellOnline -AllowClobber #Get the commands available in this module Get-Command -Module SharePointPnPPowerShellOnline
To start using this module, you can connect to the SharePoint admin endpoint of your tenant or directly to a desired SharePoint Site:
#Connecting to the SharePoint admin endpoint of your tenant Connect-PNPOnline -Url 'https://btcstech-admin.sharepoint.com' #Connecting to a SharePoint site Connect-PNPOnline -Url 'https://btcstech.sharepoint.com/sites/mysite'You will be prompted for SharePoint admin credentials and you are good to go 🙂
As a little tip, when you need to use CmdLet from those two modules in your script, you can use the same credentials object while connecting with PNP :
#Connect with the SharePoint Online module you will be prompted for credentials Connect-SPOService 'https://btcstech-admin.sharepoint.com' #Avoid being prompted for Credentials when allready connected with 'Connect-SPOService' Connect-PNPOnline -Url 'https://btcstech.sharepoint.com/sites/mysite' -SPOManagementShell
You can find the full documentation for every available cmdLet from Microsoft Docs.
While searching examples on the web, you can recognize cmdLets from this module with the syntax Verb-PNP Noun, like Get-PNPSite, Add-PNPFile …
SharePoint Client Side Object Model (CSOM)
This is the SharePoint client side object model, allowing you to run a complete set of actions against SharePoint. To be downloaded here
This is not a Module per say, it consist in dll files that you can import in your scripts to use SharePoint classes, It is called SharePoint Online Client Components SDK.
To use it, you will need to install the dlls on your machine, and run the following lines on top of your scripts :
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client")
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client.Runtime")
If you have it installed manually somewhere on your machine, you can use Add-Type:
Add-Type -Path 'c:/mypath/Microsoft.SharePoint.Client.dll' Add-Type -Path 'c:/mypath/Microsoft.SharePoint.Client.Runtime.dll'
Once you loaded those dlls using one of the techniques above, you can now make use of the SharePoint classes. Here is the way you will connect to a SharePoint Site:
#Set the site Url you want to connect to $SiteUrl= 'https://btcstech.sharepoint.com/sites/mysite' #Set Credentials $Credentials = Get-Credential #Use the SharePointOnlineCredentials class $SPOCredentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($Credentials.UserName , $Credentials.Password) #Use the ClientContext class $Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteUrl) #configure ClientContext credentials $Ctx.Credentials = $SPOCredentials #Make an execute query to ensure everything is find (otherwise you get an error) $Ctx.ExecuteQuery()
Using CSOM, is a bit more complex than using modules. Everything comes from the authenticated context object you build, and send the information to SharePoint with the ClientContext.Executequery() method.
You might also be interested in Update() and Load() methods, here are some illustrations from the context we built above :
#I want to retrieve all lists from the site I did connect to $lists = $Ctx.Web.Lists
At this point we just defined that $lists variable, we actually need make the request to SharePoint using Load() and ExecuteQuery() methods otherwise we will get this message :
#When trying to acces this lists variable $lists
To retrieve an manipulate information from SharePoint, we need to user Load() and ExecuteQuery() methods :
$Ctx.Load($lists) $Ctx.ExecuteQuery() $lists| select -Property Title, BaseType
To illustrate the update() method, let’s take another example where you want to disable the Synchronization feature of a document library
#Load the document library you want using the GetByTitle('Name') method
$myDocLib = $Ctx.Web.Lists.GetByTitle('Documents')
$Ctx.Load($myDocLib)
$Ctx.ExecuteQuery()
$myDocLib | select -Property Title, BaseType
#Disable sync for this library
$myDocLib.ExcludeFromOfflineClient = $true
$myDocLib.update()
$Ctx.ExecuteQuery()
#check
$myDocLib.ExcludeFromOfflineClient
To go a little further, keep in mind that you will only get error when using ExecuteQuery().
Another specificity is that you can make multiple changes before calling Clientcontext.ExecuteQuery() method, this could increase your script performance, but you might be bounded by timeout while making too big requests. I found a nice video about CSOM techniques to increase performance, it’s written in C# but might be useful
Regarding PowerShell, you can run cmdLets or scripts manually when needed or automate scripts execution using tasks scheduler locally on a machine, or using Azure functions (PowerShell is now officially supported for Azure Function). If you need more information about Azure functions, here is a little guide from Microsoft docs.
To illustrate this automation need, I can remember a request where we developed a little script ensuring every site collection had two owners and sending a report every week-end by email.
I really hope you found those information useful to start using PowerShell with SharePoint, bear in mind that you can also call the Graph API to talk to SharePoint.
See you soon in the blog section 😎
