Walkthrough: Create and debug a SharePoint workflow solution

Article
02/02/2017

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

This walkthrough demonstrates how to create a basic sequential workflow template. The workflow checks a property of a shared document library to determine whether a document has been reviewed. If the document has been reviewed, the workflow finishes.

This walkthrough illustrates the following tasks:

Creating a SharePoint list definition sequential workflow project in Visual Studio.
Creating workflow activities.
Handling workflow activity events.

Note

Although this walkthrough uses a sequential workflow project, the process is identical for a state machine workflow project.

Also, your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Personalize the Visual Studio IDE.

Prerequisites

You need the following components to complete this walkthrough:

Supported editions of Microsoft Windows and SharePoint.
Visual Studio.

Add properties to the SharePoint shared documents library

To track the review status of documents in the Shared Documents library, we will create three new properties for shared documents on our SharePoint site: Status, Assignee, and Review Comments. We define these properties in the Shared Documents library.

To add properties to the SharePoint shared documents library

Open a SharePoint site, such as http://<system name>/SitePages/Home.aspx, in a Web browser.
On the QuickLaunch bar, choose SharedDocuments.
Choose Library on the Library Tools ribbon and then choose the Create Column button on the ribbon to create a new column.
Name the column Document Status, set its type to Choice (menu to choose from), specify the following three choices, and then choose the OK button:
- Review Needed
- Review Complete
- Changes Requested
Create two more columns and name them Assignee and Review Comments. Set the Assignee column type as a single line of text, and the Review Comments column type as multiple lines of text.

Enable documents to be edited without requiring a check out

It is easier to test the workflow template when you can edit the documents without having to check them out. In the next procedure, you configure the SharePoint site to enable that.

To enable documents to be edited without checking them out

On the QuickLaunch bar, choose the Shared Documents link.
On the Library Tools ribbon, choose the Library tab, and then choose the Library Settings button to display the Document Library Settings page.
In the General Settings section, choose the Versioning Settings link to display the Versioning Settings page.
Verify that the setting for Require documents to be checked out before they can be edited is No. If it is not, change it to No and then choose the OK button.
Close the browser.

Create a SharePoint sequential workflow project

A sequential workflow is a set of steps that executes in order until the last activity finishes. In this procedure, we create a sequential workflow that will apply to our Shared Documents list. The workflow wizard lets you associate the workflow with either the site definition or the list definition and lets you determine when the workflow will start.

To create a SharePoint sequential workflow project

Start Visual Studio.
On the menu bar, choose File > New > Project to display the New Project dialog box.
Expand the SharePoint node under either Visual C# or Visual Basic, and then choose the 2010 node.
In the Templates pane, choose the SharePoint 2010 Project template.
In the Name box, enter MySharePointWorkflow and then choose the OK button.

The SharePoint Customization Wizard appears.
In the Specify the site and security level for debugging page, choose the Deploy as a farm solution option button, and then choose the Finish button to accept the trust level and default site.

This step sets the trust level for the solution as farm solution, the only available option for workflow projects. For more information, see Sandboxed solution considerations.
In Solution Explorer, choose the project node, and then, on the menu bar, choose Project > Add New Item.
Under either Visual C# or Visual Basic, expand the SharePoint node, and then choose the 2010 node.
In the Templates pane, choose the Sequential Workflow (Farm Solution only) template, and then choose the Add button.

The SharePoint Customization Wizard appears.
In the Specify the workflow name for debugging page, accept the default name (MySharePointWorkflow - Workflow1). Keep the default workflow template type value, List Workflow, and then choose the Next button.
In the Would you like Visual Studio to automatically associate the workflow in a debug session? page, choose the Next button to accept all of the default settings.

This step automatically associates the workflow with the Shared Documents library.
In the Specify the conditions for how your workflow is started page, leave the default options selected in the How do you want the workflow to start? section and choose the Finish button.

This page enables you to specify when your workflow starts. By default, the workflow starts either when a user manually starts it in SharePoint or when an item to which the workflow is associated is created.

Create workflow activities

Workflows contain one or more activities that represent actions to perform. Use the workflow designer to arrange activities for a workflow. In this procedure, we will add two activities to the workflow: HandleExternalEventActivity and OnWorkFlowItemChanged. These activities monitor the review status of documents in the Shared Documents list

To create workflow activities

The workflow should be displayed in the workflow designer. If it is not, then open either Workflow1.cs or Workflow1.vb in Solution Explorer.
In the designer, choose the OnWorkflowActivated1 activity.
In the Properties window, enter onWorkflowActivated next to the Invoked property, and then choose the Enter key.

The Code Editor opens, and an event handler method named onWorkflowActivated is added to the Workflow1 code file.
Switch back to the workflow designer, open the toolbox, and then expand the Windows Workflow v3.0 node.
In the Windows Workflow v3.0 node of the Toolbox, perform one of the following sets of steps:
1. Open the shortcut menu for the While activity, and then choose Copy. In the workflow designer, open the shortcut menu for the line under the onWorkflowActivated1 activity, and then choose Paste.
2. Drag the While activity from the Toolbox to the workflow designer, and connect the activity to the line under the onWorkflowActivated1 activity.
Choose the WhileActivity1 activity.
In the Properties window, set Condition to Code Condition.
Expand the Condition property, enter isWorkflowPending next to the child Condition property, and then choose the Enter key.

