Blog Post

Microsoft SharePoint Blog
2 MIN READ

Decorating CSOM calls in PowerShell

Justin Davis's avatar
Justin Davis
Icon for Microsoft rankMicrosoft
Mar 30, 2018

To ensure service availability and maintain service health, some HTTP requests may be prioritized over others. Our documentation recommends decorating the User-Agent header of the HTTP request as a design practice for reducing or avoiding SPO request throttling (link). Although there are many examples of decorating CSOM calls in the context of a C# application, this article demonstrates how to decorate CSOM calls within a PowerShell script.

 

Setting User-Agent at runtime

Each call to the ClientRuntimeContext.ExecuteQuery method triggers an ExecutingWebRequest event. When your script first constructs the ClientRuntimeContext object, you can pass a function to ClientRuntimeContext.add_ExecutingWebRequest method. The function passed will be called at runtime as an event handler for the ExecutingWebRequest event. This event handler sets the User-Agent header of the HTTP request. The following code is adapted from https://techcommunity.microsoft.com/t5/SharePoint-Developer/Updated-Guidance-around-Identity-and-SharePoint-web-service/td-p/119889.

 

$ctx.add_ExecutingWebRequest({
param($Source, $EventArgs)
$request = $EventArgs.WebRequestExecutor.WebRequest
$request.UserAgent = "NONISV|CsomPs|TestDecorate/1.0"
})
$ctx.ExecuteQuery()

 

Testing CSOM request header decoration

The following script demonstrates CSOM HTTP request header decoration. The script reads and prints the title of the given Web multiple times. Each iteration of the loop sleeps for one second to avoid SPO service throttling.

PARAM
(
       [Parameter(Mandatory=$true)]
       [String]$WebUrl
)
Add-Type -Path '.\Microsoft.SharePointOnline.CSOM.16.1.7206.1200\lib\net40-full\Microsoft.SharePoint.Client.dll'
Add-Type -Path '.\Microsoft.SharePointOnline.CSOM.16.1.7206.1200\lib\net40-full\Microsoft.SharePoint.Client.Runtime.dll'
Import-Module Microsoft.Online.SharePoint.PowerShell -DisableNameChecking
$username = Read-Host -Prompt "Enter or paste a Site Owner or Site Collection Administrator for $($WebUrl)"
$password = Read-Host -Prompt "Enter Password for $($username)" -AsSecureString
$ctx = New-Object Microsoft.SharePoint.Client.ClientContext($WebUrl)
$ctx.Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($username, $password)
$ctx.add_ExecutingWebRequest({
param($Source, $EventArgs)
$request = $EventArgs.WebRequestExecutor.WebRequest
$request.UserAgent = "NONISV|CsomPs|TestDecorate/1.0"
})
$ctx.ExecuteQuery()
1..5 | %{
   $web = $ctx.Web
   $ctx.Load($web)
   $ctx.ExecuteQuery()
   $title = $web.Title
   Write-Host "Iteration $($_) - Web Title: $($web.Title)"
   Start-Sleep -Milliseconds 1000
}

Recording a Fiddler trace while the script runs shows the decorated User-Agent request header.

Further guidance

The HTTP protocol has no mechanism for verifying the User-Agent header, so this header can be set to any value that conforms to https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.

 

To avoid throttling, it’s best to format the User-Agent in accordance with our published guidance linked above. In addition to decorating HTTP traffic, adding Start-Sleep statements helps to ensure a steady-state request rate of 1 request per second. It may be helpful to pair ExecuteQuery calls with Start-Sleep -Milliseconds 1000 statements, especially if calling ExecuteQuery in a loop.

Updated Aug 27, 2020
Version 3.0
No CommentsBe the first to comment