How to: Update apps for SharePoint

apps for SharePoint

Learn how to create and deploy an update for an app for SharePoint.

Last modified: March 09, 2015

Applies to: apps for SharePoint

You can update your app for SharePoint by using the updating support built into SharePoint 2013. Within 24 hours after you upload an updated version of the app to the organization's app catalog or the app is accepted at the Office Store, a notification that an update is available appears next to the app on Site Contents page of every website where it is installed. As you can see in Figure 1, a link is provided for users to immediately install the update.

Figure 1. App for SharePoint update process

The UI steps for updating an app

A user can install the update without first uninstalling the earlier version. The update infrastructure tests the update installation and rolls it back if there are any errors.

Important note Important

You cannot change the app type using the update system. For example, you cannot change an app from SharePoint-hosted to provider-hosted with an update. To make a change of type, you need to migrate from an old app to a new one. In particular, since the preview program for autohosted apps has been closed, you should be aware that cannot update an autohosted app to a provider-hosted app. You have to convert the app as explained in How to: Convert an autohosted app for SharePoint to a provider-hosted app.

Core concepts to know to update an app for SharePoint

Table 1. Core concepts for updating an app for SharePoint

Article title


Choose patterns for developing and hosting your app for SharePoint

Learn about the different types of apps for SharePoint. The updating process varies depending on the type.

App for SharePoint update process

Learn about the process for updating apps for SharePoint.

Upgrading Features

Learn how to update Features (SharePoint 2010 SDK).

Deploying and installing apps for SharePoint: methods and options

Learn about the methods for publishing, installing, and uninstalling an app for SharePoint.

Handle events in apps for SharePoint

Learn about remote event receivers in SharePoint 2013.

The following are the major steps that may be needed when you create an update for an app for SharePoint. Each step is discussed in detail in linked sections or articles. Not all the steps are required in every update project. What you must do depends on what components are already in your app and what components you are adding. Only the items marked with * are always required.

The following sections discuss practices you should follow and important points to consider as you are planning an update.

Decide whether you really have to update

For a provider-hosted app for SharePoint, improvements to the app do not necessarily require updating the app. If all the changes are to remote components, and those changes don't have to be reflected in SharePoint components, you can change the remote components without updating the app. As long as the URLs and connection strings that the SharePoint components use to access the remote components do not change, the app for SharePoint continues to work. For example, suppose that you add a button to a remote web application that reads a column from a SharePoint list that the web application did not previously read. If the column already exists on the list, you do not have to change anything in SharePoint. You can upload the revised webpage, and the revised code behind or JavaScript, to the remote web application. The new functionality is immediately available to users when they start the app for SharePoint.

Remember that updating is optional for users

When a new version of your app for SharePoint becomes available in the Office Store or the organization's app catalog, a message appears on the app's tile on the Site Contents page informing users that an update is available. It takes no more than 24 hours for this message to appear. But nothing in the SharePoint infrastructure forces users to update. So changes that you make to remote components must not break the older versions of the app. A general, but not quite universal, rule is that you should add things to remote components, but avoid deleting, renaming, moving, or changing the schema, connection string, or URL of any existing component.

If a remote component needs to know the version of the app instance that is calling it, you can pass this information from SharePoint. For example, you can add the app version as a query parameter on the StartPage URL of the app.

Create and debug the new version as if it were a brand new app

You should separate the development and debugging of the new version of the app from the debugging of the update markup and logic. To do this, uninstall the earlier version of the app from your development test SharePoint site. Save a backup copy of the app package file for the earlier version. Add and change components of the app as needed, and then test and debug them against the test site as if it is a brand new app you are creating from scratch.

Test the update with each earlier version of the app

When the new version of the app is functioning correctly as a "new" app, restructure the code and markup so that the project is an update of the old app. For example, increment the app version number as indicated in Major steps in updating an app. For more information about turning the project into an update, see the child topics of this topic.

When you are ready to test your update, retract the new version from the test site and redeploy the earlier version so you can test update logic. If you have shipped multiple previous versions of the app, install each earlier version on a different subweb of your test site. Then upload the latest version of the app to your test site's app catalog and update every instance of the app. Verify that each has the latest app version number and the latest version of all components. If there is an app web in the app, verify that the app web components have been deployed using the procedure in Verify deployment of app web components.

Update an app without waiting 24 hours

When developing an update for an app on your SharePoint test site, it is impractical to wait 24 hours between updates. You (and users on a production SharePoint site) can update an app immediately after it is uploaded to the Office Store or the organization's app catalog with these steps:

To immediately update an app

  1. After the latest update is uploaded to the app catalog, open the Site Contents page on the website where the app is installed and choose the ... button on the app's tile.

  2. On the callout that opens, choose the About tab. On the About page that opens, there is a notice that a new version is available.

  3. Choose the Get It button. The Site Contents page reopens, and there is a notice on the app's tile that the app is being updated.

Figure 2 illustrates these steps.

Figure 2. Process of immediately updating an app for SharePoint

Immediate app upgrade process
Note Note

If you need to see the "update available" notice on the app's tile more frequently than every 24 hours, you can use the method described in Update process for an app for SharePoint to make the notice appear immediately.

After making a backup copy of the Visual Studio 2012 project folder, open the app project. Open app manifest and raise the version number on the General tab of the manifest designer.

If the updated version of the app needs more (or fewer) permissions to components of the host web, make changes as needed to the AppPermissionRequests section of the app. In Visual Studio 2012, use the Permissions tab of the manifest designer.

If the updated version of the app has prerequisites that the earlier versions did not have (or no longer has some prerequisites that earlier versions had), make changes as needed to the AppPrerequisites section of the app. In Visual Studio 2012, use the Prerequisites tab of the manifest designer.

© 2015 Microsoft