The Code Editor opens, and a method named isWorkflowPending is added to the Workflow1 code file.
Switch back to the workflow designer, open the toolbox, and then expand the SharePoint Workflow node.
In the SharePoint Workflow node of the Toolbox, perform one of the following sets of steps:
- Open the shortcut menu for the OnWorkflowItemChanged activity, and then choose Copy. In the workflow designer, open the shortcut menu for the line inside the whileActivity1 activity, and then choose Paste.
- Drag the OnWorkflowItemChanged activity from the Toolbox to the workflow designer, and connect the activity to the line inside the whileActivity1 activity.
Choose the onWorkflowItemChanged1 activity.
In the Properties window, set the properties as shown in the following table.

Property Value

CorrelationToken workflowToken

Invoked onWorkflowItemChanged

Property	Value
CorrelationToken	workflowToken
Invoked	onWorkflowItemChanged

Handle activity events

Finally, check the status of the document from each activity. If the document has been reviewed, then the workflow is finished.

To handle activity events

In Workflow1.cs or Workflow1.vb, add the following field to the top of the Workflow1 class. This field is used in an activity to determine whether the workflow is finished.
```
Dim workflowPending As Boolean = True
```
```
Boolean workflowPending = true;
```
Add the following method to the Workflow1 class. This method checks the value of the Document Status property of the Documents list to determine whether the document has been reviewed. If the Document Status property is set to Review Complete, then the checkStatus method sets the workflowPending field to false to indicate that the workflow is ready to finish.
```
Private Sub checkStatus()
    If CStr(workflowProperties.Item("Document Status")) = "Review Complete" Then
        workflowPending = False
    End If
End Sub
```
```
private void checkStatus()
{
    if ((string)workflowProperties.Item["Document Status"] == "Review Complete")
    workflowPending = false;
}
```

Add the following code to the onWorkflowActivated and onWorkflowItemChanged methods to call the checkStatus method. When the workflow starts, the onWorkflowActivated method calls the checkStatus method to determine whether the document has already been reviewed. If it has not been reviewed, the workflow continues. When the document is saved, the onWorkflowItemChanged method calls the checkStatus method again to determine whether the document has been reviewed. While the workflowPending field is set to true, the workflow continues to run.

Private Sub onWorkflowActivated(ByVal sender As System.Object, ByVal e As System.Workflow.Activities.ExternalDataEventArgs)
    checkStatus()
End Sub

Private Sub onWorkflowItemChanged(ByVal sender As System.Object, ByVal e As System.Workflow.Activities.ExternalDataEventArgs)
    checkStatus()
End Sub

private void onWorkflowActivated(object sender, ExternalDataEventArgs e)
{
    // Check the status.
    checkStatus();
}

private void onWorkflowItemChanged(object sender, ExternalDataEventArgs e)
{
    // Check the status.
    checkStatus();
}

Add the following code to the isWorkflowPending method to check the status of the workflowPending property. Each time the document is saved, the whileActivity1 activity calls the isWorkflowPending method. This method examines the Result property of the ConditionalEventArgs object to determine whether the WhileActivity1 activity should continue or finish. If the property is set to true, the activity continues. Otherwise, the activity finishes and the workflow finishes.
```
Private Sub isWorkflowPending(ByVal sender As System.Object, ByVal e As System.Workflow.Activities.ConditionalEventArgs)
    e.Result = workflowPending
End Sub
```
```
private void isWorkflowPending(object sender, ConditionalEventArgs e)
{
    e.Result = workflowPending;
}
```
Save the project.

Test the SharePoint workflow template

When you start the debugger, Visual Studio deploys the workflow template to the SharePoint server and associates the workflow with the Shared Documents list. To test the workflow, start an instance of the workflow from a document in the Shared Documents list.

To test the SharePoint workflow template

In Workflow1.cs or Workflow1.vb, set a breakpoint next to the onWorkflowActivated method.
Choose the F5 key to build and run the solution.

The SharePoint site appears.
In the navigation pane in SharePoint, choose the Shared Documents link.
In the Shared Documents page, choose the Documents link on the Library Tools tab, and then choose the Upload Document button.
In the Upload Document dialog box, choose the Browse button, choose any document file, choose the Open button, and then choose the OK button.

This uploads the selected document into the Shared Documents list and starts the workflow.
In Visual Studio, verify that the debugger stops at the breakpoint next to the onWorkflowActivated method.
Choose the F5 key to continue execution.
You can change the settings for the document here, but leave them at the default values for now by choosing the Save button.

This returns you to the Shared Documents page of the default SharePoint Web site.
In the Shared Documents page, verify that the value underneath the MySharePointWorkflow - Workflow1 column is set to In Progress. This indicates that the workflow is in progress and that the document is awaiting review.
In the Shared Documents page, choose the document, choose the arrow that appears, and then choose the Edit Properties menu item.
Set Document Status to Review Complete, and then choose the Save button.

This returns you to the Shared Documents page of the default SharePoint Web site.
In the Shared Documents page, verify that the value underneath the Document Status column is set to Review Complete. Refresh the Shared Documents page and verify that the value underneath the MySharePointWorkflow - Workflow1 column is set to Completed. This indicates that workflow is finished and that the document has been reviewed.

Next steps

You can learn more about how to create workflow templates from these topics:

To learn more about SharePoint workflow activities, see Workflow Activities for SharePoint Foundation.
To learn more about Windows Workflow Foundation activities, see System.Workflow.Activities Namespace.