Tuesday, October 10, 2017

Deploy a SharePoint Framework application customizer tenant wide

Creating application customizers which are available to all site collections is a very useful feature. Especially when it comes to site provisioning solutions. In my current project I’m creating a top banner which shows if the Office 365 Group is allowed to have external members, or if the team site can be shared with external users. This extension is installed on all new sites during creation.

Want to know more about a custom self-service solution for Office 365 Groups? Join me at ESPC November 16th 2017 where this post will be part of the solution demoed.

image

When creating your SPFx project make sure to answer yes to the question about deploying to all sites immediately. This will not enable the customizer right away, but it’s available for you to programmatically add later.

image

Once you have built and deployed your extension to the app catalog (see the official docs for more information), it’s time to enable the customizer.

Any API will work, but I’ll show two methods. Using PnP PowerShell and a PnP Provisioning template.

PnP PowerShell

Open up the .manifest.json file for your extension which looks something like below

{
  "$schema": "https://dev.office.com/json-schemas/spfx/client-side-extension-manifest.schema.json",

  "id": "b513cc49-8d38-4b41-9af8-6ad3ee4466b3",
  "alias": "ExternalDisclaimerApplicationCustomizer",
  "componentType": "Extension",
  "extensionType": "ApplicationCustomizer",

  // The "*" signifies that the version should be taken from the package.json
  "version": "*",
  "manifestVersion": 2,

  // If true, the component can only be installed on sites where Custom Script is allowed.
  // Components that allow authors to embed arbitrary script code should set this to true.
  // https://support.office.com/en-us/article/Turn-scripting-capabilities-on-or-off-1f2c515f-5d7e-448a-9fd7-835da935584f
  "requiresCustomScript": false
}

Make a note of the id and alias, and pick a site you want to apply the extension to. Connect to the site and add the extension as a custom action and you should be all set.

Connect-PnPOnline https://contoso.sharepoint.com/teams/somesite
Add-PnPCustomAction -ClientSideComponentId b513cc49-8d38-4b41-9af8-6ad3ee4466b3 `
-Name ExternalDisclaimerApplicationCustomizer `
-Title ExternalDisclaimerApplicationCustomizer `
-Location ClientSideExtension.ApplicationCustomizer

PnP Provisioning Template

Below is a PnP template for the same customizer above.

<?xml version="1.0"?>
<pnp:Provisioning 
    xmlns:pnp="http://schemas.dev.office.com/PnP/2017/05/ProvisioningSchema">
    <pnp:Preferences Generator="OfficeDevPnP.Core, Version=2.19.1710.0, Culture=neutral, PublicKeyToken=null" />
    <pnp:Templates ID="CONTAINER-TEMPLATE-EXTERNAL-DISCLAIMER">
        <pnp:ProvisioningTemplate ID="TEMPLATE-EXTERNAL-DISCLAIMER" Version="1" BaseSiteTemplate="GROUP#0" Scope="RootSite">
            <pnp:CustomActions>
                <pnp:SiteCustomActions>
                    <pnp:CustomAction
                        Title="ExternalDisclaimerApplicationCustomizer"
                        Name="ExternalDisclaimerApplicationCustomizer"
                        Location="ClientSideExtension.ApplicationCustomizer"
                        ClientSideComponentId="b513cc49-8d38-4b41-9af8-6ad3ee4466b3"
                        ClientSideComponentProperties="{}" />
                </pnp:SiteCustomActions>
            </pnp:CustomActions>
        </pnp:ProvisioningTemplate>
    </pnp:Templates>
</pnp:Provisioning>

Once saved as a template file you can apply it to your site using the Apply-PnPProvisioningTemplate cmdlet.

Connect-PnPOnline https://contoso.sharepoint.com/teams/somesite
Apply-PnPProvisioningTemplate -Path extension.xml

There is also a PnP webcast showcasing this feature.

No comments:

Post a Comment