SPFx Extension - On Demand Activation

SPFx Extensions are used to extend the SharePoint experience. For example, custom header or footer, custom view for a list field etc.

SPFX Extensions can be deployed and activate in three ways:

1. Site Scoped Local Activation - SPFx extensions are installed explicitly on a site and are then available like any other app on a site, and can be activated from site contents page. 
2. Tenant Scoped on demand activation - Tenant wide deployed but not activated - Extension is available to all sites in the tenant but activation can be done via script alone. We will explore this way in more detail in this blog.
3. Tenant Scoped and activated by default - Extension is deployed tenant wide and also activated automatically across all the sites.

Tenant Scoped but on demand activation

I created my extension using the following options that yeoman generator walks me through:

Let's create a new SharePoint solution.

? What is your solution name? on-demand-extension

? Which baseline packages do you want to target for your component(s)? SharePoint Online only (latest)

? Where do you want to place the files? Create a subfolder with solution name

Found npm version 6.9.0

? Do you want to allow the tenant admin the choice of being able to deploy the solution to all sites immediately without running any feature deployment or adding apps in sites? Yes

? Will the components in the solution require permissions to access web APIs that are unique and not shared with other components in the tenant? No

? Which type of client-side component to create? Extension

? Which type of client-side extension to create? Application Customizer

Add new Application Customizer to solution on-demand-extension.

? What is your Application Customizer name? custom-header

? What is your Application Customizer description? custom-header

Now a folder with the base code for SPFx Extension is created. Open the folder in your code editor, and open the package-solution.json, you will see the following:

{ "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json", "solution": { "name": "on-demand-extension-client-side-solution", "id": "dafe6ae3-7d52-4e85-b784-728be2a7660c", "version": "1.0.0.0", "includeClientSideAssets": true, "skipFeatureDeployment": true, "isDomainIsolated": false, "features": [ { "title": "Application Extension - Deployment of custom action.", "description": "Deploys a custom action with ClientSideComponentId association", "id": "8e500ccf-e147-480d-92b5-9cef681c2eb8", "version": "1.0.0.0", "assets": { "elementManifests": [ "elements.xml", "clientsideinstance.xml" ] } } ] }, "paths": { "zippedPackage": "solution/on-demand-extension.sppkg" } }

skipFeatureDeployment is the property that determines if this SPFx solution will be deployed tenant wide or not. If it is set to true means it will be deployed tenant wide.

After the isDomainIsolated property you can see a "features" property, this feature is used by SharePoint to automatically activate the SPFx extension when we select the option to deploy tenant wide. If you dont want that to happen  i.e. you want the extension to be deployed tenant wide but dont want it to be activated automatically then remove the feature property. Since we want to do On Demand Activation, we will remove the features property and also the Assets folder which is located under the sharepoint folder.

Lets build the package using

gulp bundle

gulp package-solution

gulp serve --nobrowser

Drag and drop the solution package file from the \sharepoint\solution folder to app catalog site, you will be prompted to trust the solution, select the option to make the solution available to all the sites in the organization and click Deploy.

You will notice you are not seeing the default prompt that we see when an extension is available on a site. That is because we have still not activated the solution to a particular site. Lets activate the solution via power shell,  use the following commands:

  Connect-PnPOnline

Add-PnPCustomAction -Name "Extension ABC" -Title "Ext Title"

 -Location "clientSideExtension.ApplicationCustomizer"

 -ClientSideComponentId

Client Side Component Id can be obtained from the manifest file which resides under   

\src\extensions\customHeader\CustomHeaderApplicationCustomizer.manifest.json

Following is the content of that manifest file

{

"$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-extension-manifest.schema.json", "id": "186751b2-ff1d-42d9-bada-2ff7c7b9ca0f", "alias": "CustomHeaderApplicationCustomizer", "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 }

The Id property in the above json file is the ClientSideComponentId

So our power-shell command will look like this:

  Connect-PnPOnline

Add-PnPCustomAction -Name "Extension ABC" -Title "Ext Title"

 -Location "clientSideExtension.ApplicationCustomizer"

 -ClientSideComponentId 186751b2-ff1d-42d9-bada-2ff7c7b9ca0f 

Now our extension solution is active on that particular site.

Thanks for reading, please do share your experiences around SharePoint extensions.