SharePoint 2010 Sandbox solutions: Architecture and Restrictions

Posted on 12/7/2009 @ 4:32 PM in #SharePoint by | Feedback | 8027 views

In this blog post, I will dissect every aspect of sandbox solutions as they apply to SharePoint 2010. 
The below will turn into links as newer blog posts are published.

Some of the content below uses excerpts from my book on SharePoint 2010.


Table of Contents:

    1. The definitive guide (back to table of contents).
    2. The basics of a sandbox solution
    3. Sandbox solution architecture and restrictions <-- you are here
    4. Sandbox solution monitoring, management and deployment
    5. Sandbox solution validations
    6. Sandbox solutions full trust proxies



It is clear that Sandbox solutions run under certain restrictions! An example of such a restriction - being able to make changes to the file system, even during deployment. This is why a Visual WebPart which involves the deployment of an ASCX is not allowed in a sandbox solution. But it is important to understand the architecture of how sandbox solutions work before we can talk about the specific restrictions.

The word "sandbox" in computers is generally used to refer to a safe area where you can play, without damaging the outside hosting environment. The sandbox in SharePoint is implemented as a separate process where your sandbox solution code will run. In fact, there are three processes.

The User Code Service

SPUCHostService.exe, also known as the User Code Service. This service runs on each server on the farm that we are going to allow to work in the sandbox. Thus the infrastructure ogres can choose to run this service on all, or only a certain subset of the servers in the farm. This is an important consideration, because this constitutes an important part around the administration of sandbox solution infrastructure, namely the load balancing aspects.There are two approaches to load balancing sandbox solutions on your SharePoint Farm.

You could turn on the User Code Service on every front end in the farm. In that scenario, the solution would run on the web front end on which the request was made. The code is executed on the WFE. This is very low administration overhead, but has lower scalability.

Alternatively, you can choose to spin up the user code service on only certain web front ends, use only certain web front ends to run sandbox solutions. This allows you to offload the execution load on different servers.

In order to choose on or the other mechanism, the infrastructure administrator needs to peform two steps in central adminstration.

a) Start the user code service on the relevant web front ends. This can be done by accessing central administration\system settings\manage services on server. The specific service is shown as below:

b) Go to Central Administration\System Settings\Manage User Solutions and specify the desired load balancing behavior as indicated in the figure below.

The Sandbox Worker Process

The sandbox worker process is where your actual code runs! This is in contrast to having the code run inside of w3wp.exe. This is why you don't have to restart the application pool every time your redeploy an sandbox solution. If you wish to debug a sandbox solution, and for any reason why F5 debugging is not working, you will need to attach your visual studio debugger to the SPUCWorkerprocess.exe process. It is important to note however that the sandbox solution management infrastructure of SharePoint 2010 can choose to destroy the SPUCWorkerProcess.exe anytime your code tries doing something naughty, such as an infinite resource crunching loop! So, during debugging, don't be too surprised if SharePoint kills your process without asking first.

Sandbox Worker Process Proxy

Finally there is the sandbox worker process proxy, or the SPUCWorkerProcessProxy.exe, which is built on the new services infrastructure in SharePoint. Inside the SPUCWorkerProcess.exe sandbox, you have the ability to run only a subset of the Microsoft.SharePoint namespace. What does that subset include? In sandbox solutions, you are free to use the following:

  1. All of Microsoft.SharePoint, except
    1. SPSite constructor
    2. SPSecurity
    3. SPWorkItem and SPWorkItemCollection
    4. SPAlertCollection.Add
    5. SPAlertTemplateCollection.Add
    6. SPUserSolution and SPUserSolutionCollection
    7. SPTransformUtilities
  2. Microsoft.SharePoint.Navigation
  3. Microsoft.SharePoint.Utilities, except
    1. SPUtility.SendEmail
    2. SPUtility.GetNTFullNameandEmailFromLogin
  4. Microsoft.SharePoint.Workflow
  5. Microsoft.SharePoint.WebPartPages, except
    1. SPWebPartManager
    2. SPWebPartConnection
    3. WebPartZone
    4. WebPartPage
    5. ToolPane
    6. ToolPart

