Installing, Uninstalling, and Upgrading Sandboxed Solutions in SharePoint 2010

Applies to: SharePoint Foundation 2010

Available in SharePoint Online

This topic describes how site collection administrators can install, uninstall, and upgrade sandboxed solutions.

Warning

The Sandbox Solution framework provides a mechanism for executing user-provided code outside of the IIS worker process. The Sandbox Solution framework should not be used as a mechanism for enforcing security boundaries when executing user code. Sandbox Solutions are not supported as a security boundary with user code, especially code of unknown origin. We advise against executing Sandbox Solutions of unknown origins.

Installing a Sandboxed Solution

Just as with a farm solution, there are two steps to installing a sandboxed solution. In the context of sandboxed solutions, these two steps are called uploading and activating.

  • Upload stage: The upload stage consists of uploading a sandboxed solution to the solution gallery of a site collection. This parallels adding a farm solution.

  • Activation stage: The activation stage occurs after the solution is uploaded to a solution gallery. When a solution is uploaded, it is still functionally inert. Activating the solution makes it operate within the site by deploying files, registering event receivers, and running solution validation. This parallels deploying a farm solution. If a sandboxed solution includes a Feature that is scoped to the site collection level, the Feature is automatically activated when the solution is activated.

A sandboxed solution is installed by a site collection administrator to the site collection's solution gallery. This gallery also shows the current resource usage, average resource usage over the past two weeks, and the status of each sandboxed solution. For more information about the resource usage and monitoring system for sandboxed solutions, see Resource Usage Limits on Sandboxed Solutions in SharePoint 2010.

The following are the steps a site collection administrator takes to install a sandboxed solution.

To install a sandboxed solution

  1. From a page in the site collection, click Site Actions, and then select Site Settings.

  2. On the Site Settings page, click Solutions under the Galleries heading.

  3. On the Solutions tab of the Server ribbon, click Upload Solution.

  4. In the Upload Solution dialog box, click Browse, and browse to the sandboxed solution package (.wsp file). Click Open.

    The solution package is now in the site collection's solution gallery, but it is not yet deployed.

  5. In the Activate Solution dialog box, click Activate to activate the solution.

    Note

    If the sandboxed solution package contains a Feature that is scoped to the site collection level, the Feature is activated automatically. Any Features that are scoped to the website level must be activated on the Manage site features page at https://servername/site/subsite/_layouts/managefeatures.aspx. When you add a sandboxed solution package through the object model, both site collection–scoped and website-scoped Features must be activated on the Manage site features page at https://servername/site/subsite/_layouts/managefeatures.aspx.

Note

Other ways to install a sandboxed solution:

  • A farm administrator can also install a sandboxed solution to a site collection by using SharePoint Management Shell (Windows PowerShell). The commands are Add-SPUserSolution and Install-SPUserSolution.

  • On your development computer, in Microsoft Visual Studio, you can perform all installation steps by selecting Deploy Solution on the Build menu.

Uninstalling a Sandboxed Solution

There are also two steps to uninstalling a sandboxed solution.

  • Deactivation stage: A site collection administrator can deactivate a sandboxed solution from the site collection's solution gallery. Deactivation reverses most of the deployment actions of activation and, thus, turns off various capabilities of the solution. (If a solution that contains a Web Part is deactivated after the Web Part is added to a page, the Web Part displays an error instead of the usual information contained in the Web Part. The Web Part does not entirely disappear because deactivation does not undeploy the Web Part's .webpart file.)

  • Deletion stage: The deletion stage occurs when an administrator chooses to delete a sandboxed solution from the solution gallery. When the administrator chooses to delete a solution, additional validations and checks occur to warn the administrator of the negative consequences of an unintended deletion. A sandboxed solution cannot be deleted if it is still activated. When a sandboxed solution is deleted, it is moved into the Recycle Bin and can be restored or deleted permanently from the Recycle Bin.

Note

Other ways to uninstall a sandboxed solution include the following:

  • A farm administrator can deactivate and delete a sandboxed solution from a site collection by using SharePoint Management Shell (Windows PowerShell). The commands are Uninstall-SPUserSolution and Remove-SPUserSolution.

  • On your development computer, in Visual Studio, you can perform all uninstallation steps by selecting Retract Solution on the Build menu.

Upgrading a Sandboxed Solution

A site collection administrator upgrades a sandboxed solution by installing a new sandboxed solution package (.wsp file) that has the same solution ID as the existing sandboxed solution but a different hash code.

If the sandboxed solution contains any Features, feature upgrade actions are also processed: During upgrade, the Feature definitions for the existing solution are compared with the Feature definitions for the new solution. Existing Feature definitions are upgraded on the site. All new Feature definitions are activated on the site. (Incoming requests for the sandboxed solution fail during the upgrade process.)

Note

A farm administrator can upgrade a sandboxed solution in a site collection by using SharePoint Management Shell (Windows PowerShell). The command is Update-SPUserSolution (not Upgrade-SPUserSolution).

See Also

Concepts

Sandboxed Solutions Architecture in SharePoint 2010

What Can Be Implemented in Sandboxed Solutions in SharePoint 2010

Other Resources

Sandboxed Solutions in SharePoint 2010

Sandboxed Solutions Resource Center | SharePoint 2010

SharePoint Developer Team Blog

SharePoint Developer Center