How to Connect to SharePoint Online using CSOM PowerShell?

Requirement: Connect to SharePoint Online using PowerShell CSOM.

How to Connect to SharePoint Online using CSOM using PowerShell?

Although SharePoint Online Management Shell provides several PowerShell Cmdlets to manage SharePoint Online, it is pretty limiting. The only way to do real SharePoint PowerShell is to use the SharePoint CSOM. The Client Side Object Model is a subset of the Server Object Model and can be used to supplement it.

Pre-Requisites: Download and Install SharePoint Online Client SDK

Download and install SharePoint Online Client Components SDK from https://www.microsoft.com/en-us/download/details.aspx?id=42038. Once installed, It creates assembly (DLL) files in 16 hive on your computer at C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\.

How to write a CSOM PowerShell Script for SharePoint Online?

In SharePoint On-Premises, We had to log in to the SharePoint Server and write-execute PowerShell scripts. As SharePoint Online is in the cloud, we can now write and run PowerShell scripts remotely from our client machines. Here is the typical flow of CSOM PowerShell scripts:

• Step 1: Add the SharePoint Online CSOM assembly references
• Step 2: Initialize variables or command line parameters (optional)
• Step 3: Create the Client Context
• Step 4: Load objects into variables
• Step 5: Retrieve properties or Call methods of the Objects

Step 1: Add the CSOM references to your script

As a first step, you need to load the CSOM libraries in the PowerShell script.

Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.dll"
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"

While these two lines in the script are enough for most operations, we need to reference the below DLLs when dealing with service applications like user profiles, search, managed metadata, etc.

• User Profile – Microsoft.SharePoint.Client.UserProfiles.dll
• Managed Metadata – Microsoft.SharePoint.Client.Taxonomy.dll
• Search  – Microsoft.SharePoint.Client.Search.dll
• Workflow  – Microsoft.SharePoint.Client.WorkflowServices.dll

Step 2: Initialize Variables

Say, you want to connect to a site and get the site name! We need to tell the PowerShell script which site we need to connect and retrieve its property, isn’t it? This step is entirely optional. However, it helps to simplify the script.

#Set Parameters
$SiteUrl = "https://crescent.sharepoint.com/sites/projects"

You can also get the value for parameters at runtime:

#Get Parameter Value
$SiteUrl = Read-Host "Enter the Site URL"

Step 3: Create the Client Context

You need valid credentials to connect to the SharePoint Online site. You may want to get the user name and password to connect at the runtime, or you can hard-code the credentials in the script itself!

#Get Credentials to connect to SharePoint Online site
$Cred = Get-Credential
   
#Set up the context
$Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteUrl)
$Ctx.Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($Cred.Username, $Cred.Password)

You can hard code the credentials to connect as:

#Set user name and password to connect
$UserName="[email protected]"
$Password = "Password goes here"

#Create Credential object from given user name and password 
$Cred = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($UserName,(ConvertTo-SecureString $Password -AsPlainText -Force))
   
#Set up the context
$Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteUrl)
$Ctx.Credentials = $Cred

Step 4: Load Necessary Objects into Variables for processing

Once you have established the context, the next step is to load objects into variables. Say, you want to connect to a site and get the site title. We need to load the web object first!

#Get the Web Object
$Web = $Ctx.web
$Ctx.Load($Web)
$Ctx.ExecuteQuery()

Here is another example:

#Create a Variable and Assign it to Lists object of the Web
$Lists = $Ctx.web.Lists
$Ctx.load($Lists) 
$Ctx.ExecuteQuery() 

#Use the Variable to retrieve object properties
$Lists | Select Title, ItemCount 

In CSOM, To minimize the data transfer, Requests are bundled together and then sent to the server for execution with ExecuteQuery() method.

Step 5: Retrieve Properties or Call Methods of the Objects

Once we load the object, we can access its members to retrieve its properties or call its methods to perform some operations. Here, in our case, let’s retrieve the web object’s “Title” property.

#Retrieve the Title Property of the Web
Write-host $Web.Title

Similarly, You can call any methods of the objects as:

$Web.Title = "New Web Title"
$Web.Update()
$Ctx.ExecuteQuery()

The complete script of the above chunks looks like this:

#Load SharePoint CSOM Assemblies
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.dll"
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"
    
#Set Parameter Value
$SiteUrl = "https://crescent.sharepoint.com/sites/projects"
 
#Get Credentials to connect to SharePoint Online site
$Cred = Get-Credential
   
#Set up the context
$Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteUrl)
$Ctx.Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($Cred.Username, $Cred.Password)

#Get the Web Object
$Web = $Ctx.web
$Ctx.Load($Web)
$Ctx.ExecuteQuery()

#Retrieve the Title Property of the Web
Write-host $Web.Title

You can use the Windows PowerShell console, PowerShell ISE, or Visual Studio Code to execute the SharePoint Online CSOM PowerShell scripts.

How to use Credential Manager in SharePoint Online PowerShell scripts?

To avoid credential popups, you can store your credentials in the Windows credentials store and connect to SharePoint Online without a prompt! This is extremely useful for unattended PowerShell scripts! Here is how to create a stored credential: Open Control Panel >> Windows credential manager >> Select Windows Credentials >> Click on “Add a new Generic credential” >> Enter the credentials. I’ve used “SPO” as the credential name here.

Now, You can use the stored credentials in the PowerShell script as:

Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.dll"
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"

#Variables for Processing
$SiteUrl = "https://Crescent.sharepoint.com/sites/Marketing"

#Get Credentials from Windows Credentials Manager
$Cred = Get-PnPStoredCredential -Name "SPO"

#Set up the context
$Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteUrl)
$Ctx.Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($cred.UserName,$cred.Password)

#Get the Web
$Web=$Ctx.Web
$Ctx.Load($Web)
$Ctx.ExecuteQuery()

Write-host $Web.Title

Using CSOM and SharePoint Online Management Shell Together

CSOM and the SharePoint Online Management Shell can be used together! Sometimes, we may need it as CSOM script scopes at the site collection level, and SharePoint Online Management Shell is scoped at the tenant level. E.g., You want to retrieve all site collections and iterate through each site collection and retrieve the number of webs in each site. Here is an example of how to connect to the SharePoint Online site using PowerShell:

#load powershell sharepoint online module
Import-Module Microsoft.Online.SharePoint.Powershell -DisableNameChecking
 
#Tenant Admin Site URL Parameter
$AdminSiteURL="https://crescent-admin.sharepoint.com"

#Get Credentials
$Cred = Get-Credential

#Connect to SharePoint Online Admin Center
Connect-SPOService -Url $AdminSiteURL -Credential $Cred
 
#Get All site collections
$SiteCollections = Get-SPOSite -Limit All
 
#Traverse through each site collection and get their subsits count
Foreach ($Site in $SiteCollections)
{
    #Setup context
    $Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($Site.Url)
    $Ctx.Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($Cred.Username, $Cred.Password)

    #Get Immediate Subsites in the Site
    $Webs = $Ctx.Web.Webs
    $Ctx.Load($webs)
    $Ctx.executeQuery()
  
    Write-host "Number of Sub-sites in $($Site.Url):"$Webs.Count
}

How to Get  All Available Methods and Properties of SharePoint Online Objects?

While Microsoft docs serve as an authentic source, you can use SharePoint Online Client Browser as it’s a great tool to explore objects in CSOM.

Here are some of my SharePoint Online CSOM PowerShell scripts:

• SharePoint Online CSOM to Update List Item in PowerShell
• SharePoint Online PowerShell CSOM to Add List Item
• SharePoint Online PowerShell CSOM to Create Folder
• SharePoint Online PowerShell CSOM to Create Site Collection
• SharePoint Online PowerShell CSOM to Get List Items
• SharePoint Online Powershell CSOM with MFA
• SharePoint Online Powershell CSOM to Upload file
• SharePoint Online CSOM to Download File PowerShell

Last but not least: SharePoint Patterns and Practices (PnP) contains a library of PowerShell cmdlets that allows you to perform complex operations with one single cmdlet.