So as you can see, as long as you can fit your solution within the above constraints, you can deliver very compelling functionality. It is important to note however that when you create a new Visual Studio SharePoint project, and choose to make the solution a sandbox solution, visual studio will trim it's intellisense to reflect the restricted API. However, if you choose to hand type in one of the restricted APIs above, and compile and deploy your project, it will still compile and deploy! It just won't execute. This is because, your sandbox solution code is validated against the restricted API as indicated above, but it is compiled against the full API.

So here is a little trick! If you want to make sure that you aren't using any of the restricted APIs before you deploy your solution, manually reference your project against [SharePoint Root]\UserCode\assemblies\Microsoft.SharePoint.dll. If your code compiles, then you're pretty safe! Of course, NEVER deploy code with this user code Microsoft.SharePoint dll references, instead reference the Microsoft.SharePoint.dll in the [SharePoint Root]\ISAPI folder.

While you are in the [SharePoint Root]\UserCode folder, you will also note a web.config there. If you open that web.config, you will see a trust level entry as shown below:

<trustLevel name="WSS_Sandbox" policyFile="..\config\wss_usercode.config" />

Thus as you can see, the sandboxed solutions are also restricted by an out of the box CAS policy. Thus the sandbox is non-negotiable! You shouldn't edit this file to define the boundaries of your own sandbox, you should stick with the boundaries that Microsoft defined for you! Specifically, the CAS policy for sandbox solutions grants you the following policy permissions:

  1. SharePointPermission.ObjectModel
  2. SecurityPermission.Execution
  3. AspNetHostingPermission.Level = Minimal

There are two other important points to note in this out of the box CAS Policy

  1. While your code is restricted to the CAS policy permissions defined above, it allows the SharePoint framework code full trust.
  2. If your custom code needs to break out of this sandbox's boundaries, you can always write a full-trust proxy.

Sound off but keep it civil:

Older comments..

On 1/9/2010 7:12:57 AM mswin said ..

I want to create a webpart, which will create documentLibrary/document sets programatically.Can this be deployed as Sandboxed solution? Creation of Document Libraries and Docsets is supported in Sandboxed solution or not?


On 2/10/2010 8:02:40 AM Sonja said ..
You can't wrap your code for use in Developer Dashboard either. SPMonitoredScope is part of SharePoint.Utilities namespace.

On 3/11/2010 5:36:59 AM Ben said ..
Hello !

This is a nice article, but I would like to ask you a question:

Inside a Sandboxed Solution, I am trying to add an Application Page into a Module to have it deployed under the "SitePages" list of a site; my problem is that even is the Project option "Include Assemby In Package" is set to true, code is never deployed. Do you think this is feasible, even if I was not really possible in 2007?


On 6/24/2010 3:36:57 AM Andrew Woodward said ..

A cool Power Tool for SharePoint 2010 has been released that will automatically validate your solution against the sandbox.


On 8/5/2010 2:07:27 AM Vikram said ..

I am designing application, which reads the .xml file located on document library of local SharePoint server on which sandbox solution is going to deploy, do some processing on that xml file and so some output e.g on button click.

Is it possible to access .xml file? if yes can you tell me the way to do that.

Thanks in advanced :)


On 2/13/2012 3:26:56 PM Venky said ..
Please help me here with F5 in simple Farm dev environment: I have purchased your book on SP2010 long back and never had issues with F5 debugging in VS 2010:

I have two server farm 1. App server Windows Server 2008 R2 + VS 2010 professional

+ SQL sevrer windows server 2008 SP2

In Task manager, I only see SPUCHostService.exe and SPUCWorkerProcessProxy.exe at times and never see SPUCWorkerProcess.exe appears in processes.

1) Activated/Deactivated user solution using sitecollection admin credentials

2) OOB sandbox code Deployment went successfully

3) When I run from any client machines and try to add sandbox webpart, I get "Sandboxed code execution request failed."

4) If I run with F5 Unable to attach. Process 'SPUCWORKERPROCESS.exe' is not running on 'machinename'.

I have followed all the blogs and applied given workaround and I am not getting any trusted advise on this topic.

I have created another fresh environment

Configuration database version: 14.0.4762.1000

I appreciate any help you would give us.