Pnp-sites-core: Get-PnPProvisioningTemplate -Handlers PageContents returns just sub site's homepage

[mpowney]

Category

[x] Bug
[ ] Enhancement

Environment

[x] Office 365 / SharePoint Online
[ ] SharePoint 2016
[ ] SharePoint 2013

Expected or Desired Behavior

When using Get-PnPProvisioningTemplate with the "PageContents" Handler, all pages in the site's "SitePages" RootFolder, should be extracted.

Observed Behavior

Only contents from the site's welcome page is extracted with the "PageContents" handler.

Steps to Reproduce

1. Create a sub site with the Site Pages feature turned on
2. Create any number of modern pages in the Site Pages
3. Connect to the newly created sub site with Connect-PnPOnline
4. Create a folder relative to the current PowerShell directory: .\Documents\temp
5. Execute the following PnP PowerShell cmdlet: Get-PnPProvisioningTemplate -Handlers PageContents | Out-File "$pwd\Documents\temp\site-page-1.xml"

[jansenbe]

Hi @mpowney, the fact that only the home page is extracted is a conscious decision we took as we don't see the PnP provisioning engine as a migration tool. This does not mean that you can't realize your scenario via an extensibility handler: check out https://github.com/SharePoint/PnP/tree/dev/Samples/Provisioning.Extensibility.Pages for a sample of an extensibility handler that does export all pages from a site.

[mpowney]

My scenario is not to use the cmdlet as a migration tool, it is to create a template that involves one or two pages pre loaded in to the site.

It's not clear that this is the intention without looking at code. On first blush you'd expect a handler called "PageContents" to not be specific to only the home page. Perhaps the handler should be renamed to "HomepageContents" for clarity? Or some documentation written to make it clear?

Or perhaps it might help to have an additional parameter passed in for PageContents, to specify the name of the page you want to extract the contents of.

[jansenbe]

Fair feedback, we definitely should do a better job at documenting things. This however is an open source community project and depending on the time folks can invest in this next to their day to day tasks.

[mpowney]

Yeah I understand its an open source project; I'd happily make the change myself and submit a PR, but would want to confirm the approach first matches the team's expectations.

[mpowney]

Further info on my real-world scenario... we're an ISV that offer a templating capability to customers, and we've integrated PnP templating for supportability and future-proofing. We need to offer an easy support/cheat sheet for customers to extract templates after the provisioning engine is deployed.

Most other scenarios, where the customer changes, say, a list schema, or a content type, in their template site, are covered. We set the expectation that they install the required tool set, i.e. pnp powershell cmdlets, and run a single command to re-generate the template.

With this limitation on the SitePages handler, its difficult to offer a single step process to produce the template. The only practical method is to create a series of templates, one per page, and explain the steps required to a) set the home page of the template site to each page required in the PnP template, and then b) perfrom the Get-PnPProvisioningTemplate. The output is multiple templates, which subsequently become unwieldy in themselves.

This pnp-sites-core project is a god send; there is so much to leverage from it. Now that modern pages are starting to see real-world adoption, solving this issue would improve the continued use of pnp templating.

[jansenbe]

Why is using an extensibility handler not an option? The SitePages handlers was refactored to make it really easy for an extensibility handler to export all pages as demonstrated in the sample I shared earlier. You could for example offer them a script that pulls down the matching version of PnP PowerShell and your extensibility handler and then runs the extraction with the handler included.

[mpowney]

I'll take a look at the sample you shared..

[mpowney]

An extensibility handler similar to the one shared is possible, but the functionality I'm looking for is covered by the PageContents handler, with the one exception of what pages it is designed to export.

I can't think of a real-world scenario where you'd want to export a template with just the homepage included. And it seems counterintuitive behaviour to what the name of the handler is, i.e. it's name is with the plural (PageContentS), which implies it will export multiple pages, but it never would do that in its current form.

But yes, creating an extensibility handler is something we would have to consider without any changes to the PageContents handler.

[KEMiCZA]

@mpowney I feel like the engine should by default export all SitePages. Imagine you have a navigation link set to one of these pages. Exporting the navigation will work fine, but when applying the template the provisioning will _crash_ because the site page file is not found.

The logic is already built in for one site page, in my custom solution I was able to easily extend this to other pages and without changing the _applying_ logic. Why duplicate the code by using a Extensiblity handler, when the logic is already provided for the homepage?

Maybe provide a flag within the _ProvisioningTemplateApplyingInformation_ class to allow extraction of all site pages.

[jansenbe]

We refactored sites core to make it really easy to reuse the page export logic in an extensibility handler as is shown in https://github.com/SharePoint/PnP/tree/dev/Samples/Provisioning.Extensibility.Pages. So there's no need for code duplication. Having a switch is something we can think about, thanks for the feedback.

[kitzler-walli]

I agree it should export all pages by default or at least with some sort of switch.
Currently it's faster to set the different pages as homepage and export each one of them separately than fiddling with an extension.