Add Web Part To Page Using CSOM With PowerShell On SharePoint

Introduction

In this article, you will learn how to add web part to a publishing page using CSOM with PowerShell on SharePoint 2013 / SharePoint online.

Steps Involved

The following section explains the flow for adding web part to a publishing page.

1. Add the references using the Add-Type command with necessary reference paths. The necessary references are Microsoft.SharePoint.Client.dll, Microsoft.SharePoint.Client.Runtime.dll and Microsoft.SharePoint.Client.Publishing.dll.
   

   Add-Type -Path "C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\ISAPI\Microsoft.SharePoint.Client.dll"
   Add-Type -Path "C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"
   Add-Type -Path "C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\ISAPI\Microsoft.SharePoint.Client.Publishing.dll"

2. Initialize client context object with the site URL.

   $siteURL = ""
   $ctx = New-Object Microsoft.SharePoint.Client.ClientContext($siteURL)

3. If you are trying to access SharePoint Online site, then you need to setup the site credentials with credentials parameter and get it set to the client context. 
   

   #Not required for on premise site - Start
   $userId = ""
   $pwd = Read-Host -Prompt "Enter password" -AsSecureString
   $creds = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($userId, $pwd)
   $ctx.credentials = $creds
   #Not required for on premise site - End

4. If you are trying to access the SharePoint on premise site, then the credentials parameter is not required to be set to the context. But you need to run the code on the respective SharePoint server.
   
   
5. Get the page from the respective library using server relative url. Load the file and execute the query to access the page components.
   

   #page where web part to be changed
   $pageName = "TestPage1.aspx"
   #Get the page to add
   $file = $ctx.Web.GetFileByServerRelativeUrl("/Pages/TestPage1.aspx")
   $ctx.Load($file)
   $ctx.ExecuteQuery()

6. Check if web part already exists.
   
   
7. If web part not present, then we will add the web part. Check out the file using below logic.
   
   
• Check the file is checked out by some one. If so, undo check out.
  
  
• If its not checked out, then check out the file using check out type "none" and check out method.
  

  #Check if page already checked out. If so, undo check out
  if($file.CheckOutType -eq [Microsoft.SharePoint.Client.CheckOutType]::Online){
      try{
          Write-Host "Undo Checkout"
          $file.UndoCheckOut()
          $ctx.load($file)
          $ctx.ExecuteQuery()
      }
      catch{
          write-host "Error in checkout.. $($_.Exception.Message)" -foregroundcolor red
      }
  }
  
  #If page is not checked out, then check out
  if($file.CheckOutType -eq [Microsoft.SharePoint.Client.CheckOutType]::None){
      Write-Host "Checkout"
      $file.CheckOut()
      $ctx.Load($file)
      $ctx.ExecuteQuery()
  }

8. Then access the web part file. It will have extension of webpart or dwp. It is a xml file with necessary web part details like title, zone id, header, etc. The web part xml can be generated by exporting and modifying the existing web part files. Once generated, import the web part xml and add it to web part manager with necessary zone id and zone index.
   

   Write-Host "Adding webpart"
   $XmlDocument = Get-Content -Path "local drive path/NewWebpart.xml"
   $importWP = $wpManager.ImportWebPart($XmlDocument)
   $wpManager.AddWebPart($importWP.WebPart,0,0)
   $ctx.ExecuteQuery()

9. Then check in and publish the page.
   

   Write-Host "Page checkin"
   $file.CheckIn("Added webpart", [Microsoft.SharePoint.Client.CheckinType]::MajorCheckIn)
   $ctx.load($file)
   $ctx.ExecuteQuery()

I have added a content editor web part to the page. Like wise any other web part can be added to the page using the respective web part file. Here generating or mapping the correct web part file is important.

Summary

 

Thus you have learnt how to add web part to a publishing page using CSOM with PowerShell commands on SharePoint 2013 / SharePoint online.