Tracking Using User Track Points Sample

Article
01/09/2007

This sample illustrates the use of the SQL tracking service that is provided by Windows Workflow Foundation to track the execution of a workflow.

The workflow runtime raises certain events while it is executing a workflow. The tracking service can catch these events and store information about them in a SQL Server database that can be queried.

The workflow runtime raises the following types of events:

Workflow instance-level events. These events are raised when a workflow instance enters into a particular state. For example, an event is raised when the workflow instance is initialized or when the workflow instance is executing.
Activity-level events. A workflow consists of activities, and each activity follows a life cycle. During its life cycle, the activity passes through multiple states. An event is raised when an activity reaches a particular state.
User-tracked events. A workflow author can create custom tracking events and add them to the code-beside of the workflow.

Data from the workflow data context can be emitted and given to the tracking service together with the events.

When you are tracking a workflow, you might not be interested in all events for all states and activities. You can create a tracking profile to specify the events and data that you are interested in.

Writing Custom Track Points

You might want to track a piece of data at a particular point in the execution of the workflow that is not tracked by the tracking events. In this case, you can use custom track points. You create a custom track point by using the TrackData method that is provided on the data context class. The TrackData method takes an argument of an object. This means that you can emit any kind of data that you want to track. In the sample workflow, a custom track point is created in the code handler of the code activity.

Creating the Custom Tracking Profile

The sample illustrates how to create a custom tracking profile to track the user track point. This profile is inserted into the SQL tracking database to track the specified events. The tracking profile is created by using the tracking profile object model.

The tracking profile object model provides a set of classes that help create the instance tracking point, activity tracking points, and user track points. Each tracking point also contains a set of matching locations. A matching location describes the event to be tracked (which is different based on whether it is an instance track point or an activity track point) and the activity (or workflow in case of an instance track point) to be tracked.

The data to be extracted can also be specified in the track point. In this example, no data extracts have been specified.

Use the following code to create the tracking profile to track the user track point:

TrackingProfile profile = new TrackingProfile();

ActivityTrackPoint trackPoint = new ActivityTrackPoint();
ActivityTrackingLocation location = new ActivityTrackingLocation(typeof(Activity));
location.MatchDerivedTypes = true;
foreach (ActivityExecutionStatus s in Enum.GetValues(typeof(ActivityExecutionStatus)))
{
    location.ExecutionStatusEvents.Add(s);
}

trackPoint.MatchingLocations.Add(location);
profile.ActivityTrackPoints.Add(trackPoint);
profile.Version = new Version("3.0.0.0");


// Adding a user track point to the tracking profile.
UserTrackPoint utp = new UserTrackPoint();

// Adding a user location to the track point. 
UserTrackingLocation ul = new UserTrackingLocation(typeof(string), typeof(CodeActivity));
ul.MatchDerivedActivityTypes = true;
utp.MatchingLocations.Add(ul);
profile.UserTrackPoints.Add(utp);


// Serialize the profile.
TrackingProfileSerializer serializer = new TrackingProfileSerializer();
StringWriter writer = new StringWriter(new StringBuilder());
serializer.Serialize(writer, profile);
string trackingprofile = writer.ToString();
InsertTrackingProfile(trackingprofile);

In the previous code example, the last four lines specify how the tracking profile can be serialized into an XML format and stored in the tracking database. After the tracking profile is serialized, it looks like the following:

<?xml version=\"1.0\" encoding=\"utf-16\" standalone=\"yes\"?>

<TrackingProfile xmlns=\"https://schemas.microsoft.com/winfx/2006/workflow/trackingprofile\" version=\"3.0.0.0\">

<TrackPoints> <ActivityTrackPoint>

<MatchingLocations>

<ActivityTrackingLocation>

<Activity>

<Type>System.Workflow.ComponentModel.Activity, System.Workflow.ComponentModel, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35</Type>

<MatchDerivedTypes>true</MatchDerivedTypes>

</Activity>

<ExecutionStatusEvents>

<ExecutionStatus>Initialized</ExecutionStatus>

<ExecutionStatus>Executing</ExecutionStatus>

<ExecutionStatus>Canceling</ExecutionStatus>

<ExecutionStatus>Closed</ExecutionStatus>

<ExecutionStatus>Compensating</ExecutionStatus>

<ExecutionStatus>Faulting</ExecutionStatus>

</ExecutionStatusEvents>

</ActivityTrackingLocation>

</MatchingLocations>

</ActivityTrackPoint>

<UserTrackPoint>

<MatchingLocations>

<UserTrackingLocation>

<Activity>

<Type>System.Workflow.Activities.CodeActivity, System.Workflow.Activities, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35</Type>

<MatchDerivedTypes>true</MatchDerivedTypes>

</Activity>

<Argument>

<Type>System.String, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</Type>

<MatchDerivedTypes>false</MatchDerivedTypes>

</Argument>

</UserTrackingLocation>

</MatchingLocations>

</UserTrackPoint>

</TrackPoints>

</TrackingProfile>

The tracking profile is created by using the tracking profile schema.

Inserting the Tracking Profile into the SQL Tracking Database

The tracking profile is inserted into the tracking profile database by using the UpdateTrackingProfile stored procedure. The stored procedure stores the profile for a particular workflow type. When the runtime asks the tracking service for a profile for the type, the tracking service returns this custom profile instead of the default profile.

Registering the Tracking Service with the Workflow Host

Use the following code to register a tracking service with the workflow runtime:

WorkflowRuntime workflowRuntime = new WorkflowRuntime();
workflowRuntime.AddService(new SqlTrackingService(connectionstring));
workflowRuntime.StartRuntime();

The second line registers the SQL tracking service with the workflow runtime. The connection string is the connection string of the tracking database.

Creating the Tracking Database

The SQL services that are installed by Windows Workflow Foundation use Microsoft SQL Server to store information. You can use Microsoft SQL Server 2005 Express, SQL Server 2000 or later versions, or SQL Server 2000 Desktop Engine (MSDE) for these tasks.

Windows Workflow Foundation Setup does not install the databases that are required by these services; however, Setup installs the SQL scripts for creating and configuring the databases for these services.

To create the SQL tracking database

Using Microsoft SQL Server 2005 Express, SQL Server 2000 or later versions, or SQL Server 2000 Desktop Engine (MSDE), create a new database named Tracking by using the SQL query statement:
```
CREATE DATABASE Tracking
```
In the SQL Query Analyzer workspace, select the database that you created in step 1 in the list of available databases.
On the File menu, click Open and open the SQL script %WINDIR%\Microsoft.NET\Framework\v3.0\Windows Workflow Foundation\SQL\<language>\Tracking_Schema.sql.
Execute the query by clicking Execute or by pressing F5 to create the SQL Tracking Service tables.
On the File menu, click Open and open the SQL script %WINDIR%\Microsoft.NET\Framework\v3.0\Windows Workflow Foundation\SQL\<language>\Tracking_Logic.sql.
Execute the query by clicking Execute or by pressing F5 to create the SQL Tracking Service stored procedures.

To build the sample

Download the sample by clicking Download Sample.

This extracts the sample project to your local hard disk.
Click Start, point to Programs, point to Microsoft Windows SDK, and then click CMD Shell.
Go to the source directory of the sample.
At the command prompt, type MSBUILD <Solution file name>.

To run the sample

In the SDK Command Prompt window, run the .exe file in the UserTrackPoints\bin\debug folder (or the UserTrackPoints\bin folder for the VB version of the sample), which is located below the main folder for the sample.

Tracking Using User Track Points Sample

Writing Custom Track Points

Creating the Custom Tracking Profile

Inserting the Tracking Profile into the SQL Tracking Database

Registering the Tracking Service with the Workflow Host

Creating the Tracking Database

To create the SQL tracking database

To build the sample

To run the sample

See Also

Reference

Other Resources

Additional resources