Deploying and installing SharePoint Add-ins: methods and options

SharePoint Add-ins

Learn about the methods for publishing, installing, and uninstalling a SharePoint Add-in.

Last modified: September 17, 2015

Applies to: apps for SharePoint | Office 365 | SharePoint Add-ins | SharePoint Foundation 2013 | SharePoint Server 2013

Note Note

The name "apps for SharePoint" is changing to "SharePoint Add-ins". During the transition, the documentation and the UI of some SharePoint products and Visual Studio tools might still use the term "apps for SharePoint". For details, see New name for apps for Office and SharePoint.

You can upload your SharePoint Add-in to either the public Office Store or to an organization's private add-in catalog. A private add-in catalog is a dedicated site collection in a SharePoint 2013 web application (or a SharePoint Online tenancy) that hosts document libraries for SharePoint Add-ins and Office Add-ins. Putting the catalog into its own site collection makes it easier for the web application administrator or tenant administrator to limit permissions to the catalog.

If the add-in is uploaded to the Office Store, Microsoft runs some validation checks on it. For example, it checks whether the add-in manifest markup is valid and complete and verifies that any SharePoint solution packages (.wsp files) that are included do not include disallowed elements or Features with a scope broader than Web. The content of the package is also inspected for objectionable content. If the add-in passes all tests, the add-in package is wrapped into a file and signed by Microsoft.

Note Note

When you are developing your add-in and deploying it with Microsoft Office Developer Tools for Visual Studio, the add-in is directly installed in the target test SharePoint site. Since it is not passing through the Office Store, the validation checking described above does not occur.

Uploading a SharePoint Add-in to an organization's add-in catalog is as easy as uploading any file to a SharePoint Foundation document library. You fill out a pop-up form in which you supply the local URL of the add-in package and other information, such as the name of the add-in. When the add-in is uploaded to an organization's add-in catalog, similar checks take place and add-ins that do not pass are marked as invalid or disabled in the catalog.

Tenant administrators and SharePoint 2013 web application administrators can shop for SharePoint Add-ins on the Office Store. To open the Office Store, the administrator selects Add an Add-in on the Site Contents page and then selects SharePoint Store in the Your Add-ins page. This opens a SharePoint Store page that the administrators can use to discover and learn about SharePoint Add-ins that vendors are offering. (They can also do this on Add-ins that require a prerequisite that is not installed on the administrator's web application or tenancy appear dimmed and are unavailable in the add-in store. For example, if an add-in requires Search Services and this is not installed, the add-in appears dimmed. Administrators can sort, filter, and browse the list of add-ins, read about the add-ins, see add-in reviews, and purchase licenses for an add-in.

When an administrator decides to purchase a license, she must accept the terms and conditions of purchase and agree to the permissions that the add-in must have in order to execute, such as read access to lists or full control access to the site collection.

When one or more licenses for an add-in are purchased, the licenses are downloaded to the web application or tenancy. The add-in is not automatically downloaded and installed when the license is purchased, although administrators have the option to combine installation with license purchase.

Users install add-ins from the Your Add-ins page. This page has a merged listing of the following:

  • SharePoint Add-ins from the web application's (or the tenant's) organization add-in catalog.

  • SharePoint Add-ins from the Office Store for which the organization or tenant already owns a site license or a license which has been assigned to the user.

All the add-ins that the user can install immediately are listed, and with few exceptions only add-ins the user can install immediately are listed. Users can filter the add-ins included on the page to include only add-ins in the organization's add-in catalog. When an add-in is installed, it appears in the list of add-ins on the Site Contents page of the website to which it is installed.

Website owners install SharePoint Add-ins from the Your Add-ins page as described earlier in this topic. Installation creates an instance of the add-in. For more information about installing add-ins, see Add SharePoint Add-ins to a SharePoint 2013 site.

Note Note

Sometimes a temporary loss of a network connection can block installation. If installation fails for any reason, the installation infrastructure will retry three times. If it does not succeed, an indication of the failure appears in the UI. Users can retry the installation later.

Website owners can uninstall an instance of a SharePoint Add-in through the SharePoint UI. Uninstallation of an instance of a SharePoint Add-ins is clean. This means that everything installed by the add-in is uninstalled.

However, components that an add-in uses, but that are installed separately from the installation of the add-in, are not removed. For example, suppose an add-in has a remote web page with buttons that create lists on the host web. Uninstallation of the add-in removes the add-in's tile from the Site Contents page which, in turn makes the remote page effectively inaccessible or unusable for end users, but it does not remove the lists that were created with the add-in. SharePoint does not keep a record of which lists on the host web were created with the add-in and which ones were created by users in the SharePoint UI, so it can't delete lists that were created with the add-in. This is generally desirable behavior because the lists may have data that remains useful to users even after the removal of the add-in that created the lists.

If the SharePoint Add-in includes an add-in web, the add-in web is deleted. This provides a cleaner uninstall than systematically deactivating features and reversing the deployment of the add-in's internal .wsp file.

Note Note

When a user removes an add-in, it is moved to the first stage Recycle Bin. Deleting it from there moves it to the second stage Recycle Bin. If it is deleted from the second stage Recycle Bin, then it is completely uninstalled and cannot be restored.

The add-in's permissions are also revoked when it is removed (recycled), according to these rules:

  • Web-scoped permissions are always revoked.

  • If there is no other instance of the add-in in the site collection, site collection-scoped permissions are also revoked.

  • If there is no other instance of the add-in in the site subscription (tenancy), tenant-scoped permissions are also revoked.

The UninstallingEventEndpoint web service, if one is registered in the add-in manifest of the add-in, executes at the beginning of the uninstallation process (which occurs when the add-in is removed from the second stage Recycle Bin). It is a best practice to have an UninstallingEventEndpoint web service if you have an InstalledEventEndpoint web service and to design the UninstallingEventEndpoint service to reverse anything done in your InstalledEventEndpoint service. For more information, see Handle events in SharePoint Add-ins.