Upgrading your app for SharePoint

Once you have submitted an app to the Office Store or published it to your corporate app catalog, you will probably start planning the next version of your app. An important part of that planning is ensuring that the app upgrade process will be smooth for your users and their data. This post explains how SharePoint enables developers to correctly upgrade their apps and how Office Developer Tools can make the process even easier.

To enable upgrading for your app, you have to consider things beyond the implementation of your first version, and your main concern will be to keep your app updated without losing any data on the process. On the other hand, as a developer, you also want a comprehensive way to track your changes with each version submitted.

SharePoint provides you with fine grained control over how each element of your app for SharePoint is upgraded. Office Developer Tools for Visual Studio 2012 helps you declare all the necessary information and performs some of the steps automatically for you. In the following sections, I’ll briefly walk you through how upgrade works in apps for SharePoint, and then talk about how you can use the Office Developer Tools to simplify this work.

How app upgrade works

The upgrade for all elements at the app package level (that is, client Web Parts, host web custom actions, etc.) are tracked by the version specified in the app manifest. This means that once the user decides to upgrade an app for SharePoint, and if the version in the app manifest changes, SharePoint will find the difference in those files automatically and perform the upgrade for you.

For the files inside a WSP package in the app package (for example, lists or modules), you need to declare how SharePoint should handle them in an upgrade. They must be specified in a declarative way in their Feature manifest, along with the version range where the upgrade actions should be triggered. Here is an example:

<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
    <VersionRange EndVersion="">
        <ElementManifest Location="Pages\Elements.xml" />
        <ElementManifest Location="Scripts\Elements.xml" />
        <ElementManifest Location="Content\Elements.xml" />
        <ElementManifest Location="Images\Elements.xml" />
<ElementManifest Location="List1Instance\Elements.xml" />
ElementManifest Location="List1\Elements.xml" /> </
ApplyElementManifests> </VersionRange> <VersionRange BeginVersion="" > <ApplyElementManifests> <ElementManifest Location="List1Instance\Elements.xml" /> <ElementManifest Location="List1\Elements.xml" /> </ApplyElementManifests> </VersionRange> </UpgradeActions> <ElementManifests> <!-- Elements manifests are declare here.
Not relevant for this example
--> </ElementManifests> </Feature>

In this particular example, the new Feature version is, and this Feature manifest specifies the upgrade actions for the different element manifests included in the Feature. Supposing you have the feature which upgrades pages, scripts, content and images modules for previous versions, the element manifest for Pages, Scripts, Content, and Images need to be upgraded for the version smaller than Besides, a list was added in version This way, if the app is updated from version to version, the only modification SharePoint has to do for this Feature is to add the new list, as declared in the Feature manifest:

<VersionRange BeginVersion="" >
    <ElementManifest Location="List1Instance\Elements.xml" />
    <ElementManifest Location="List1\Elements.xml" />

There are many more actions we can declare in the Feature manifest, which are well documented on MSDN: Upgrading Features.

Office Developer Tools support for app upgrade

Office Developers Tools supports the process of creating an app upgrade in many ways. In fact, for most scenarios, you can simply rely on what the tooling does for you. The tools also provide the flexibility to customize the upgrade actions. I will explain each of these in the following sections.

Module files upgrade support

By default, when you add a new file to a module, it will be added when the user deploys the next version of the app. This configuration is set up in the module elements manifest that contains the file. In particular, the attribute that enables upgrade is “ReplaceContent="TRUE"”, which is declared in the file element. Here is an example of a default Page module elements manifest for an app for SharePoint:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Module Name="Pages">
    <File Path="Pages\Default.aspx"
          ReplaceContent="TRUE" />

If you do not want to have to replace a particular file during upgrade, just remove that attribute.

Feature manifest and app manifest version kept in sync

Besides the version of the app, Features of an app also have their own versions. The Feature version number needs to be updated to be larger than the previous version so that it can participate in the upgrade process. To make sure that the different version numbers are addressed when you update your app version number in the manifest editor, Office Developer Tools keeps the app and Feature version numbers in sync. This means that if you change the version of the app in the app manifest editor, the Feature version will automatically be changed to the same version.

Element manifests kept in sync with Feature manifest

Every time a new element manifest is added to the project, Office Developer Tools will modify the Feature manifest by adding that element manifest to the first version range inside the declared upgrade actions. In this way, all the web artifacts of your project will be brought up-to date by default.

Customize Feature upgrade actions using Office Developer Tools

There are two ways in which Office Developer Tools will help you editing the Feature manifest.

Update through Feature manifest template editor

You can access the Feature manifest editor by double-clicking the project Feature file, selecting the manifest tab, and then clicking Edit options at the bottom of the screen.

The editor looks like this:


Figure 1. Feature manifest editor.

At the bottom of the editor is an area where you can add your own declarations. By default, the editor adds all the elements that are already in the project. You can modify these elements by adding them in the manifest editor, and Office Developer Tools will automatically match it with the one in the project.

For example, consider the scenario at the start of this post. A new list was added in version, and you want your users who are using the previous version to get this new list through upgrading, but the upgrade should only apply to the new list. In that case, you would introduce this text in the editor to specify the new list manifests in UpgradeActions of the Feature manifest:

