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:
- The definitive guide (back to table of contents).
- The basics of a sandbox solution
- Sandbox solution architecture and restrictions <-- you are here
- Sandbox solution monitoring, management and deployment
- Sandbox solution validations
- 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:
- All of Microsoft.SharePoint, except
- SPSite constructor
- SPWorkItem and SPWorkItemCollection
- SPUserSolution and SPUserSolutionCollection
- Microsoft.SharePoint.Utilities, except
- Microsoft.SharePoint.WebPartPages, except
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:
- AspNetHostingPermission.Level = Minimal
There are two other important points to note in this out of the box CAS Policy
- While your code is restricted to the CAS policy permissions defined above, it allows the SharePoint framework code full trust.
- If your custom code needs to break out of this sandbox's boundaries, you can always write a full-trust proxy.