Working With SharePoint Master Pages Using PnP PowerShell

Introduction

In this article, we will learn how we can add, retrieve, set and delete the master pages on SharePoint sites, using PnP PowerShell. The Client Side Object Model is used internally for these operations.

Prerequisite

You need to have PowerShell 3.0, available on a Windows machine. You need to install or import PnP PowerShell packages. You can download the installers or view more documentation from the official site. The installers are available here. Online version installer is preferred for On Premise or Office 365 operations. You can also install all the three installers for testing (SharePoint 2013, 2016, online).

The PnP PowerShell is supported by SharePoint 2013, SharePoint 2016 On Premises and Office 365 versions. The following operations are tested on SharePoint 2013 and Office 365 environments.

Connect To Site

Connect to the site, using the snippet, given below. PnP PowerShell code, given below, helps in getting the current context of the site, using Client Side Object Model (CSOM).

$siteurl = "https://abc.sharepoint.com"
Connect-SPOnline -Url $siteurl
$ctx = Get-SPOContext

Be default, the master pages are present on the master page gallery of the site. (http://siteurl/_catalogs/masterpage/Forms/AllItems.aspx).

Add Master Page

Add-SPOMasterPage command is used to add the master page to the site.

The required parameters are:

SourceFilePath: Local master page file path.
Title: Master page title.
Description: Master page description.

The optional parameter is:

DestinationFolderHierarchy: Folder, where the master page should be saved. The value can be “/” or “/Subfolder”. The files will be stored in the master page gallery.

Note: I assumed that the master page is already created and is kept ready for the use in local system.

The code snippet, given below, shows adding new master page file to SharePoint site:

Add-SPOMasterPage -SourceFilePath D:\Nakkeeran\PnP\PnPMasterPage.master -Title "PnPMasterPage" -Description "Adding through PnP" -DestinationFolderHierarchy "PnPMasterPages"

Retrieve Master Pages

The current master pages of the site can be retrieved, using Get-SPOMasterPage command. There are no parameters required to retrieve the details. The system master page and the custom site master page URL are retrieved, using the operation.

The code snippet, given below, shows retrieving the master page details of the site, mentioned above.

$masterPage = Get-SPOMasterPage
Write-Host "Custom Master Page : " $masterPage.CustomMasterUrl
Write-Host "System Master Page : " $masterPage.MasterUrl

Set Master Page

Set-SPOMasterPage command is used to set the master pages for the current site.

The required parameter for setting the master page can be,

CustomMasterPageServerRelativeUrl or CustomMasterPageSiteRelativeUrl for setting the custom site master page.
MasterPageServerRelativeUrl or MasterPageSiteRelativeUrl for setting the system files master page.

The code snippet, given below, shows updating the master pages. (Both the parameters can also be passed in the single call):

Set-SPOMasterPage -CustomMasterPageServerRelativeUrl "/_catalogs/masterpage/PnPMasterPages/PnPMasterPage.master"
Set-SPOMasterPage -MasterPageServerRelativeUrl "/_catalogs/masterpage/PnPMasterPages/PnPMasterPage.master"

The same can be viewed from the site master page settings page (http://siteurl/_layouts/15/ChangeSiteMasterPage.aspx). The snapshot, given below, shows the results before setting the master page and after setting the master page.

Note: GetMasterPage denotes the retrieve operation, defined above. SetMasterPage denotes the update operation, defined in this section.

Delete/Remove Master Page

Before removing the current master page from the site, the master page should be updated to some other page. Set-SPOMasterPage is used to update the master page. Remove-SPOFile is used to remove the master page from the site.

The below code snippet shows the operation.

Set-SPOMasterPage -CustomMasterPageServerRelativeUrl /_catalogs/masterpage/seattle.master
Set-SPOMasterPage -MasterPageServerRelativeUrl /_catalogs/masterpage/seattle.master
Remove-SPOFile -ServerRelativeUrl "/_catalogs/masterpage/PnPMasterPages/PnPMasterPage.master"

Summary

Thus, you have learned, how to retrieve, add, set or delete SharePoint master pages on SharePoint sites programmatically, using PnP PowerShell commands. PnP PowerShell is supported by SharePoint 2013, SharePoint 2016 On Premises and Office 365 versions. The operations mentioned above, are tested on SharePoint 2013 and Office 365 environments.