<Feature xmlns="http://schemas.microsoft.com/sharepoint/">
    <VersionRange EndVersion="">
    <VersionRange BeginVersion="">
        <ElementManifest Location="List1Instance\Elements.xml" />
        <ElementManifest Location="List1\Elements.xml" />

The actual Feature manifest will then become:


Figure 2. Feature manifest preview on editor after update.

Notice that Office Developer Tools always adds the project items to the first VersionRange element so they will be updated by default for all the artifacts in the project. If you only want a specific set of artifacts to be upgraded, you can specify an end version for the first version range, as the above sample does, to restrict when this action will be triggered.

Advanced Feature manifest editing

If the Feature manifest editor does not meet your needs, you can always edit the Feature manifest by hand. To do this, click Overwrite generated XML and edit manifest in the XML editor in the Feature Designer (see Figure 3 below). Be aware that after clicking that link, Office Developer Tools will no longer update the Feature manifest, and you will have to handle all changes manually.


Figure 3. Option for editing the Feature manifest manually.

In summary, this post explained how upgrade works in apps for SharePoint, and how Office Developer Tools can help you with the upgrade process. Let me know if you have any issues or feedback by adding a comment to this post or at the Developing Apps for SharePoint 2013 forum.

Happy coding!

~ Miguel Caballero Pinto| Software Development Engineer, Visual Studio Tools for Office & Apps for Office

Comments (5)

  1. Son Dambi says:

    There is a serious error in the logic of the VersionRange elements in this post. When you are upgrading the feature to, then the only existing instances of the feature are and, But the last VersionRange in this example IS NOT GOING TO BE APPLIED TO ANY of these existing instances. That's because the last VersionRange has a BeginVersion attribute set to So the actions in that VersionRange are only going to apply to instances that are ALREADY at version (or higher).  But none of them are!!!!

    There is a lot of misinformation about VersionRange floating around, including some of Microsoft's own documentation. One misconception is that the version of the instance of the feature gets updated at the beginning of the upgrade process. It actually happens at the end. So there's no point in mentioning the new version in any place in the feature manifest after the Version attribute of the Feature element, because no instance of the feature is going to have that version until after all the upgrade actions have already run.

    Another misconception is that the BeginVersion is ever useful. It isn't. It was a mistake to include it in the markup. Just as the EndVersion attribute can be used to ensure that an upgrade action does not occur a second time on a feature instance on which it has already occured, a BeginVersion can only have the effect of ensuring that a new upgrade action does not occur on feature instances that have not yet reached a certain version. But you never want to do that. After the upgrade finishes EVERY app instance is going to have the version number of the Version attribute in the Feature element; so they are all going to have the same version number. If you had a BeginVersion value in any of your VersionRanges, you would create a situation in which some instances of the feature with version X HAVE DIFFERENT COMPONENTS than other instances of the feature with THE VERY SAME VERSION number!

  2. Anton Vishnyakov says:

    Hi Miguel Caballero Pinto,

    Thanks for a great insight. That's quite helpful.

    However, there are some pros/cons about xml-based and code-based provision and upgrades.

    So, it comes to the first questions – is there any way to perform and control upgrades via code? Any ideas?

    Next, what about auto-hosted and provided-hosted apps. What could be a best practice for those?

    Finally, there are a lot of doubts about testing/unit testing/regression testing. What would you recommend to implement a regressing.upgrade testing for sp-hosted and other types of apps?


  3. Hi Son Dambi,

    Thank you very much for your feedback. I will update the blog post accordingly to make the example more meaningful and consistent.

  4. Hi Anton Vishnyakov,

    First of all, thank you for your comment. Find below more information about your questions:

    Is there any way to perform and control upgrades via code? Any ideas?

    It’s recommended to use declarative upgrade whenever possible, because SharePoint will optimize the upgrade and handle the upgrade errors in a safe way. Alternatively, developers can use app event receivers and CSOM to modify lists and pages etc. But then, they’ll have to remember to provide proper error handling so that if error happens, they will get rolled back. Otherwise, if they do it on the fly at runtime, the upgrade changes are immediate and permanent. Besides, developers will also want to be smart in the upgrade event receiver and check the state of the schema in some way, so the upgrade to v3 won't redo the v2 schema upgrade, etc. It’s similar to the usage of BeginVersion in the feature manifest.

    What about auto-hosted and provided-hosted apps. What could be a best practice for those?

    For Feature elements upgrade (i.e. lists) the process explained on the post is the same for auto hosted, provider hosted and SharePoint hosted. However, if you need to update your web components (i.e. a web page in your web project), then you have to handle it using other conventional methods.

    What would you recommend to implement a regressing.upgrade testing for sp-hosted and other types of apps?

    Here I am not exactly sure what is your scenario. If you meant how can you create automation tests on upgrading scenarios, I can suggest you to take a look to our continuous integration scripts that may help you on this purpose. Here is the link: officesharepointci.codeplex.com

  5. Ricky says:

    Microsoft published greatly expanded coverage of app upgrading yesterday. Search MSDN for "sharepoint 2013 app update"