How to Connect to SharePoint Online using CSOM PowerShell?

Requirement: Connect to SharePoint Online using PowerShell CSOM.

connect to sharepoint online csom powershell

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.

sharepoint online powershell credential manager

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:

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.

How to connect to SharePoint Online using PnP PowerShell?

As a first step, You need to install the PnP.PowerShell module to your computer using the “Install-Module” PowerShell command. Then you can connect to SharePoint Online from PnP PowerShell and perform any operation such as retrieving data, manipulating objects, updating settings, etc.
More info: How to Connect to SharePoint Online from PnP PowerShell Module?

How do I connect to SharePoint Online with MFA-enabled accounts from PowerShell?

To connect to SharePoint Online from PowerShell with an MFA enabled account, here are the options: You can create an App Password, leave the -Credential parameter from “Connect-SPOService” cmdlet and try to connect, use -Interactive switch for PnP PowerShell Connect-PnPOnline cmdlet.
More info: Connect to SharePoint Online from PowerShell with MFA

How do I connect to the SharePoint Online Management shell?

Install the SharePoint Online Management Shell or Microsoft.Online.SharePoint.PowerShell module and then connect to SharePoint Online using Connect-SPOService cmdlet.
More info: Connect to SharePoint Online Management Shell

Salaudeen Rajack

Salaudeen Rajack - SharePoint Expert with Two decades of SharePoint Experience. Love to Share my knowledge and experience with the SharePoint community, through real-time articles!

One thought on “How to Connect to SharePoint Online using CSOM PowerShell?

  • Using PnP PowerShell

    $listObject = Get-PnPList -Identity ” -Includes ‘Author’
    $listObject.Author

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *