How to: Create a Sandboxed Workflow Action

Article
08/02/2010

Overview

Microsoft® SharePoint® 2010 enables you to create and deploy custom workflow actions as sandboxed solutions. You can then consume these workflow actions within declarative workflows in SharePoint Designer. This how-to topic describes how to create and deploy a sandboxed workflow action.

For a practical example of the deployment of a sandboxed workflow action, see the workflow activities 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 Workflow Action Class. In this step, you create a class that contains your sandboxed logic.
Step 3: Create the Workflow Action Definition. In this step, you create a feature manifest file. This contains the markup that references your class and defines your workflow action.

Step 1: Create the SharePoint Project

This procedure creates a SharePoint project in the Microsoft Visual Studio® 2010 development system. You can use this project to build and deploy your sandboxed workflow action.

To create a project

Start Visual Studio 2010 and create a new Empty SharePoint Project, as shown in the following illustration. Name the project SimpleAction.
In the SharePoint Customization Wizard, specify a valid local site for debugging, select Deploy as a sandboxed solution, and then click Finish.

Step 2: Create the Workflow Action

This procedure creates a sandboxed workflow action class. It contains a method that defines the workflow action logic, and it shows you how to return values to the workflow.

To create a sandboxed workflow action class

Add a new class named SandboxActivityLog to the project.

Add the following using statements to your class.

using System.Collections;
using Microsoft.SharePoint;
using Microsoft.SharePoint.UserCode;
using Microsoft.SharePoint.Workflow;

Add the public access modifier to your class.
Within the class, add a public method that accepts an argument of type SPUserCodeWorkflowContext and returns a value of type Hashtable. This method defines the workflow action.
```
public class SandboxActivityLog
{
  public Hashtable Log(SPUserCodeWorkflowContext context) { }
}
```

Within your method, implement your action logic. You can return values from your method by adding key/value pairs to a Hashtable object.

public Hashtable Log(SPUserCodeWorkflowContext context)
{
  Hashtable results = new Hashtable();
  results["Except"] = string.Empty;

  try
  {
    using (SPSite site = new SPSite(context.CurrentWebUrl))
    {
      using (SPWeb web = site.OpenWeb())
      {
        SPWorkflow.CreateHistoryEvent(web, context.WorkflowInstanceId, 0,
            web.CurrentUser, TimeSpan.Zero, "Information",
      "Event from sandboxed activity", string.Empty);
      }
    }
  }  
  catch (Exception ex)
  {
    results["Except"] = ex.ToString();
  }

  results["Status"] = "Success";
  return (results);
}

Note

Notice the use of the Except key to return an exception to the workflow.

Step 3: Create the Workflow Action Definition

This procedure creates a workflow action definition in a feature manifest file. This markup tells the SharePoint workflow engine how to interact with your workflow action.

To create an action definition for a sandboxed workflow action

In Solution Explorer, right-click the project node, point to Add, and then click New Item.
In the Add New Item dialog box, in the Installed Templates pane, expand SharePoint, and then click 2010.
Click Empty Element, type a name for the element in the Name text box, and then click Add. This example uses the name LogDefinition for the element.
Expand the LogDefinition node and open the feature manifest file (Elements.xml).
Add a WorkflowActions element to the feature manifest.

Within the WorkflowActions element, add an Action element. This should do the following:

Provide a friendly name for your workflow action.
Specify that the action runs in the sandbox.
Identify the assembly name and class name of your action.
Identify the method that provides the action's functionality.

<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <WorkflowActions>
    <Action Name="Log Testing" 
            SandboxedFunction="true" 
            Assembly="$SharePoint.Project.AssemblyFullName$" 
            ClassName="SimpleAction.SandboxActivityLog" 
            FunctionName="Log" 
            AppliesTo="all" 
            Category="patterns and practices sandbox">
    </Action>    
  </WorkflowActions>
</Elements>

Within the Action element, add a RuleDesigner element. This specifies the sentence that your workflow action will display in SharePoint Designer. It also binds the Except argument returns by your action to a variable named Exception.
```
<RuleDesigner Sentence="Log Activity (Exception to %1)">
  <FieldBind Field="Except" 
             Text="Exception" Id="1" 
             DesignerType="ParameterNames" />
</RuleDesigner>
```

Within the Action element, add a Parameters element. This should define the arguments passed to your workflow action method and the types returned by your workflow action method.

<Parameters>
  <Parameter Name="__Context" 
             Type="Microsoft.SharePoint.WorkflowActions.WorkflowContext, 
                   Microsoft.SharePoint.WorkflowActions" 
                   Direction="In" 
                   DesignerType="Hide"/>
  <Parameter Name="Except" 
             Type="System.String, mscorlib" 
             Direction="Out" 
             DesignerType="ParameterNames" 
             Description="Exception encountered"/>
</Parameters>