Sandboxed solutions overview (SharePoint Server 2010)

 

Applies to: SharePoint Foundation 2010, SharePoint Server 2010

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.

A Microsoft SharePoint Server 2010 solution is a deployable, reusable package that can contain features, site definitions, and other functionality. Solutions can be enabled or disabled individually. You can deploy a solution directly onto your SharePoint Server farm, or you can deploy the solution into a sandbox. A sandbox is a restricted execution environment that enables programs to access only certain resources, and that keeps problems that occur in the sandbox from affecting the rest of the server environment. Solutions that you deploy into a sandbox, which are known as sandboxed solutions, cannot use certain computer and network resources, and cannot access content outside the site collection they are deployed in. For more information about solutions, see Solutions Overview (https://go.microsoft.com/fwlink/p/?LinkID=156638).

Because sandboxed solutions cannot affect the whole server farm, they do not have to be deployed by a farm administrator. Sandboxed solutions can be deployed by a site collection administrator or, in certain situations, by a user who has the Full Control permission level at the root of the site collection. However, only a farm administrator can configure sandboxed solutions–related settings such as load balancing, tiers, quotas and resource points, and only a farm administrator can promote a sandboxed solution to run directly on the farm, outside the sandboxed environment.

This article introduces the concepts that are related to sandboxed solutions, describes the uses and benefits of sandboxed solutions, explains the differences between sandboxed solutions and solutions that are deployed on the farm, summarizes how sandboxed solutions are deployed, describes the sandboxed solution service, explains resource points and quotas, and describes the tasks associated with administering sandboxed solutions. This article does not contain detailed procedures about how to configure sandboxed solutions or to deploy sandboxed solutions. For information about how to perform specific tasks that are related to sandboxed solutions, see Sandboxed solutions administration (SharePoint Server 2010) and Installing, Uninstalling, and Upgrading Sandboxed Solutions (https://go.microsoft.com/fwlink/p/?LinkId=220252).

In this article:

  • Use and benefits of sandboxed solutions

  • Understanding sandboxed solutions

  • Deploying sandboxed solutions

  • Understanding the sandboxed solutions service

  • Understanding quotas and resource points

  • Administering sandboxed solutions

Use and benefits of sandboxed solutions

There are two common scenarios where it is appropriate to use sandboxed solutions:

  • When an organization wants to run code for employees on a production SharePoint Server site, and that code has not been rigorously reviewed and tested.

  • When a hoster wants to let the owners of hosted SharePoint Server sites upload and run custom code.

The main benefits of using sandboxed solutions are as follows:

  • Sandboxed solutions can be added to a production SharePoint Server environment without the risk of affecting processes outside the sandbox.

  • Site collection administrators can deploy sandboxed solutions. This frees farm administrators from this task.

  • Scalability and flexibility are increased because sandboxes run in a separate process that can be restricted by quotas, and their effect on the farm can be monitored.

  • A solution does not have to be modified or recompiled if it is moved from a sandbox to running directly on the farm.

Understanding sandboxed solutions

Solutions are packaged as .wsp files that can contain features, site definitions, Web Parts, and assemblies. There are two kinds of solutions: farm and sandboxed. Farm solutions are deployed on front-end Web servers by a farm administrator, have full access to the server object model, and are not subject to any usage limits. By comparison, sandboxed solutions can be deployed by a site collection administrator — or by a user who has the Full Control permission level at the root of the site collection — into the solution gallery for a site collection. Sandboxed solutions have limited access to the server object model and run in a security restricted context that provides isolation and monitoring of the sandboxed solution's code. Farm administrators can enable or disable sandboxed solutions and set usage limits to protect servers in the farm from malicious code. For more information about solutions, see Building Blocks: Solutions (https://go.microsoft.com/fwlink/p/?LinkId=220253).

What sandboxed solutions cannot do

A SharePoint Server solution must contain the configuration file that is named manifest.xml, and may also contain additional configuration files and assemblies. If the solution will run in a sandbox, the assembly and configuration files are limited in what they can do.

The following list identifies the most common things that an assembly that will run in a sandbox cannot do:

  • Connect to resources that are not located on the local farm.

  • Access a database.

  • Change the threading model.

  • Call unmanaged code.

  • Write to disk.

  • Access resources in a different site collection.

For more information about what a sandboxed solution can and cannot do, see What Can Be Implemented in a Sandboxed Solution (https://go.microsoft.com/fwlink/p/?LinkId=220254) and Restrictions on Sandboxed Solutions (https://go.microsoft.com/fwlink/p/?LinkId=220255).

Understanding load balancing for sandboxed solutions

SharePoint Server provides two load-balancing schemes that are used to determine which server to run a sandboxed solution on. Farm administrators can select one of the following load-balancing schemes to apply to sandboxed solutions across the farm:

  • Local load balancing   The sandboxed solution runs on the same server that received the request.

  • Remote load balancing   The server that the sandboxed solution runs on is selected based on solution affinity, and the sandboxed solution is run on a server where it is already loaded and has already been run. This saves time in servicing the request for the solution.

Regardless of which load-balancing scheme that you select, the sandboxed solutions service must be running on each server on which you want to run sandboxed solutions.

Note

The sandboxed solutions service has different names, depending on where you access the service. In the SharePoint Central Administration Web site, the service is called the Microsoft SharePoint Foundation Sandboxed Code Service. In the Services console on the server, the service is called SharePoint User Code Host service. To avoid confusion, this article refers to the service as the "sandboxed solutions service."

You can increase the isolation of sandboxed solutions by using remote load balancing and by running the sandboxed solutions service only on specific servers. In a production environment, we recommend that you use remote load balancing and dedicate a separate server to running sandboxed solutions. For information about how to decide which load-balancing scheme to use, see Plan to load balance sandboxed solution code in Plan sandboxed solutions (SharePoint Server 2010).

Comparison of sandboxed and farm solutions

The following table compares aspects of solutions that run in a farm to solutions that run in a sandbox.

Aspect Farm Sandbox

Deployment process

Add the solution, and then deploy it to the farm.

Upload the solution to a site collection, and then activate it in the site collection.

Who can deploy

Farm administrator.

If the solution contains an assembly, only a site collection administrator can deploy it. If the solution does not contain an assembly, a user who has the Full Control permission level at the root of the site collection can deploy it.

Data access

Unrestricted.

The solution can only access content from the site collection in which it was deployed.

Process the solution runs in

Unrestricted IIS worker process, or whichever process the solution is deployed into.

Separate worker process that has restricted permissions.

Code access security

The solution developer can set the code access security policy when packaging the solution.

Restricted.

Monitoring

Not monitored.

Monitored, and limited by quotas set by the farm administrator.

Load balancing

Varies, based on the kind of solution.

Configurable separately from non-sandboxed solutions.

Solution functionality

Unrestricted.

Restricted, as described in What sandboxed solutions cannot do, earlier in this article.

Although sandboxed solutions are restricted in what code they can and cannot use, and what data that they can and cannot access, you can create a special kind of operation that runs in a full trust process and can be called from a sandboxed solution. This is known as a full-trust proxy. For more information about full-trust proxies, see Sandboxed Solutions in Partnership with Full-Trust Proxies (https://go.microsoft.com/fwlink/p/?LinkId=220256), and Chapter 4: Sandboxed Solutions (https://go.microsoft.com/fwlink/p/?LinkID=219528).

Deploying sandboxed solutions

Any page in a SharePoint Server site can contain components that run in a sandbox in addition to components that run directly on the farm. The components that are deployed to the farm run in the Internet Information Services (IIS) worker process. The components that are deployed to the sandbox run in a sandboxed process.

The following list identifies components that you might deploy in a sandbox:

  • Web Parts

  • Event receivers

  • Feature receivers

  • Custom Microsoft SharePoint Designer workflow activities

  • Microsoft InfoPath business logic

The following steps describe the tasks that are required to prepare for and deploy sandboxed solutions:

  1. A farm administrator performs the following tasks one time only:

  2. A site collection administrator or a user who has the Full Control permission level at the root of the site collection uploads a solution to the site collection’s solution gallery. For information about how to upload a solution to a solution gallery, see Installing, Uninstalling, and Upgrading Sandboxed Solutions (https://go.microsoft.com/fwlink/p/?LinkID=220252).

  3. A site collection administrator activates the solution. If the solution does not contain an assembly, a user who has the Full Control permission level at the root of the site collection can also activate the solution. Validation tools run against the solution. If the solution fails validation, it is not activated. For information about how to validate and activate a sandboxed solution, see Installing, Uninstalling, and Upgrading Sandboxed Solutions (https://go.microsoft.com/fwlink/p/?LinkID=220252).

Site collection administrators can monitor the resources that sandboxed solutions use and can deactivate sandboxed solutions in the site collection. If, after a sandboxed solution is deployed, it starts to use too many resources or causes problems in the sandboxed environment, a farm administrator can block a sandboxed solution from running on the farm. Optionally, a farm administrator can also remove the requirement that a sandboxed solution be run in a sandbox by reinstalling the solution as a farm solution. If the requirement to run in a sandbox is removed, when the solution next runs in any site collection in the farm, it will no longer run in a sandboxed environment. For information about how to block a sandboxed solution, see Block or unblock a sandboxed solution (SharePoint Server 2010). For information about how to install a farm solution, see Deploy solution packages (SharePoint Server 2010).

Understanding the sandboxed solutions service

The sandboxed solutions service manages the execution of sandboxed solutions throughout a farm. Two processes run within the sandboxed solution service: the worker process and the proxy process. Each sandboxed solution runs inside an application domain in the worker process. The worker process manages the sandboxed solutions by throttling the resources accessed by each solution and by stopping processes that take too long to execute. Each worker process is paired with a proxy process that handles calls to the SharePoint object model. For a detailed explanation of how the sandboxed solutions service works, see "How Does the Sandbox Execution Model Work?" in Sandboxed Solutions (https://go.microsoft.com/fwlink/p/?LinkId=220257).

Understanding tiers

Based on the average number of resources per request that sandboxed solutions use, they can be grouped into tiers within the sandboxed solutions service. As shown in the following illustration, a tier in the sandboxed solutions service contains one or more worker processes in which sandboxed solutions run. Each sandboxed solution runs in its own application domain, which is reused when the solution is invoked.

Tiers in the sandboxed solutions service

By default, all sandboxed solutions run in the sandboxed solutions service in one tier, which contains a single worker process. By default, that worker process can run up to 10 application domains. A farm administrator can configure additional tiers and worker processes within the sandboxed solutions service to separate sandboxed solutions for performance, security, and reliability. If a sandboxed solution in a particular worker process uses too many resources, that solution causes all the sandboxed solutions within that worker process to stop. Because sandboxed solutions are monitored for how much resources they use, they are automatically separated into additional tiers based on their resource usage from the previous day. Therefore, creating additional worker processes and tiers helps isolate sandboxed solutions and protects well-behaved solutions from poorly behaved solutions by forcing the poorly behaved solutions to run in different tiers.

Farm administrators can set the following properties for each tier:

  • ResourceMaxValue   This property is a number that determines which sandboxed solutions will run in the tier. The default is 0, and it must be set to a larger value or the tier is never used.

  • MaximumWorkerProcesses   This property represents the maximum number of worker processes that can run in the tier. The default is 1. Setting this property to more than 1 will cause an additional worker process to be created on the server that is handling the request.

  • MaximumAppDomainsPerProcess   This property represents the maximum number of app domains that can run in a worker process in the tier. The default is 10.

  • MaximumConnectionsPerProcess   This property represents the maximum number of allowed connections from the sandboxed solutions service to a worker process in the tier. The default is 1.

  • PriorityPerProcess   This property represents the priority that the operating system has assigned to the worker processes in the tier.

For more information about tiers, see Using Execution Tiers to Protect Well-Behavied Sandboxed Solutions (https://go.microsoft.com/fwlink/p/?LinkId=220258) and Sandbox Tiers (https://go.microsoft.com/fwlink/p/?LinkId=217145). For information about how to configure tiers, see Configure sandboxed solutions service tiers (SharePoint Server 2010).

Understanding quotas and resource points

Sandboxed solutions are monitored for resource usage based on default quotas, which are monitored per site collection. When you set quotas for your site collections, you help prevent any sandboxed solution from using too many system resources. If one or more sandboxed solutions exceeds the quota that was set for the site collection, all sandboxed solutions in that site collection will automatically be stopped until the Solution Daily Resource Usage Update timer job runs, which typically occurs each night.

Quotas are managed through the SharePoint Central Administration Web site as a single number that controls the aggregate total of the resource points allowed per day for all sandboxed solutions in a site collection. Farm administrators can create a quota template that can be applied to any site collection in the farm. For information about how to plan quotas, see Plan quota management (SharePoint Server 2010). For information about how to create quota templates, see Create, edit, and delete quota templates (SharePoint Server 2010). For information about how to set the maximum resource quota for a specific site collection, see Change the storage limits for a site collection in Manage site collection storage limits (SharePoint Server 2010).

To restrict the resources that your sandboxed solutions consume, you define resource points. Resource points correspond to specific levels of resource usage that you can define for up to 15 resource measures (that is, system resources that you want to monitor), and are accrued for the whole site collection as sandboxed solutions run. When you view the resource measures inside a quota, you see the number of resources per point; these are the number of times that a particular resource can be used until a single resource point is accrued. For each resource measure, farm administrators can configure the following properties:

  • MinimumThreshold   The minimum level of resource usage that must be reached before it is aggregated into the running total for the site collection quota.

  • AbosoluteLimit   The maximum level of resource usage within a single request that can occur before the worker process is stopped.

  • ResourcesPerPoint   The quantity or level of a specific resource that equals one resource point and is counted toward the total quota for the site collection.

When the resource usage reaches the limit specified by the ResourcesPerPoint property, the site collection accrues a resource point. If the cumulative number of resource points exceeds the quota for a site collection, all sandboxed solutions in the site collection will be disabled for the rest of the day.

The default resource point limits will probably be satisfactory for most scenarios. However, you can adjust individual resource point limits to allow increased limits where they are suitable. For more information about how to adjust individual resource point limits, see Configure resource points for sandboxed solutions (SharePoint Server 2010).

Farm administrators can fine-tune the resource point distribution by using Windows PowerShell in a script to configure the individual resource point distribution within the sandboxed solution quota for a site collection. For a list of the individual resource measures and the minimum threshold, absolute limit, and resources per point for each resource measure, see Resource Usage Limits on Sandboxed Solutions in SharePoint 2010(https://go.microsoft.com/fwlink/p/?LinkId=217149). For information about how to configure the settings for specific resource measures, see Configure resource points for sandboxed solutions (SharePoint Server 2010).

Note

If you determine that a sandboxed solution is consistently misusing server resources, you can block that solution until the developer can correct the situation. For more information about how to block and unblock sandboxed solutions, see Block or unblock a sandboxed solution (SharePoint Server 2010).

Administering sandboxed solutions

As a farm administrator, you can do the following to administer sandboxed solutions and the sandboxed solutions service:

  • Enable the sandboxed solutions service on servers in the farm.

  • Change the load-balancing scheme for a farm.

  • Block or unblock a sandboxed solution on a farm.

  • Configure quotas for site collections on a farm.

  • Configure quota templates on a farm.

  • Use Windows PowerShell to do the following:

    • Display the quota settings for a site collection.

    • Display and configure resource points for specific resource measures.

    • Display and configure tiers for the sandboxed solutions service.

For more information about how to administer sandboxed solutions and the sandboxed solutions service, see Sandboxed solutions administration (SharePoint Server 2010).

Site collection administrators can do the following to administer sandboxed solutions:

See Also

Concepts

Sandboxed solutions planning (SharePoint Server 2010)
Sandboxed solutions administration (SharePoint Server 2010)

Other Resources

Sandboxed Solutions Resource Center
Sandboxed solutions architecture (https://go.microsoft.com/fwlink/p/?LinkId=177368)
Sandboxed Solutions in SharePoint 2010
Installing, Uninstalling, and Upgrading Sandboxed Solutions in SharePoint 2010
Resource Center: What's New in Microsoft SharePoint Server 2010