Creating and Using Tracking Profiles

Article
03/05/2010

Tracking profiles are used to filter tracking information so that you receive only tracking information that you are interested in. To accomplish this, tracking services use a TrackingProfile object to request tracking information. When a new workflow instance starts, the tracking framework calls TryGetProfile on each tracking service that is registered with the runtime. The type of the workflow instance is provided as a parameter to this call. If the tracking service wants to receive tracking information for the instance in question (usually determined by the type of instance running), it returns true and specifies a TrackingProfile object as an out parameter. The TrackingProfile object contains information that tells the tracking runtime what events and data the tracking service wants to receive. When the tracking framework receives an event that is specified in the tracking profile, it sends the event information to the tracking service by using a tracking channel.

Tracking profiles can be represented as XML files that use the TrackingProfile schema that is defined in Windows Workflow Foundation. Tracking profiles also have a complex object model that abstracts their details. You can create a tracking profile by using the object model or by using XML. However, tracking profiles that are represented in XML form must be deserialized to a TrackingProfile object because the runtime expects a TrackingProfile object.

Warning

If you use non-English variables in your tracking profiles, the tracking profile file should be saved with Unicode encoding.

Tracking Profile Object Model Elements

A TrackingProfile object enables you to track workflow instance events, individual activity events, and custom user events. The tracking profile object model uses various objects to construct a tracking profile that enables granular control over the information that the tracking service receives from the runtime engine.

Track Points

A TrackingProfile contains three different types of track points. Three kinds of tracking events can be filtered:

Activity status events.
Workflow status events.
User events.

You can add WorkflowTrackPoint objects to the WorkflowTrackPoints property to match specific workflow status events; you can add ActivityTrackPoint objects to the ActivityTrackPoints property to match specific activity status events; and you can add UserTrackPoint objects to the UserTrackPoints property to match specific user events.

WorkflowTrackPoint

Whenever the status of the workflow instance changes, the workflow instance emits a workflow status event that is based on one of the TrackingWorkflowEvent values to the runtime tracking infrastructure. A WorkflowTrackPoint defines an interest in all the points during the execution of a workflow instance at which specific types of workflow status events occur. These status events are defined in the MatchingLocation property of the WorkflowTrackPoint. For information about the relation between tracking locations and a WorkflowTrackPoint, see the "Tracking Locations" section in this topic.

A WorkflowTrackPoint can also specify additional associated information that should be sent by the runtime tracking infrastructure by adding Annotations. Annotations are strings that you define that contain information to associate with the WorkflowTrackPoint. For example, an annotation could contain information about the possible execution path that the workflow can take from this track point, or it could contain information to be displayed in an application.

ActivityTrackPoint

Whenever the status of an activity changes, the workflow instance emits an activity status event that is based on one of the ActivityExecutionStatus values to the runtime tracking infrastructure. An ActivityTrackPoint defines a point of interest in the potential execution path of a root workflow, qualified by such an activity status event. An ActivityTrackPoint contains locations that are included in matching using the MatchingLocations property, locations that are excluded from matching using the ExcludedLocations property, and the data that should be extracted from the workflow instance when the track point is matched using the Extracts property.

The Extracts property is an ExtractCollection that contains ActivityDataTrackingExtract or WorkflowDataTrackingExtract objects. When you add an ActivityDataTrackingExtract object to the ExtractCollection, the Member property points to a field or property of the activity, a member of such a field or property, or a single element of a field or property (or a member of either) that implements the IEnumerable interface. The value of the member is put into the Body property of the associated ActivityTrackingRecord when the ActivityTrackPoint is matched. The WorkflowDataTrackingExtract object can be used to extract members of the workflow during this particular activity event.

UserTrackPoint

An activity designer or a workflow designer can use the overloaded System.Workflow.ComponentModel.Activity.TrackData(System.Object) and System.Workflow.ComponentModel.ActivityExecutionContext.TrackData(System.Object) methods to instrument the workflow to emit data to the runtime tracking infrastructure as a user event. The data that is emitted is referred to as user data. Unlike activity status events, and workflow status events, which occur only on status changes, user events can occur at any location that is instrumented in a workflow. There are many reasons to instrument a workflow to emit user events. For example, a workflow designer might want to communicate logical state information about the progress of a workflow, or an activity designer might want to provide an opportunity to activity members at times other than an activity status change.

A UserTrackPoint defines a point of interest in the potential execution path of a root workflow instance that is associated with a user event. A UserTrackPoint contains locations that are included in matching, locations that are excluded from matching, and any additional data that should be extracted from the workflow instance when the track point is matched. You can add a UserTrackPoint to System.Workflow.Runtime.Tracking.TrackingProfile.UserTrackPoints to instruct the runtime tracking infrastructure to send a UserTrackingRecord to the tracking service when the track point is matched. The user data is returned in System.Workflow.Runtime.Tracking.UserTrackingRecord.UserData. A single UserTrackPoint can be matched at multiple points in the workflow instance.

