App for SharePoint update process

For an update, you use the same product ID in the app manifest that you used for the original version. The version number in the app manifest should be greater than the version number of the original app or the most recent update.

Within 24 hours after you upload your update to an organization's app catalog, and within a week of uploading it to the Office Store, an indication that an update is available appears next to the app's listing on the Site Contents page of every website where it is installed. Users can click a link to update the app as shown in Figure 1. Available updates are also exposed in the tenant management UI.

Tip

When you are developing an update, you don't want to wait 24 hours every time you upload a new version to your test SharePoint app catalog. See Update an app without waiting 24 hours for information about how to immediately update an app. By default, SharePoint checks every 24 hours for updates to installed apps. A farm administrator can set this to another value by using the following SharePoint Management Shell command, where n is the number of hours between checks. Set-SPInternalAppStateUpdateInterval -AppStateSyncHours n If the value is set to 0, then the check is made every time the built-in timer job Internal App State Update executes, which by default is every hour. Farm administrators can use Central Admin to change the frequency of the timer job or run it immediately.

SharePoint 2013 will do the following when a user installs an update to an app for SharePoint. They do not necessarily occur in exactly this order, and some of them may occur in parallel. Also, if update fails, there is a complete rollback.

• SharePoint 2013 prompts the user to approve permissions requested by the app.

• SharePoint 2013 makes the app unavailable to users temporarily. This includes the app web, any Windows Azure Web Sites, and any Windows Azure SQL Databases that are part of the app.

• If the app is autohosted and includes a Windows Azure SQL Database, SharePoint 2013 uses the Data-Tier Application Package (DAC) functionality of SQL Server to determine whether the update changes the schema of any Windows Azure SQL Databases. If the schema changed, the database is updated. A backup copy of it is made first, so that a rollback is possible if the upgrade fails at later point.

  It is not possible for SharePoint 2013 upgrading infrastructure to make every kind of upgrade change on its own. For example, suppose that a new column is added that should have default values that are computed based on existing data, such as a new Risk rating field in a mortgage app that is computed based on Income, Home Price, and Interest Rate. SharePoint cannot determine what is needed for the Risk field. In such cases, you must add some update logic. You can put this logic in one of four locations:

  • In a data script inside the app package. Data scripts execute after any schema upgrade and after any pre- or postdeployment scripts in the DACPAC. If an error is encountered in a data script, the SharePoint upgrading infrastructure will roll back the app upgrade. Use data scripts to add data to the database. Only T-SQL, (not SQLCMD mode) can be used in a script in an autohosted app for SharePoint. There is no way to pass variables to the script at run time, so the script must not assume anything about the run-time environment other than that it has database owner rights to the database.

  • In a pre- or postdeployment script in the DACPAC that is executed as part of the DAC upgrade. Use these scripts for complex schema transformations that cannot be done merely by changing the database schema directly. For example, if you need to create a new table and move data from an old table to the new one because the schema of the old table is going to change, you can use a predeployment script to move the data to a temporary table. Then, in a postdeployment script (that executes after schema changes), copy the data into the new table and remove the temporary table. Just as in data scripts, only T-SQL can be used.

    Important

    Errors encountered in a pre- or postdeployment script do not trigger a rollback of the app installation. For this reason, whenever you have a pre- or postdeployment script, you should also have a data script that checks the success of the pre- and postdeployment scripts. If they have failed, the data script must throw an error. This is necessary to ensure that the app upgrading infrastructure will roll back the update. To learn important details about this practice, see How to: Use pre- and postdeployment scripts to update a SQL Database in autohosted apps for SharePoint.

  • In an UpgradedEventEndpoint web service, which you would create and register in the app manifest. This kind of web service can do anything an app can do, including accessing SharePoint with the client object model, and making calls to other web services.

  • In "first run after update" logic of the app itself. (The app can inspect its own version number when it starts.)

