How to: Create and Register a Sandbox Proxy

Article
08/02/2010

Overview

Sandbox proxies are components that enable you to make full-trust functionality available to sandboxed solutions. This how-to topic describes how to create a sandbox proxy in the Microsoft® Visual Studio® 2010 development system.

For more information about sandbox proxies, see Execution Models in SharePoint 2010. For an example of sandbox proxies in action, see the Sandbox Proxy Reference Implementation.

Summary of Steps

This how-to topic includes the following steps:

Step 1: Create the SharePoint Project. In this step, you create a Visual Studio 2010 project that you can use to deploy and test your sandbox proxy.
Step 2: Create the Proxy Arguments Class. In this step, you create a serializable type that you can use to pass arguments from the sandbox to the sandbox proxy.
Step 3: Create the Proxy Operation Class. In this step, you create a class that contains the full-trust logic that you want to expose to sandboxed solutions.
Step 4: Register the Proxy Operation. In this step, you register your proxy operation with the user code service in order to make your operation available to sandboxed callers.
Step 5: Use the Proxy Operation from the Sandbox. In this step, you call your proxy operation from a sandboxed solution.

Step 1: Create the SharePoint Project

This procedure creates a Microsoft® SharePoint® project in Visual Studio 2010. You can use this project to build and deploy your sandbox proxy assembly.

To create a sandbox proxy project

Start Visual Studio 2010, and create a new Empty SharePoint Project, as shown in the following illustration. Name the project SimpleProxy.
In the SharePoint Customization Wizard, specify a valid local site for debugging, select Deploy as a farm solution, and then click Finish.
Open the AssemblyInfo class file and add the AllowPartiallyTrustedCallers attribute to the class, as shown here.
```
[assembly: AllowPartiallyTrustedCallers]
```

Step 2: Create the Proxy Arguments Class

This procedure creates a proxy arguments class. This is a serializable type that you can use to pass data from sandboxed code to the proxy operation class.

To create a proxy arguments class

Add a new class named SimpleProxyArgs to the project.
Add the following using statement to your class.
```
using Microsoft.SharePoint.UserCode;
```
Add the public access modifier to your class.
Add the SerializableAttribute to your class.
Modify your class to inherit from the SPProxyOperationArgs class. Your class should resemble the following code.
```
[serializable]
public class SimpleProxyArgs : SPProxyOperationArgs { }
```
Add public properties for any arguments that you want to pass from the sandbox to the proxy.
```
public string clientName { get; set; }
public int clientID {get; set; }
```
Note

Ensure that any properties you create use serializable types.
As a good practice, you might also want to add read-only properties for the type name and assembly name of your proxy operations class (which you will create in the next step). These are required when you register your proxy operation and when you invoke the operation from sandboxed code. By adding these properties to the proxy arguments class, you ensure that they are available from all locations when required.

(Optional) Add read-only properties for the type name and assembly name of your proxy operations class. The type name should be fully qualified and the assembly name should be the four-part strong name of your assembly.

public static string ProxyOperationTypeName
{
  get
  {
    return "SimpleProxy.SimpleProxyOps";
  }
}

public static string ProxyAssemblyName
{
  get
  {
    return "SimpleProxy, Version=1.0.0.0, Culture=neutral,   
            PublicKeyToken=2dfe43bced7458f6";
  }
}

Step 3: Create the Proxy Operations Class

This procedure describes how to create a proxy operations class that exposes full-trust logic to the sandbox environment.

To create a proxy operations class

Add a new class named SimpleProxyOps to the project.
Add the following using statement to your class.
```
using Microsoft.SharePoint.UserCode;
```
Add the public access modifier to your class.
Modify your class to inherit from the SPProxyOperation class. Your class should resemble the following code.
```
public class SimpleProxyOps : SPProxyOperation { }
```
Within the SimpleProxyOps class, override the Execute method. The method should accept an argument of type SPProxyOperationArgs and return an Object.
```
public override object Execute (SPProxyOperationArgs args)
{
}
```
Within the Execute method, cast the SPProxyOperationsArgs parameter to your proxy operations argument type, which in this case is SimpleProxyArgs.
```
var proxyArgs = args as SimpleProxyArgs;
```
Retrieve your arguments from the proxy arguments class, perform any full-trust logic, and return an object to the caller. In this example, assume that your class includes a helper method named GetAvailableCredit that calls a Windows Communication Foundation (WCF) service and returns a double value.
```
// Retrieve arguments from the proxy arguments class.
string clientName = proxyArgs.ClientName;
int clientID = proxyArgs.ClientID;

// Perform full-trust logic; for example, call a WCF service.
double availableCredit = GetAvailableCredit(clientName, clientID);

// Return an object to the caller. 
return availableCredit;
```
Note

Exception handling has been omitted for brevity. You should validate the incoming arguments and trap exceptions that occur within your logic.

Step 4: Register the Proxy Operation

This procedure describes how to create a feature receiver class to register your proxy operation with the user code service. This makes your proxy operation available to callers in the sandbox environment.

To register a proxy operation

Add a new feature named SimpleProxyFeature to the project. To do this, right-click Features in Solution Explorer, and then click Add Feature. To rename the feature, right-click the new feature name, and then click Rename.
In the Feature Designer window, in the Scope drop-down list box, click Farm.
Add an event receiver to the SimpleProxyFeature. To do this, right-click SimpleProxyFeature in Solution Explorer, and then click Add Event Receiver.

Add the following using statements to the SimpleProxyFeature.EventReceiver class.

using Microsoft.SharePoint.Administration;
using Microsoft.SharePoint.UserCode;

Uncomment the FeatureActivated method.
In the FeatureActivated method, add the following code to retrieve the local user code service.
```
SPUserCodeService userCodeService = SPUserCodeService.Local;
```

Add the following code to create a new proxy operation type, based on your proxy operation class.

var simpleOperation = new SPProxyOperationType(
                            SimpleProxyArgs.ProxyAssemblyName,
                            SimpleProxyArgs.ProxyOperationTypeName);

Add the following code to register your proxy operation type with the local user code service.
```
userCodeService.ProxyOperationTypes.Add(simpleOperation);
userCodeService.Update();
```
Press F5 to deploy your sandbox proxy to the test environment.

Step 5: Use the Proxy Operation from the Sandbox

This procedure describes how to call a registered proxy operation from sandboxed code.

To use a sandbox proxy

In your sandboxed solution, add a reference to the sandbox proxy assembly.

Create an instance of the proxy arguments class and set any property values.

var proxyArgs = new SimpleProxyArgs();
proxyArgs.ClientName = "Adventure Works";
proxyArgs.ClientID = 1;

Call the SPUtility.ExecuteRegisteredProxyOperation method, passing in the assembly name of the proxy operation, the type name of the proxy operations class, and the proxy arguments instance. In this case, the assembly name and the type name are provided by static properties of the proxy arguments class, as described in step 2.
```
var result = SPUtility.ExecuteRegisteredProxyOperation(
 SimpleProxyArgs.ProxyAssemblyName,
 SimpleProxyArgs.ProxyOperationTypeName,
 proxyArgs);
```
Cast the returned value to the expected return type of the proxy operation.
```
double availableCredit = (double) result;
```