A UserTrackingLocation contains match conditions for a location that is associated with a user event in the potential execution path of a workflow instance. You can add UserTrackingLocation objects to MatchingLocations to define locations that should be included in matching for the track point. Similarly, you can add UserTrackingLocation objects to ExcludedLocations to define locations that should be excluded from matching for the track point. For information about the relation between tracking locations and a UserTrackPoint, see the "Tracking Locations" section in this topic.

You can add ActivityDataTrackingExtract objects and WorkflowDataTrackingExtract objects to Extracts to specify data that should be extracted from the workflow instance when the track point is matched. The extracted data is returned in System.Workflow.Runtime.Tracking.UserTrackingRecord.Body.

You can add to Annotations to specify additional information that is associated with the track point. These annotations are returned in Annotations.

Tracking Locations

The previous section explained how to associate track points with a TrackingProfile to specify the type of events that are processed by the tracking service that is used in the Windows Workflow Foundation runtime engine. These track points use tracking locations to match specific types in the workflow definition.

WorkflowTrackingLocation

A WorkflowTrackingLocation is used to track events that occur whenever the status of the workflow instance changes. The Events property that is defined in the WorkflowTrackingLocation class enables you to set the list of workflow status events that will be matched. These events can be any combination of values that are defined in the TrackingWorkflowEvent enumeration.

ActivityTrackingLocation

An ActivityTrackingLocation is used to track events that occur whenever the status of an activity in a workflow instance changes. The ActivityTrackingLocation matches the events that are raised from the activities that are specified in the ActivityTypeName or ActivityType properties. The ActivityType property is used when you specify a Type object. The ActivityTypeName property, however, can be used to specify an unqualified name of the reference activity type. For example, to specify the unqualified name of a CodeActivity activity, set the ActivityTypeName property to "CodeActivity".

The ExecutionStatusEvents property that is defined in the ActivityTrackingLocation class enables you to filter the type of activity level events that are processed by the tracking service. At least one of the ActivityExecutionStatus values in the ExecutionStatusEvents collection must be matched, and every TrackingCondition in the Conditions property must be true for the ActivityTrackingLocation to be matched. An empty list specifies that no events are to be matched.

An ActivityTrackingCondition enables you to exercise additional control on the granularity of the activity to track. The Member property of the ActivityTrackingCondition class specifies a property or field, a member of an activity property or field, or a single element of an activity property or field (or a member of either) that implements the IEnumerable interface that is defined in the activity that you want to track. The Value property denotes the value that you want to compare the Member property with by using the specified Operator. By using these three properties in the ActivityTrackingCondition class with an ActivityTrackingLocation, you can, for example, specify that you want to track only CodeActivity activities whose Name property is equal to "CodeActivity1".

UserTrackingLocation

An activity designer or a workflow designer can use any of the overloaded System.Workflow.ComponentModel.Activity.TrackData(System.Object) and System.Workflow.ComponentModel.ActivityExecutionContext.TrackData(System.Object) methods to instrument the workflow to emit data to the runtime tracking infrastructure as a user event. The data that is emitted is referred to as user data. Unlike activity status events and workflow status events, which occur only on activity or workflow status changes, user events can occur at any location that is instrumented in a workflow. A UserTrackingLocation defines the matching parameters for such a location by specifying the type of the user data, the type of the activity from which it must be emitted, a collection of conditions that can more precisely qualify an instance or instances of this activity, an optional key name with which the user data must be associated, whether derived types of the user data should be matched, and whether user data emitted from activities derived from the type of the specified activity should be matched.

Note

A single UserTrackingLocation can refer to more than one actual location in the potential execution path of a workflow instance.

You can add a UserTrackingLocation to either the System.Workflow.Runtime.Tracking.UserTrackPoint.MatchingLocations or System.Workflow.Runtime.Tracking.UserTrackPoint.ExcludedLocations properties to define the match parameters for a UserTrackPoint in a TrackingProfile.

Matching Conditions

There are three general conditions that must be met in the following order for the UserTrackingLocation to be matched by the runtime tracking infrastructure:

The activity that has emitted a user event must match the set of activities that is specified by the ActivityType, ActivityTypeName, Conditions, and MatchDerivedActivityTypes properties.
The key, if one exists, that is associated with the user data must match the KeyName property.
The type of the user data that is emitted by the user event must match the set of user data types that are specified by the ArgumentType, ArgumentTypeName, and MatchDerivedArgumentTypes properties.

Only if all three conditions are met, does the runtime tracking infrastructure consider the UserTrackingLocation matched.

Configuration

To configure a UserTrackingLocation, you must set either the ArgumentTypeName property or the ArgumentType property to specify the type of the user data to be matched. You must also set either the ActivityTypeName property or the ActivityType property to specify the type of the activity from which the user data must be emitted to be matched. You may add ActivityTrackingCondition objects to Conditions to more completely qualify the activity from which the user data must be emitted. You may set the MatchDerivedArgumentTypes property to specify that user data that is derived from the user data type that is specified by the ArgumentTypeName or ArgumentType properties should be matched, and you may set the MatchDerivedActivityTypes property to specify that user data emitted from activities that are derived from the activity type specified by the ActivityTypeName or ActivityType properties should be matched.

You can set KeyName to specify that only user data associated with the specified key name should be matched for this UserTrackingLocation. If the KeyName property is a null reference (Nothing in Visual Basic), the runtime tracking structure does not try to match the key that is associated with the user data.

Using the Tracking Profile Object Model

As previously mentioned, you can use the Windows Workflow Foundation API to create a TrackingProfile object for use in your tracking service. The tracking profile object model uses the set of classes described in the previous section to create a TrackingProfile object. The TrackingProfile object contains tracking points that are related to workflow, activity, and user track points. Each tracking point also has a set of matching locations. A matching location describes the event that will be tracked and the activity to be tracked. You can also define excluded locations in addition to the matching locations.

The activity properties that are used in the tracking profile should map with the names in the activity object model.

Warning

The tracking service accesses public properties that are set up for tracking in a tracking profile. This can cause unexpected results in a workflow.

For example, you create a workflow that has a public incremental counter property that is incremented every time that the counter property is accessed. If you create a tracking profile that tracks the counter property, the tracking service accesses the counter property and the counter is incremented. In this scenario, the property is unexpectedly incremented by the tracking service outside the business logic of the workflow.

The following code example demonstrates how to create a tracking profile that tracks a CodeActivity activity and three events: Initialized, Executing, and Closed. The profile has a single ActivityTrackPoint with one matching location.

static void CreateSimpleTrackingProfile()
{

    TrackingProfile myProfile = new TrackingProfile();
    ActivityTrackPoint myTrackPoint = new ActivityTrackPoint();
    ActivityTrackingLocation myLocation = new ActivityTrackingLocation(typeof(CodeActivity));
    myLocation.MatchDerivedTypes = false;
    myLocation.ExecutionStatusEvents.Add(ActivityExecutionStatus.Initialized);
    myLocation.ExecutionStatusEvents.Add(ActivityExecutionStatus.Executing);
    myLocation.ExecutionStatusEvents.Add(ActivityExecutionStatus.Closed);
    myTrackPoint.MatchingLocations.Add(myLocation);
    myProfile.ActivityTrackPoints.Add(myTrackPoint);
    myProfile.Version = new Version("1.0.0.0");
    TrackingProfileSerializer trackingProfileSerializer = new TrackingProfileSerializer();
    StringBuilder trackingProfileString = new StringBuilder();
    using (StringWriter writer = new StringWriter(trackingProfileString, CultureInfo.InvariantCulture))
    {
        trackingProfileSerializer.Serialize(writer, myProfile);
        Console.WriteLine(writer.ToString());
    }
}

Creating and Using XML for a TrackingProfile

You can also write tracking profiles by using XML. When you do this, you must deserialize the XML into a TrackingProfile. The corresponding XML representation for the TrackingProfile that was created in the previous section is as follows.

<?xml version="1.0" encoding="utf-16" standalone="yes"?>
<TrackingProfile xmlns="https://schemas.microsoft.com/winfx/2006/workflow/trackin
gprofile" version="1.0.0.0">
    <TrackPoints>
        <ActivityTrackPoint>
            <MatchingLocations>
                <ActivityTrackingLocation>
                    <Activity>
                        <Type>System.Workflow.Activities.CodeActivity, System.Wo
rkflow.Activities, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad36
4e35</Type>
                        <MatchDerivedTypes>false</MatchDerivedTypes>
                    </Activity>
                    <ExecutionStatusEvents>
                        <ExecutionStatus>Initialized</ExecutionStatus>
                        <ExecutionStatus>Executing</ExecutionStatus>
                        <ExecutionStatus>Closed</ExecutionStatus>
                    </ExecutionStatusEvents>
                </ActivityTrackingLocation>
            </MatchingLocations>
        </ActivityTrackPoint>
    </TrackPoints>
</TrackingProfile>

The XML representation of a TrackingProfile can also be constructed using the Tracking Profile object model and the TrackingProfileSerializer class that is included in Windows Workflow Foundation.

The following example demonstrates how to serialize a TrackingProfile object into XML data.

TrackingProfileSerializer serializer = new TrackingProfileSerializer();
StringWriter writer = new StringWriter(new StringBuilder(),CultureInfo.InvariantCulture);
serializer.Serialize(writer, profile);
string trackingprofile = writer.ToString();