Using CSOM and PowerShell to query SharePoint Online or on-premise

Recently I released the SharePoint Client Browser (preview) that provides inside in a remote SharePoint site by using the Client Side Object Model (CSOM). The tool only reads data and shows it in a rich interface. When you want to make changes you have options: 1) build a custom tool and use the CSOM to interact with SharePoint or 2) use PowerShell and CSOM to interact with SharePoint.

This post shows how to use PowerShell and CSOM together to interact and automate configuration changes to your SharePoint. The example script can be used for both SharePoint Online and on-premise deployments.

This PowerShell script will be a new feature in the SharePoint Client Browser. This allows the user to start PowerShell directly from the SharePoint Client Browser and eliminates the need to do the scripting discussed in this post by yourself!

Prerequisites

Besides having a SharePoint site collection somewhere, you need to create a folder on your local machine. This folder needs to have the SharePoint Client Runtime assemblies. These can be downloaded here. Next to the SharePoint Client Runtime you need to place your scripts here (for example: OpenSite.ps1).

The PowerShell script

The easiest way to get started is creating a new TXT-file in the local folder and rename it to “OpenSite.ps1” (or choose a more appropriate name). Next right click with your mouse on the file and choose Edit. This will open up the Windows PowerShell ISE and you can start editing your script.

Authentication

The script is pretty easy and almost reusable for both SharePoint Online and on-premise, but it has a difference between them. Guest what it is?! The authentication is done differently. Below 3 different authentication examples.

Current user credentials

By not providing any credentials automatically the current user credentials are used.

SharePoint Online

When connecting to SharePoint Online you can use the new SharePointOnlineCredentials class. This makes it a lot easier then with SharePoint 2010.

$ctx = New-Object Microsoft.SharePoint.Client.ClientContext($siteUrl)
$ctx.Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($loginname, $pwd)

SharePoint (on-premise) and credentials

Setting the credentials is done via the NetworkCredential class. That looks like this:

$ctx = New-Object Microsoft.SharePoint.Client.ClientContext($siteUrl)
$ctx.Credentials = New-Object System.Net.NetworkCredential($loginname, $pwd)

The full example script

Below you can find the PowerShell script to use with SharePoint Online. Make sure when using the script you choose the right authentication model (see above). After running this script you can use the CSOM the same way as you would use CSOM in your C# application.

$loc = "C:\Users\Bram\Downloads\SharePoint" # Location of DLL's
$siteUrl = "https://contoso.sharepoint.com"
$loginname = "bram@contoso.onmicrosoft.com"

Set-Location $loc

Add-Type -Path (Resolve-Path "Microsoft.SharePoint.Client.dll")
Add-Type -Path (Resolve-Path "Microsoft.SharePoint.Client.Runtime.dll")

Write-Host "Please enter password for $($siteUrl):"
$pwd = Read-Host -AsSecureString
$ctx = New-Object Microsoft.SharePoint.Client.ClientContext($siteUrl)
# Remove or replace line below to change authentication method
$ctx.Credentials = New-Object System.Net.NetworkCredential($loginname, $pwd)

$web = $ctx.Web 
$ctx.Load($web) 
$ctx.ExecuteQuery() 

Write-Host " Current web title is '$($web.Title)', $($web.Url)"