Upgrade a Deployed SharePoint Framework Solution using Upgrade Actions

Published: 26 July 2017

This is a continuation post in the SharePoint Framework Development series, In a previous article, we saw how to set up the development environment for SharePoint Framework. We also saw the basic Hello World web part creation and  how to provision SharePoint List with custom Site Columns and Content Type here. In this article, we will see how to upgrade the previous solution that was used to deploy a list so that we can deploy a second list along with the same solution.The main code files used for this demo is uploaded here

Upgrade the SharePoint Framework Solution

Once we have deployed the solution if we must make some changes at a later point, upgrade actions are available. Deploying without an upgrade will install a fresh copy of the solution. To retain the existing data, we will go with the upgrade option. However, to do the upgrade, we should add a new element file say elementsV2.xml

Download the guide to setup SharePoint Framework.

Upgrade the solution and add a new list

In our case, we are trying to add a new list along with the previously deployed solution(The previous solution had already deployed a list named Employee ). In the new elements file, we will specify the list instance declaration for the new list. 

We will also add an upgrade action which will contain the information about the newly added elements.xml file. It contains the relative location of the new elements file with respect to the feature ID.

As the last step we have to update the package-solution.json file by adding elementsV2.xml to the elementsmanfiest tag and we will also add the upgrade actions file reference.Before updation the json file looks like the one below:

After adding the new elements file and upgrade action reference, we will also increment the version number to

Package and Deploy the Solution

Save the files and run gulp serve to package the solution file. Now let’s go ahead and upload the sppkg solution file to SharePoint App Catalog. 

Upon clicking on OK it will give a warning whether to replace it with the new solution. Click on Replace It so that the new version is added. 

We can see that the version has upgraded from to

Heading over to the site contents we can see that the new list ‘ListAddedViaUpgrade’ has been provisioned in addition to the existing Employee list.

Resolve Package Errors

Once the solution has been uploaded to SharePoint, ensure that there are no errors mentioned in the below columns. 

At times if we have some error in the package, it will be displayed as shown below. Ensure that we resolve any such errors by analyzing the error message. The below error was thrown because of a white space at the beginning of the Elements.XML file. 


Thus, we saw how to upgrade the SharePoint Framework solution using upgrade actions. Stay tuned for more SharePoint Framework articles. 

Download the guide to setup SharePoint Framework.

Join 8,000 subscribers and receive instant access to

Devendra's Library of Resources for SharePoint Developers

About Author

Priyaranjan is a SharePoint Consultant and Microsoft MVP with 10 years experience in developing and deploying SharePoint Applications.He has worked on various SharePoint iterations starting from MOSS 2007 through SharePoint 2016 and Office 365. He is a frequent contributor at Microsoft TechNet and has won 33 Gold Medals in various TechNet Wiki Guru Monthly Competitions.As a token of appreciation for the TechNet community activities, he was interviewed by Microsoft Program Manager,Ed Price. He has also published 300 Articles and 4 SharePoint Ebooks in different technical communities.You can find his Microsoft TechNet contributions here