• If the app is autohosted and the update changes a Windows Azure Web Site component, SharePoint swaps the new version for the old with transaction protection, so a rollback is possible if it is needed.

  Note

  If the app is provider-hosted, you provide the update logic for all the non-SharePoint components of the app. For the most part, you update these components separately from the update of the app for SharePoint itself, just as you installed these components separately from the installation of the app. But there may be some changes that should only happen when a user is updating the app for SharePoint. This logic can go in an UpgradedEventEndpoint web service or in "first run after update" logic of the app itself.

• If the app contains a SharePoint solution package (.wsp), and the contents of the solution package have changed in any way, SharePoint does the following:

  • Makes a backup of the app web.

  • Tests the update of the backup.

  • If the test succeeds, updates the original app web. Note that the new .wsp file in the app package is used to update the Features and other elements in app web. (The update parts of the Feature schema have been expanded in SharePoint 2013.)

• SharePoint 2013 executes the UpgradedEventEndpoint web service, if any is registered in the app manifest.

• SharePoint 2013 makes the app and its components available again.

In some scenarios you may want to produce an entirely new app to replace an old one, rather than update the original one. The new app can have the same friendly name as the old, but it must be given a new product ID in the app manifest, and it will appear in the public Office Store and in the Add an App page of SharePoint websites as a distinct item.

Note

Items in an organization's app catalog are distinguished by the file name of the app package, not the product ID or the name of the app. If the new app has the same package file name as the old, it will replace the old one in the app catalog, and the old app will no longer appear on the Add an App page. If you enable versioning on the app package when you upload it to the catalog, the old version of the file (which is the old app) is still available in the item's history. You can download the old app package or revert to it, but there is no way to have both the old and new apps as separate items in the catalog or on the Add an App page, unless they have distinct file names.

In some cases, you might need to migrate data. For example, the new app might use a Windows Azure SQL Database that has a different schema from the old app. Or the new app might use a different data storage mechanism; for example, an external database instead of SharePoint lists. You must provide the code for data migration.

If your old data is somewhere that can be accessed by a remote event handler, you can implement migration logic in an InstalledEventEndpoint web service of the new app. Alternatively, if the new app has access to the old data, you can put the migration logic in code that runs the first time that a user starts the new app. If the old data cannot be accessed by both the remote handlers and the new app, you can create an upgrade of the old app that adds a data export capability and UI. Users would first update the old app, and then use it to export the data to a location where the new app can access it. You include the capability and UI to import data in the new app.

In principle, you can reuse an external data source, compute component, or other external component in the new app that was used in the old app. Consider, however, that when an app for SharePoint is uninstalled, the SharePoint 2013 infrastructure will uninstall everything that it installed, including the remote components of an autohosted app. Accordingly, it is generally a good practice for an app for SharePoint to depend on only components that it installed or external components that were not installed by any app for SharePoint.

Note

We recommend that if you implement an InstalledEventEndpoint or an UpgradedEventEndpoint that installs components, you should also implement an UninstallingEventEndpoint that uninstalls those same components. Doing so conforms to the design principles that apps should be self-contained and uninstall cleanly. However, data that would still be useful to users after the app is uninstalled should not be deleted. Websites created by an app, other than the app web, should usually be considered data.

If the old and new apps each contain an app web, consider that a new app web is created when your new app is installed. For this reason, you should not use the update-related XML markup in the SharePoint 2013 Feature schema. Such markup does not work because you are not updating existing SharePoint components.

• How to: Update apps for SharePoint

• How to: Update app web components in SharePoint 2013

• How to: Update host web components in SharePoint 2013

• How to: Create a handler for the update event in app for SharePoint 2013

• How to: Update remote components in apps for SharePoint

• Publish apps for SharePoint

• Important aspects of the app for SharePoint architecture and development landscape

• Deploying and installing apps for SharePoint: methods and options

• Data-Tier Application (DAC)