Sandboxed Solutions Architecture in SharePoint 2010

This topic describes the architecture of sandboxed solution system in Microsoft SharePoint.

Applies to: SharePoint Foundation 2010

Available in SharePoint Online

Included are descriptions of the packaging system, the processing model, the split page rendering system, the resource usage restrictions, the code execution and access restrictions, and the solution validation framework. Details on all these subjects can be found in other topics in the Sandboxed Solutions in SharePoint 2010 node of the SDK.

Sandboxed Solutions Architecture Overview

A sandboxed solution, in contrast to a farm solution, enables site collection administrators to install custom solutions in Microsoft SharePoint Foundation without the involvement of a higher level administrator. However, this freedom requires that sandboxed solutions be limited in what they can deploy, what code they can execute, and what resources they can access.

Packaging and Installation System for Sandboxed Solutions

Like a farm solution, a sandboxed solution is packaged for installation in a solution package (.wsp) file. However, instead of being deployed to the farm's solution store, sandboxed solutions are deployed to a specific site collection's Solution Gallery by a site collection administrator. The gallery is a special SharePoint list, so it is in the content database. Solution deployment to the gallery is done through the Site Actions user interface (UI) of the site collection or with SharePoint Management Shell. For more information about the installation process of sandboxed solutions, see Installing, Uninstalling, and Upgrading Sandboxed Solutions in SharePoint 2010.

There are limits on what kinds of elements can be in sandboxed solutions and where they can be deployed. Most importantly, nothing can be deployed to the file system of the servers from a sandboxed solution. This restriction has several implications:

• Application pages, user controls (.ascx files), and localization resource (.resx) files cannot be deployed with a sandboxed solution. (However, there are other ways to localize sandboxed solutions. For more information, see Localization of Sandboxed Solutions in SharePoint 2010.)

• Images, script files, and Features in sandboxed solutions are deployed to the content database, not to the file system of the front-end servers.

