Transforming to modern site pages using PowerShell

Important

The SharePoint PnP Modernization framework is continuously evolving, checkout the release notes to stay up to date on the latest changes. If you encounter problems please file an issue in the sp-dev-modernization GitHub issue list.

The page transformation engine can also be used from PowerShell. This allows it to be integrated in a site modernization script that besides page transformation also does other things like installing solution, connecting the site to an Office 365 group and applying tenant branding. A good example of an all-up modernization script can be found in the Office 365 Group connect article.

Note

Below scripts shows how to transform pages. It requires PnP PowerShell version 3.4.1812.0 (December 2018 release) or higher.

<#
.SYNOPSIS
Modernizes the pages of a site. 

IMPORTANT: this requires the PnP PowerShell version 3.4.1812.1 (December 2018) or higher to work!
Version: 1.0

.EXAMPLE
PS C:\> .\modernizesitecollection.ps1
#>

# Connect to the web holding the pages to modernize
Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/modernizationme

# Get all the pages in the site pages library. SitePages is the only supported library for using modern pages
$pages = Get-PnPListItem -List sitepages

# Iterate over the pages
foreach($page in $pages) 
{ 
    # Optionally filter the pages you want to modernize
    if ($page.FieldValues["FileLeafRef"].StartsWith(("t")))
    {
        # No need to convert modern pages again
        if ($page.FieldValues["ClientSideApplicationId"] -eq "b6917cb1-93a0-4b97-a84d-7cf49975d4ec" ) 
        { 
            Write-Host `Page $page.FieldValues["FileLeafRef"] is modern, no need to modernize it again`
        } 
        else 
        { 
            # Create a modern version of this page
            Write-Host `Modernizing $page.FieldValues["FileLeafRef"]...`
            $modernPage = ConvertTo-PnPClientSidePage -Identity $page.FieldValues["FileLeafRef"] -Overwrite
            Write-Host "Done" -ForegroundColor Green
        }
    }  
}


Options for the ConvertTo-PnPClientSidePage cmdlet

The ConvertTo-PnPClientSidePage cmdlet is the key cmdlet to modernize a given page. Below table lists the command line parameters that you can use to control the page transformation via this cmdlet.

Parameter Default Description
Identity (*) The page name (e.g. pageA.aspx)
WebPartMappingFile Page transformation is driven by a mapping file. The cmdlet has a default mapping file embedded, but you can also specify your custom web part mapping file (webpartmapping.xml) to fit your page transformation needs (e.g. transforming to 3rd party custom web parts). You do this by specifying the path to the file via the -WebPartMappingFile parameter.
Overwrite $false When you add -Overwrite then the page transformation framework will overwrite the target page if needed. By default the new page name has a prefix of Migrated_, which then implies that if Migrated_YourPage.aspx already exists (typically from a previous page transformation effort) it will be overwritten.
AddPageAcceptBanner $false Using -AddPageAcceptBanner will make the page transformation framework put the configured PageAcceptBanner web part on top of the created modern page. Using this web part the users accessing the page can decide whether they want to keep or discard the created modern page. See the Page Transformation UI article to learn more on how to install and configure the default page banner web part.
ReplaceHomePageWithDefault $false The default behavior is to transform your site's home page to a modern page like any other regular page. If you use -ReplaceHomeWithDefault then a site's home page will be transformed to a 'default' out-of-the-box modern home page, so the one you would get with a newly created modern team site.
TakeSourcePageName $false The default behavior is to give the created modern page a name that starts with the prefix Migrated_ and let the original page keep it's existing name. When -TakeSourcePageName is specified the newly created page gets the name of the original page and the original page is renamed with a prefix Previous_. Set this option if you're sure you want to move forward with the modern page as it will ensure that all links pointing the original page now result in the new modern page being loaded.
ClearCache (as of January 2019 release) $false To optimize performance certain data (list of available client side web parts, calculated list of fields to copy metadata for) is cached after the first execution. This cache will stay valid during the complete PowerShell session unless you use the -ClearCache switch. Restarting your PowerShell session also clears the cache.
CopyPageMetadata (as of February 2019 release) $false The default behavior is to not copy page metadata (so additional columns added to the site pages library). When -CopyPageMetadata is specified the values of the custom metadata fields of the page to transform are copied to the newly created page

(*) Mandatory command line parameter

FAQ

I used the "AddPageAcceptBanner" switch but don't see the banner web part on the created pages

In order to make the banner webpart work there are 2 requirements that have to be met:

  • The banner web part must have been installed in your tenant app catalog
  • The banner web part must have been referenced in the used webpartmapping.xml file

Installing the banner web part

To install the default banner web part follow these steps:

  • Open your tenant app catalog site collection and go to the Apps for SharePoint list
  • Download the banner web part solution (sharepointpnp-pagetransformation-client.sppkg) from the sp-dev-modernization repository
  • Drag and drop the sppkg file in the Apps for SharePoint list. Doing so will ask to make this solution available to all sites in your organization. Check the box and click on Deploy.

Note

The page banner web part is configured to not be visible in the web part picker...so even if you've deployed it to all sites in your tenant it will still not be visible for your users. It can only programmatically be added to a page

Checking your webpartmapping.xml file

When the page transformation engine puts the banner web part on a page it gets it's definition from the webpartmapping.xml file. Check if you find a web part of type SharePointPnP.Modernization.PageAcceptanceBanner in your mapping file. Below sample shows the default configuration using the default web part uploaded in the previous step.

      <WebPart Type="SharePointPnP.Modernization.PageAcceptanceBanner">
        <Properties>
          <Property Name="SourcePage" Type="string"/>
          <Property Name="TargetPage" Type="string"/>
        </Properties>
        <Mappings>
          <Mapping Default="true" Name="default">
            <ClientSideWebPart Type="Custom" ControlId="d462a7c4-b2e1-4e80-867a-7b46d279c161" Order="10" JsonControlData="&#123;&quot;serverProcessedContent&quot;:&#123;&quot;htmlStrings&quot;:&#123;&#125;,&quot;searchablePlainTexts&quot;:&#123;&#125;,&quot;imageSources&quot;:&#123;&#125;,&quot;links&quot;:&#123;&#125;&#125;,&quot;dataVersion&quot;:&quot;1.0&quot;,&quot;properties&quot;:&#123;&quot;description&quot;:&quot;modernizationPageDemo&quot;,&quot;sourcePage&quot;:&quot;{SourcePage}&quot;,&quot;targetPage&quot;:&quot;{TargetPage}&quot;&#125;&#125;"/>
          </Mapping>
        </Mappings>
      </WebPart>

Note

You can use your own custom banner web part by simply deploying it and then updating the mapping in the used webpartmapping.xml file.

Modern site pages don't work on the site I want to transform pages in

By default the modern site page capability is enabled on most sites but maybe it was turned off afterwards. If that's the case the SharePoint Modernization scanner will tell you which sites have turned of the modern page feature. To remediate this use below sample PnP PowerShell script:

$minimumVersion = New-Object System.Version("2.24.1803.0")
if (-not (Get-InstalledModule -Name SharePointPnPPowerShellOnline -MinimumVersion $minimumVersion -ErrorAction Ignore))
{
    Install-Module SharePointPnPPowerShellOnline -MinimumVersion $minimumVersion -Scope CurrentUser
}
Import-Module SharePointPnPPowerShellOnline -DisableNameChecking -MinimumVersion $minimumVersion

Connect-PnPOnline -Url "<your web url>"

# Enable modern page feature
Enable-PnPFeature -Identity "B6917CB1-93A0-4B97-A84D-7CF49975D4EC" -Scope Web -Force

See also