Creating SharePoint 2010 Workflows: Starting with Visual Studio 2010

The most recent versions of SharePoint -- Microsoft SharePoint 2010 and SharePoint Foundation 2010 -- are based on the workflow and concepts of the .NET Framework 3.5. In my previous article, "Workflows in SharePoint 2010," I provided an overview of these workflows.

Now, in this series of articles, I will provide a step-by-step approach to building workflows in SharePoint 2010, using Microsoft Visual Studio (VS) 2010, SharePoint Designer (SPD) 2010, and Visio 2010.

In this first article, I will cover the basics: creating a VS 2010 project and SharePoint 2010 workflow, deploying the workflow, and understanding some basic concepts. The code we will create in this article will be upgraded in future articles. (To download the beginning code and site template that we'll use in this article, click the  hotlink at the beginning of the article.)

You'll also need a virtual machine (VM) for this tutorial. I use the free 2010 Information Worker Demonstration and Evaluation VM, which you can download from Microsoft; if you prefer, you can get an instance of the same VM running in the cloud from www.cloudshare.com.

The Scenario: Submitting an Expense Report

The workflow that we are going to create is an application that allows users to submit expense reports. As soon as an expense report is submitted, a workflow will be activated and will

Before starting this tutorial, you need to create a site (based on the template that you can download from the  hotlink at the beginning of this article) that has the following lists:

Figure 1: Expense Reports list structure

Figure 2: Managers list structure 

Fill the Managers list with the accounts that Figure 3 shows (I've used accounts that Microsoft provides in its VM, but you can use your own accounts.) Make sure that the users in this list are at least contributors in the site (a setting that is not provided in the site template).

Figure 3: List of managers and their direct reports 

Creating the Workflow

Before creating the workflow, make sure that VS 2010 and SharePoint 2010 are running on the same computer. Start VS 2010 and create a new SharePoint 2010 project that is based on the Empty SharePoint Project template, as Figure 4 shows. Name the project Litware.ExpenseReport.

Figure 4: Creating a SharePoint project in VS 2010 

In the SharePoint Customization Wizard, when prompted to provide your web site URL for debugging, enter the URL and select the Deploy as a farm solution option, as Figure 5 shows. Workflows that are generated with VS cannot run in the sandbox.

Figure 5: Deploying the VS project 

Add a new SharePoint item, based on the Sequential Workflow template, to your project, as Figure 6 shows. Name the item ExpenseReportWorkflow.

Figure 6: Adding a sequential workflow project item 

Because workflows communicate with users by assigning tasks (I'll provide more details about this topic in another article), we usually need a task list (although it isn't mandatory). For this tutorial, the site template creates the task list. If you don't provide any task list, the SharePoint Customization Wizard generates an error message that begins "The SharePoint Site at xxxxx is missing a target, task, or history list..." (as Figure 7 shows). Don't worry too much about this for the moment, but keep it in mind.

Figure 7: Missing-list error message 

In the next window, you need to specify whether you want your workflow to be associated with a SharePoint list item. If so, select the List Workflow option; if not, select the Site Workflow option, which is new in SharePoint 2010.

Because our expense report will be stored in the Expense Reports SharePoint list, select List Workflow, as Figure 8 shows. Click Next.

In the next window, select the list that you want your workflow to be associated with: in our case, Expense Reports, as Figure 9 shows. (Note that the Workflow History list is a hidden list that contains key information about each workflow event, including date, status, participant, and description. The wizard creates this list for you. By default, the workflow history is visible for only 60 days after a workflow completes or is cancelled. I'll provide more information about the Workflow Auto Cleanup job in a future article.)

Click Next.

Figure 8: Choosing list or site workflows

Figure 9: Choosing lists for debugging 

The next window allows you to specify how you want the workflow to start.

When you associate a workflow to a list (which you can do manually, as I will illustrate later, or by using the SharePoint Customization Wizard), you can specify whether you want the workflow to start manually (i.e., the user will manually start the workflow) or automatically when a new list item is created or when an existing item is changed. (You can change these parameters later if you want.)

Let's keep the options that Figure 10 shows. Click Finish.

Figure 10: Selecting workflow starting options 

The workflow now shows up in the Workflow Designer, which Figure 11 shows. The first activity (or step) of a VS SharePoint workflow must be an onWorkflowActivated activity.

Figure 11: First workflow in the Workflow Designer 

Open the Solution Explorer, which Figure 12 shows. You will see that a new SharePoint project item (of type Workflow) has been generated. The associated .NET code can be found in the ExpenseReportWorkflow.cs file, which is also a .NET class; we usually call this class a workflow template.

Figure 12: Solution Explorer showing workflow generated code 

Building and Deploying

Go to the Build menu and select Deploy Solution. This generated code is called a workflow template; several instances of the same workflow template can be associated to the same list or to a different list in the site collection.

Go to your site, click the Expense Reports list, go to the list settings, and click the Workflow Settings button on the SharePoint Ribbon, as Figure 13 shows.

Figure 13: Workflow button  

The Workflow Settings window appears. This window shows a list of available workflow templates. Our workflow template is available because it is encapsulated in a SharePoint feature with a scope of Site (a site collection); more about this later.

In this window, you can associate your workflow template with the current list.

We already have one association (performed by VS 2010), named Litware, as Figure 14 shows.ExpenseReports-ExpenseReportWorkflow, but you can create other workflow associations by clicking the Add a workflow hyperlink. (You can display the list of available workflow templates by clicking the drop-down arrow.)

Click the Litware.ExpenseReports-ExpenseReportWorkflow association link to view the workflow association settings, which Figure 15 shows. Note that the option is selected to start the workflow when a new item is created. Click OK.

Figure 14: Workflow association

Figure 15: Workflow association settings 

Go to the Expense Report list and add a new item, as Figure 16 shows. Save this item. Because the workflow is configured to start when a new item is created, saving the item will cause a workflow instance to be created from our workflow template.

Figure 16: Adding a new list item 

Indeed, if you go back to the list view, which Figure 17 shows, you will notice a new column that has the workflow association as a name. If you click the Completed hyperlink, you will visualize the workflow status, history, and tasks in the Workflow Information window, which Figure 18 shows.

Figure 17: Workflow Association column

Figure 18: Workflow Information window

Using Workflow Activities

A workflow is a set of steps; each step is an activity. Activities are .NET classes. We can reuse existing activities or create custom activities, as I will illustrate later.

The Workflow Foundation (WF) infrastructure is a set of assemblies that can be visualized in the References folder of our VS 2010 project (see Figure 19).

As part of the .NET Framework 3.5, WF provides several interesting activities that can be used in SharePoint. (Not all WF activities can be used in SharePoint, however.)

These activities are provided in the System.Workflow.Activities assembly, as Figure 19 shows. For more information about WF see the sidebar "For Workflow Foundation Aficionados."

Figure 19: Workflow assemblies to reference 

The SharePoint team also provided more specific SharePoint activities, which you can find in the Microsoft.SharePoint.WorkflowActions assembly. This assembly can be found in the 14ISAPI folder and is referenced by default in our VS 2010 project.

These activities can be dragged and dropped into the VS workflow design surface from the toolbox (select the SharePoint Workflow panel), which Figure 20 shows.

Figure 20: Workflow activities toolboxes 

Just to make sure that our basic workflow can at least say "Hello World," we will drag and drop LogToHistoryListActivity to the workflow surface. Figure 21 shows the addition of an activity.

Now, in Workflow Designer, select logToHistoryActivity, go to its property page, and type "Hello World" in the HistoryOutcome property, as Figure 22 shows. Deploy the solution as you did previously (selecting Deploy Solution from the Build menu).

Figure 21: Adding an activity

Figure 22: LogToHistoryList activity properties 

Go to the Expense Reports list. Select the expense report that you created earlier, and then click the Workflows button on the SharePoint Ribbon, as Figure 23 shows. The Start a New Workflow window, which Figure 24 shows, appears.

Click the Workflow button to start our workflow. Go to the workflow status, and you should see the Hello World message, as Figure 25 shows.

Figure 23: Choosing a workflow in the SharePoint Ribbon

Figure 24: Starting a workflow

Figure 25: Workflow outcome with Hello World 

Workflow Features

Workflows that are generated from VS 2010 are logically packaged as site collection features. If the feature is not activated, then the workflow template cannot be used.

Workflows that are generated by VS 2010 are compiled as .dll files that must be installed into the global assembly cache (GAC). Therefore, these kinds of workflows cannot run in the sandbox environment, even if we create custom sandbox activities (as I will illustrate in another article).

If you look at the elements.xml file that describes the workflow feature (Figure 26), you will find the element, which points to the workflow class Name, as well as the placeholder for the assembly name.

New in SharePoint 2010 is the element, which can contain List (if the workflow must be associated with a SharePoint list), Site (if the workflow must be associated with a SharePoint site), or Content Type (if the workflow is associated with a content type, which is an excellent practice).

The element specifies the .aspx page that is used to display the workflow status. I usually keep the default _layouts/WrkStat.aspx, but you can replace it with a custom page if needed.

Figure 26: Workflow element.xml file 

Wizard Setting Configuration

If you want to modify the settings that the VS 2010 SharePoint Configuration Wizard provides, then you can select the workflow SharePoint project item, display its property page (which Figure 27 shows), and change the settings. For instance, you can change the Task List, or you can cancel the automatic association of the workflow with the list (via the Auto Associate property).

If you try to modify the task list, a new SharePoint Customization Wizard window will appear, as Figure 28 shows.

Figure 27: Workflow settings provided by the wizard

Figure 28: Triggering the wizard 

Reviewing the Code

If you open the file ExpenseReportWorkflow.cs, you will see a class that is derived from SequentialWorkflowActivity (see Figure 29), which is the root class for Sequential workflows. (There are two kinds of workflows: Sequential and State Machine, which I will illustrate in another article.)

If you open the Designer code, you will see that each activity is a member of this class, which Figure 30 shows.

In the next article of this series, we will enhance this workflow.

Figure 29: Deriving a class from SequentialWorkflowActivity

Figure 30: Activities as class members