• Site definitions cannot be deployed in sandboxed solutions. (But web templates, which are functionally equivalent, can be. For more information, see How to: Deploy a Web Template in a Sandboxed Solution.

• Assemblies in sandboxed solutions are also deployed to the content database; although when in use, they are temporarily cached to the file system of the server handling the request. For more information, see Where are Assemblies in Sandboxed Solutions Deployed?.

For a fuller account of what can be deployed in a sandboxed solution, see What Can Be Implemented in Sandboxed Solutions in SharePoint 2010.

A sandboxed solution is also not allowed to access anything outside the site collection to which it is deployed. An implication of this is that Features deployed in sandboxed solutions can only be scoped to a site collection or website.

Process Model for Sandboxed Solutions

SharePoint is an ASP.NET application, and like any ASP.NET application, when an HTTP request is received by a front-end web server, a special driver, HTTP.SYS, detects the request and routes it to the application pool that is handling requests for the targeted Internet Information Services (IIS) website, and thus, the targeted SharePoint web application. Every application pool has an IIS worker process (w3wp.exe) in which the request pipeline for each request is executed. (For more information about the IIS 7.0 worker processes and application pools, see Introduction to IIS 7 Architecture.) On a SharePoint server, the IIS worker process runs in the application pool account, and thus the process has read and write permissions to SharePoint resources. On a multiserver farm, the application pool account is normally a domain user. This should not be the same account as the farm account.

Farm solutions run in the IIS worker process just like any ASP.NET application. However, sandboxed solutions run in a specially restricted execution environment. This is necessary to prevent rogue or poorly performing code from slowing or crashing the application pool. Accordingly, SharePoint imposes restrictions on what code in a sandboxed solution can do. As a crucial part of the implementation of this system, sandboxed solutions must run in a special sandboxed worker process (SPUCWorkerProcess.exe).

When a request tries to access a sandboxed solution, a SharePoint execution manager that is running in the IIS worker process finds a sandbox worker process (or starts one, if none is running) in which the code of the sandboxed solution will run. In principal, this sandboxed worker process can be started on any server in the farm that is running the SharePoint Foundation Sandboxed Code Service (SPUCHostService.exe). In the Windows Services dialog box, this is referred to as the SharePoint 2010 User Code Host service.

The server that is running the SharePoint Foundation Sandboxed Code Service can be, but does not have to be, the front-end web server on which the IIS worker process is running. Which server is used is configurable in the Central Administration application: Administrators can choose to have each sandboxed process run in "local mode", which means that each request for a sandboxed solution is processed on the same front-end web server on which the IIS worker process is running; or they can have the execution manager launch each sandboxed process in "remote mode", sometimes called "affinity mode." In the latter mode, the execution manager will look for a server that is running the SharePoint Foundation Sandboxed Code Service and which already has created an application domain inside its SPUCWorkerProcess.exe process for the very same sandboxed solution. (This would be the case if that same sandboxed solution was requested before, possibly by another user on another site collection.) If there is a matching application domain, the request is sent to that same application domain for handling. If none of the servers that are running the SharePoint Foundation Sandboxed Code Service already has an application domain for the sandboxed solution, the execution manager assigns the request to the least busy of those servers. The server then creates the needed application domain and processes the request for the sandboxed solution. Regardless of whether local or affinity mode is being used, the application domain in the sandboxed worker process stays alive after the request is processed and is reused if there is another request for the same sandboxed solution.

All sandboxed solutions that are being handled by a given server run in the same sandbox worker process. Each sandboxed solution gets its own application domain within the common process. The SharePoint Foundation Sandboxed Code Service runs in the farm account.

Code Execution and Resource Access in the Sandboxed Worker Process

All code that runs in this sandbox worker process is subject to execution and access constraints. There are two systems of constraints: one applies only to calls that code in sandboxed solutions makes to the main SharePoint Foundation assembly, Microsoft.SharePoint.dll. The other applies to all other calls, including calls to all other SharePoint assemblies and to .NET Framework assemblies. In this topic, the first system is called Server-side Object Model Constraints and the second system is called General Constraints. (There are also some miscellaneous constraints resulting from the split page rendering system used in sandboxed solutions. For more information, see the section Split Page Rendering System later in this topic.)

The General Constraints are imposed by two mechanisms:

1. A highly restrictive code access security (CAS) policy significantly limits what code in the sandboxed worker process can do. This policy is defined in the wss_usercode.config file in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\CONFIG and is referenced in the web.config file in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\UserCode. (We do not support changing this file.) Among the restrictions imposed by the CAS policy are the following:

   • Code in the sandbox cannot call unmanaged code.

   • Code in the sandbox cannot call the Microsoft .NET Framework 3.5 reflection APIs.

   • Code in the sandbox can call only the .NET Framework 3.5 assemblies that have the AllowPartiallyTrustedCallersAttribute attribute. This blocks access to about two-thirds of the .NET Framework 3.5 APIs, including, System.Printing, for example. Some SharePoint assemblies also do not have the attribute. For lists of .NET Framework assemblies that do, and do not, have this attribute, see Available and Unavailable .NET Assemblies from Sandboxed Solutions in SharePoint 2010. For lists of SharePoint assemblies that do, and do not, have this attribute, see Available and Unavailable SharePoint Assemblies from Sandboxed Solutions in SharePoint 2010.

   Note

   The CAS policy makes an exception for strong-named Microsoft Office assemblies. These are granted full trust.

   For more information about this CAS policy and its implications, see Restrictions on Sandboxed Solutions in SharePoint 2010.

2. Secondly, the sandboxed worker process has a low-privileged security token.

   • The token denies the process the right to read or write to the file system.

   • The token denies the process the right to call to the network. So, only resources that are available on the server that is running the sandboxed worker process may be accessed. An external database, for example, cannot be accessed.

   • The token denies the process the right to write to the registry.

   • The token denies the right to call to any assembly that is not in the global assembly cache, even if it has the AllowPartiallyTrustedCallersAttribute attribute and would otherwise be eligible to be called from the sandboxed worker process.

Be aware that these restrictions do not apply to calls made to the APIs in the Microsoft.SharePoint.dll assembly. So, for example, a call to GetLocalizedString can read from resource files in the file system, and calls to SPList objects can read and write to the content database regardless of which server it is on. (However, a file cannot be deployed to disk in sandboxed solution, so the .resx would have to be separately installed as a farm solution.)

The main restriction in the Server-side Object Model Constraints system is that only a subset of the APIs in the Microsoft.SharePoint.dll assembly can be called from a sandboxed solution. A call to any forbidden API results in an exception (which is caught and reported to the user as an error).

The following are some of the restrictions on the SharePoint object model that can be accessed:

• The SPWebApplication class is not available. Among other things, this means that a sandboxed solution cannot access anything outside its hosting site collection.

• Almost all classes in the Microsoft.SharePoint.WebControls namespace are not available, which means that you are mainly restricted to ASP.NET controls in sandboxed solutions.

For a complete list of Microsoft.SharePoint.dll classes that are available to sandboxed solutions, see Microsoft.SharePoint.dll APIs That Are Available from Sandboxed Solutions.

The implementation of this restriction is done by a pair of specially restricted versions of the Microsoft.SharePoint.dll assembly, called shim assemblies, which are located in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\UserCode\assemblies. These versions differ from the standard Microsoft.SharePoint.dll assembly primarily in that they contain only a subset of the classes and members in the standard version.

One of the two shim assemblies is loaded by the sandboxed worker process. The other is loaded in a special proxy process (SPUCWorkerProcessProxy.exe) that runs in full trust and that is also managed by the SharePoint Foundation Sandboxed Code Service. The standard Microsoft.SharePoint.dll assembly is also loaded in this proxy process.

The main job of the two shim assemblies is to filter out forbidden SharePoint classes and members. When a call is made to the Microsoft.SharePoint.dll from any code in the sandboxed worker process, it is redirected to the shim version of the assembly. If the API that is being called is not in the shim assembly, an exception is thrown (which is caught and reported as an error to the user).

When the sandboxed solution calls an approved API that is contained in the shim assemblies, the first shim assembly passes it to the second in the full-trust proxy process, which in turn, passes it to the standard the Microsoft.SharePoint.dll. Any returned results are passed back to the original calling code. This cross-process interaction is possible by means of .NET Remoting. A sandboxed worker process and a full-trust proxy process are always launched together and paired with each other. If either crashes, the other is stopped too.

There is a secondary restriction in the Server-side Object Model Constraints system that is also enforced by the shim assemblies. Some SharePoint APIs can be called from sandboxed solutions, but only with special restrictions on the parameters passed to them. It is the shim assemblies that enforce these input restrictions and ensure that an exception is thrown when there is a violation. The only case of this in SharePoint Foundation 2010 are the SPSite(String) and SPSite(Guid) constructors. These are available to sandboxed solutions, but only URLs or GUIDs that refer to the site collection in which the sandboxed solution is installed can be passed to them.

Figure 1 shows how an HTTP request is handled when it accesses a sandboxed solution.

Figure 1. Request processing model for sandboxed solutions

The SPUCHostService.exe, SPUCWorkerProcess.exe, and SPUCWorkerProcessProxy.exe files are located at %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\UserCode.

Resource Usage Restrictions on Sandboxed Solutions

Sandboxed solutions are also subject to three kinds of resource usage restrictions that can be categorized by (1) the sort of entity to which the restriction applies, and (2) the sort of entity on which the penalty for exceeding the restriction is imposed.

• Per Request with the Request Penalized: There is a hard limit to how long a sandboxed solution can take to be completed. This is 30 seconds by default. If a sandboxed solution exceeds the limit, the request (but not the sandboxed worker process) is terminated. (This limit is configurable, but only through custom code against the object model. The relevant parts of the object model are not available to sandboxed solutions, so no sandboxed solution can change the limit.)

• Per Request with the Process Penalized: There is a set of 15 resource additional resource limits that apply to requests. If a request exceeds one of them, the process (and all the sandboxed solutions running in it) is terminated.

• Per Day/Per Site Collection with the Site Collection Penalized: Each site collection is subject to a configurable maximum of daily "resource points." These points accumulate based on an algorithm that considers the use of resources in the 15 resource categories by the sandboxed solutions installed in the site collection. When a site collection exceeds its maximum allowed points, all sandboxed solutions in the site collection are terminated, and no more can run for the rest of the day.

For detailed information about the resource restrictions imposed on sandbox restrictions, see Resource Usage Limits on Sandboxed Solutions in SharePoint 2010.

Split Page Rendering System

When a client computer requests a SharePoint page that includes a component from a sandboxed solution, such as a Web Part that is deployed in a sandboxed solution, SharePoint renders more than one page object. One is rendered in the Microsoft ASP.NET worker process (w3wp.exe), and the others are rendered in the sandboxed worker process. All non-sandboxed components are rendered on the page in the ASP.NET worker process, while the first sandboxed component is rendered on a page object in the sandboxed worker process. When the page in the sandboxed worker process is fully rendered, it is merged into the page object in the ASP.NET process. If there is more than one sandboxed component on the page that the user requested, each of them is rendered separately on their own page object in the sandboxed worker process. Each such page object, in turn, is merged into the page object in the ASP.NET process.

As a side effect, this system imposes some additional restrictions on what can be done in a sandboxed solution. For more information about these restrictions, see Restrictions on Sandboxed Solutions in SharePoint 2010.

Escaping the Sandbox Restrictions

There are two major ways that a sandboxed solution can escape the usual restrictions. By far the most important is to use client-side code to access the resources that are not available from server-side code in a sandboxed solution. For example, a sandboxed solution could include a custom site page with JavaScript that makes calls to the SharePoint JavaScript client object model. Also, a sandboxed solution could include a Web Part that hosts a Microsoft Silverlight application. The latter application can make calls to the SharePoint Silverlight client object model. None of the restrictions on sandboxed solutions apply to client-side code. There are no code execution restrictions, no resource access restrictions, and no resource usage restrictions. For more information, see How to: Extend the Power of a Sandboxed Solution with the SharePoint Client Object Model.

The sandboxed solutions architecture also enables a technique by which a sandboxed solution can call custom operations that run in full trust. The technique requires that a farm solution be developed that includes one or more classes that derive from SPProxyOperation. Each of these defines an operation that will run in full trust and can be called from sandboxed solutions by means of the ExecuteRegisteredProxyOperation method. Specifically, these full trust proxy operations execute in the same proxy process (SPUCWorkerProcessProxy.exe) in which the standard Microsoft.SharePoint.dll assembly runs. The proxy operations can return data to the sandboxed solution.

Figure 2 shows how a request that accesses a sandboxed solution is processed when the sandboxed solution makes a call to a full trust proxy.

Figure 2. Request processing model when a sandboxed solution calls a full-trust proxy

The preceding description might give the impression that, with this technique, a farm and a sandboxed solution are always developed together by the same development team. In fact, the farm solution that contains the proxy operation classes may be developed specifically to provide certain operations to any and all sandboxed solutions that need those services, including sandboxed solutions that are developed by other teams. For example, because a sandboxed solution cannot write to the SharePoint ULS logs, a farm solution that opened proxy logging operations to sandboxed solutions would be very useful.

For more information about developing and calling full trust proxy operations, see Sandboxed Solutions in Partnership with Full-Trust Proxies in SharePoint 2010 and other topics in the same node.

Solution Validation Framework

SharePoint provides a solution validator framework which can be used to develop custom solution validators such as, for example, a validator that verifies whether a solution is signed with a specific certificate. The validators in a site collection run when a sandboxed solution is activated. The activation of any invalid solution is blocked. If a validator is updated or a new validator is added, each activated solution is rechecked by the validators the next time it is executed. Invalid solutions are deactivated. For more information about developing custom validators, see Solution Validation System.

See Also

Concepts

Solutions Overview

Restrictions on Sandboxed Solutions 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