70 Part I Introducing Windows Workflow Foundation (WF) 6. In the Name field, type the name of your project or application. 7. In the Location field, type the file system location where you would like your project files stored. 8. If the Create Directory For Solution check box is not already selected, select it. 9. Click OK. Visual Studio 2005 will now create the basic project for you and bring up the workflow visual designer user interface. As with the sequential workflow application, Visual Studio is now ready for us to build a state- machine workflow. We’re not quite ready to actually build a state-machine workflow at this point in the book. Why? Because we need to trigger the events that cause the workflow to change state. To do that, we’ll need to understand how workflow instances communicate with their host applications so that our host application can perform the trigger actions. We’ll begin looking at host and workflow communication in Chapter 8, “Calling External Methods,” but it’s in Chapter 10, “Event Activities,” that we learn what we need to know to drive state-machine workflows. Chapter 4 Introduction to Activities and Workflow Types 71 Chapter 4 Quick Reference To Do This Select the appropriate workflow type Model your system, and look closely at what is controlling the process. If the workflow is controlling the process, select a sequential workflow model. If external inputs are controlling the workflow, select a state-machine workflow. If complex behavior is to be modeled, a rules-based approach might be the best. Often a combination of workflow types will be necessary. Build a sequential workflow application Start Visual Studio 2005, and select the New and then Project menu items from the main File menu. From the resulting New Project dialog box, select the Workflow node from the Visual C# subtree shown in the Project Types pane. From the Templates pane, select either the Sequen- tial Workflow Console Application or the Sequential Workflow Library type. Build a state-machine workflow application Follow the steps for building a sequential workflow appli- cation until you choose the template. In the Templates pane, select either the State Machine Workflow Console Application or the State Machine Workflow Library type. Build a rules-based workflow application Create a sequential workflow application, and then skip to Chapter 12 to learn how to apply the Policy or rule condition. 73 Chapter 5 Workflow Tracking After completing this chapter, you will be able to: ■ Describe workflow-pluggable services ■ Create an event tracking database and populate it with tables and scripts ■ Activate the event-tracking service ■ Create a custom tracking profile ■ View your workflow's tracking information So far we’ve seen the basic objects that workflows are built from and controlled by. We build workflow tasks from activities, which when executing are managed by a WorkflowInstance object. Workflow instances are queued and controlled by the WorkflowRuntime. But Windows Workflow Foundation (WF) doesn’t just provide us with objects—it also provides us with services that work alongside our objects. Pluggable Services Workflow services are additional software functions that your workflows can, and will, use to complete their tasks. Some of the services are optional, like the tracking service we’ll work with in this chapter. Other services are required for your workflow to execute at all. Workflow services are pluggable. A pluggable service is a service that can be selected a la carte to perform specific tasks. For example, there are services that manage threading, tracking, transactions, and so forth. You select the service that’s right for your workflow. You can even create your own. So what do these services look like? What do they do for us? Table 5-1 lays out the available base services and gives you a better idea which services are available and what they do. 74 Part I Introducing Windows Workflow Foundation (WF) Most of these services we don’t use directly. We’ll typically use services derived from these base services. Remember that these are base classes. The services we actually use are derived from these. For instance, when we run a workflow instance, something needs to create a thread for that instance to use. DefaultWorkflowSchedulerService does just that, using WorkflowSchedulerService as its base. But if you want to provide the thread yourself, you can use ManualWorkflowSched- ulerService instead. In this chapter, we’ll look at the tracking service provided by SqlTrackingService, which has TrackingService for a base class. The “pluggable” part comes in when you consider that at any given time you might need to use a scheduler service (one that prepares threads for your workflow instance to use), the runtime service, and queueing and subscriptions (timers). But you can add persistence (saving in-progress workflow instances) and tracking, as well as external data communication services. They all just plug in and work together. Workflow Tracking In this chapter, we’ll concentrate on the tracking service. Other chapters will look at other available services. Regarding tracking, WF ships with one primary tracking service—SqlTrack- ingService. However, should you need them, there are two additional services available as sam- ples. These services, ConsoleTrackingService and SimpleFileTrackingService, allow you to write tracking information to the console window or to files instead of to a Microsoft SQL Server database. We won’t use those services here, but they are available if you need to use them. Table 5-1 Base Workflow Services Service Purpose WorkflowPersistenceSer vice The abstract base class from which all persistence services are derived. WorkflowQueuingService The base class that provides methods you can use to manage the workflow queues associated with a workflow instance. W orkflowRuntimeService The abstract base class from which the workflow runtime core services are derived. WorkflowSchedulerService The base class for all classes that create threads that run workflow instances on the workflow runtime host. Wo rkflowSubscriptionService The base class for classes that manage subscriptions for a workflow runtime. WorkflowTransactionService The base class for all transaction services. Tra ckingSer vice The abstract base class that provides the basic interface between a tracking service and the runtime tracking infrastructure. Chapter 5 Workflow Tracking 75 Note The samples are installed with the Windows SDK—see Chapter 1, “Introducing Microsoft Windows Workflow Foundation” for installation instructions. See also the section in this chapter entitled “Viewing Tracking Information with WorkflowMonitor” for accessing the samples. The tracking services to which I refer, “Console” and “File,” are located in the Tech- nologies directory under “Tracking.” Workflow Event Tracking Using SqlTrackingService You track your workflow processes by adding a tracking service to the workflow runtime—typ- ically, SqlTrackingService. As your workflow instance progresses, it fires events, as do individual activities within your workflow. If you have specific tracking needs, you can create your own user-defined tracking events. If the events that are captured provide you with more tracking data than you require, you can filter the tracked data using a tracking profile you establish. As tracked events fire, WF creates and manages tracking records. Although you’re not required to do so, you can easily access the tracking records directly from WF. Note that the informa- tion is recorded in the database as well, so retrieving the information directly from the data- base is also a possibility. Queries for tracking information are normally made at a later date using an external tracking monitor tool, such as WorkflowMonitor (a tracking tool that comes with WF as a sample, with source code) or a tool of your own design. Table 5-2 lists the objects you’ll typically use when working with WF event tracking, and we’ll use some of these as we progress through the chapter. If all you ever do is use WF’s out- of-the-box event tracking capabilities, you won’t directly use many of the objects shown in Table 5-2, but they will be used by WF on your behalf. However, if you need to customize your workflow’s event tracking capabilities, it’s nice to know WF provides a strong library of track- ing-related objects for you to use. Table 5-2 Event Tracking Objects Object Purpose ActivityDataTrackingExtract Specifies a property or a field to be extracted from an activity and sent to the tracking service together with an associated collection of annotations when a track point is matched. ActivityTrackingCondition Represents a condition resulting from comparing the value of an activity property with a known value by using a specified comparison operator. ActivityTrackingLocation Defines an activity-qualified location that corresponds to an activity status event in the executing root workflow instance. ActivityTrackingRecord Contains the data sent to a tracking service by the runtime track- ing infrastructure when an ActivityTrackP oint is matched. ActivityTrackPoint Defines a point of interest that is associated with an activity exe- cution status change to be tracked. 76 Part I Introducing Windows Workflow Foundation (WF) These objects can be thought of as belonging to two main categories: tracking data retrieval and tracking specification. Tracking retrieval objects, such as SqlTrackingQuery, help you gather tracking data once it is stored in the database. Tracking specification objects, such as the track points and locations, allow you to dictate what is tracked from your workflow code. The tracking specification objects, such as the point and location obects, are organized into three main groups: activity events, workflow events, and user events. The activity-related tracking objects, such as ActivityTrackingPoint or ActivityTrackingLocation, are designed to record activity-related event information to the tracking database. These events include such things as activity cancellation, unhandled exceptions, and execution events. Workflow event- tracking objects work in a similar manner but for workflow-related events, such as the SqlTrackingQuery Provides methods and properties that you can use to access cer- tain kinds of tracking data stored in a SQL database by the Sql- Tracki n gSe r v i c e. SqlTrackingQueryOptions Contains properties that are used to constrain the set of SqlTrack- ingWorkflowInstance objects returned by the SqlTrack- ingQuery.GetWorkflows method. SqlTrackingWorkflowInstance Returned by a call to either SqlTrackingQuery.TryGetWorkflow or SqlTrackingQuery.GetWorkflows to provide access to the tracking data collected by the SqlTrackingService in a SQL database for a specific workflow instance. TrackingProfile Filters tracking events, and returns tracking records based on this filtering to a tracking service. There are three kinds of tracking events that can be filtered: activity status events, workflow status events, and user events. UserTrackingLocation Specifies a user-defined location that corresponds to a user event in the executing root workflow instance. UserTrackingRecord Contains the data sent to a tracking service by the runtime track- ing infrastructure when a UserTrackPoint is matched. UserTrackPoint Defines a point of interest that is associated with a user event. WorkflowDat aTrackingExtract Specifies a property or a field to be extracted from a workflow and sent to the tracking service together with an associated col- lection of annotations when a track point is matched. WorkflowTrackingLocation Defines a workflow-qualified location that corresponds to a workflow event in the executing root workflow instance. W o rkflowTrackingRecord Contains the data sent to a tracking service by the runtime track- ing infrastructure when a WorkflowTrackPoint is matched. WorkflowTrackPoint Defines a point of interest that is associated with a workflow event. Table 5-2 Event Tracking Objects Object Purpose Chapter 5 Workflow Tracking 77 workflow starting and stopping; instances being created, idling, and finishing; and other sim- ilar things. And finally, user event tracking, which is where you customize the tracking needs of your particular workflow, is specific to your workflow and depends entirely on how you want your workflow tracked. You can allow as many or as few tracked user events in your workflow as you require. We’ll see a couple of these when we look at tracking profiles later in the chapter. The tracking records are decorated with annotations. Annotations are just strings that are kept with the tracking record and recorded into the tracking database. The activity-related and workflow-related tracking records have an established collection of annotations, but you might want to provide additional annotations for user-related event tracking records. Tracking in WF terms isn’t that dissimilar to the notion of tracing. Tracing, as you might know, is a useful debugging tool, and ASP.NET and .NET client technologies—such as Windows Presentation Foundation (WPF) and Windows Forms—all support tracing capabilities. Tracing embodies the concept of trace levels, where you specify what is traced for varying degrees of severity, such as tracing on an error, tracing to record a warning, and writing trace entries for informational purposes. This allows people reviewing the trace records to filter the trace information according to their desires. They can see only exception trace information, or they can see the entire trace stack. WF tracking is based on a similar concept, at least as far as the filtering is concerned. As you might imagine, both activity-related and workflow-related events will generate all manner of tracking records, some of which you might find interesting (such as records for unhandled exceptions or idle status). You might decide other events are not as necessary for tracking purposes. To filter the tracked events you don’t want, you create a tracking profile. Ultimately, a tracking profile is an XML document that identifies what is to be tracked and what is to be excluded. Unlike tracing, the tracking profile dictates what is written to the tracking database, not what is later to be viewed. If you exclude events, nothing regarding the excluded events is written to the database. Also unlike tracing, the tracking profile XML document is recorded in the track- ing database and recalled when the workflow is executed. Tracing, on the other hand, records everything designated to be traced but categorizes the trace information for later filtered viewing. Setting Up SQL Server for Tracking Although you could build custom tracking services that record tracking data to various repos- itories (such as a message queue or data file), in this chapter we’ll concentrate on WF’s ability to record event data in a SQL Server 2005 database. WF comes with built-in support for using SQL Server 2005. 78 Part I Introducing Windows Workflow Foundation (WF) Note Because SQL Server 2005 and SQL Server Express both use SQL Server Management Studio, the steps will be identical for either database service, at least as far as establishing the event tracking database itself is concerned. SQL Server Express doesn’t ship with SQL Server Management Studio, but you can download the Express version from this site: www.microsoft.com/ downloads/details.aspx?displaylang=en&FamilyID=C243A5AE-4BD1-4E3D-94B8-5A0F62BF7796 We’ll begin by creating a new database in SQL Server Management Studio (or the Express ver- sion). We’ll then need to run some SQL scripts that ship with the WinFX components (or that come prepackaged with Windows Vista). These scripts will create the database roles, the tables and views, and the stored procedures necessary to interact with your workflow. Let’s start by creating a new database and running some preliminary scripts; then we’ll record tracking data to that database using the WF tracking service. Note I’ll refer to SQL Server Express in the steps that follow, but for those of you using the full version of SQL Server, the steps remain the same. When you read “SQL Server Express,” think to yourself “SQL Server.” Create a SQL Server 2005 tracking database 1. In Microsoft Windows, click the Start button, move the cursor to All Programs, and then select Microsoft SQL Server 2005 from the programs menu. 2. Click the SQL Server Management Studio Express icon to start the SQL Server manage- ment application (or if you have SQL Server installed, click the SQL Server Management Studio icon). 3. We’ll need to connect to the database server we want to use, using the SQL Server Connect To Server dialog box: Chapter 5 Workflow Tracking 79 (If SQL Server Management Studio Express is already running, click the Connect button and then choose Database Engine in the Object Explorer pane.) The Server Type drop- down list should indicate Database Engine (the default value). The Server Name drop- down list should display the server’s name and the instance of SQL Server 2005 you want to use on that server. My server is named “Redbarron,” and the SQL Server instance I want to use is “SQL2005.” If you want to use the default instance, simply provide only the server’s name. As for authentication, you should use the authentication methodol- ogy you selected when you installed SQL Server (or see your database administrator for any assistance you might require). Click Connect to connect to your database server. 4. SQL Server Management Studio Express’s user interface typically consists of two panes. The left pane mimics Windows Explorer and shows the databases and services associ- ated with your database server. The right pane is the work pane, where you’ll type in scripts, set up table columns, and so forth. The left pane is known as the Object Explorer, and if it is not visible, you can activate it by selecting Object Explorer from the View menu. 5. Right-click on the Databases node to activate the context menu, and select New Database. 6. The New Database dialog box appears. Type WorkflowTracking in the Database Name field, and click OK. 80 Part I Introducing Windows Workflow Foundation (WF) If you expand the Databases node in the Object Explorer, you will find that the new WorkflowTracking database has been added. 7. Next we’ll need to execute the scripts Windows Workflow Foundation provides for setting up tracking, starting with the schema script. (This builds the tables and views, as well as creating workflow tracking roles.) The scripts are located in <%WINDIR%>\ Microsoft.NET\Framework\v3.0\Windows Workflow Foundation\SQL\EN, where <%WINDIR%> is your Windows directory (typically, C:\Windows). From SQL Server Management Studio Express’s File menu, select Open and then File, which brings up the common Open File dialog box. Using the controls in the Open File dialog box, locate the schema script, Tracking_Schema.sql. Select that from the available scripts, and click the Open button. Note you’ll need to connect to your database server once again. [...]... for editing by dragging its sln file onto an executing copy of Visual Studio 2 After Visual Studio opens the WorkflowTracker solution for editing, create a separate sequential workflow library project as you did in Chapter 3 to house our new workflow (See the section in Chapter 3 entitled “Adding a sequential workflow project to the WorkflowHost solution”.) Name this workflow library TrackedWorkflow and... TrackedWorkflow project from the list Click OK 15 Open Program.cs in the WorkflowTracker project for editing and then look for this line of code: Console.WriteLine("Waiting for workflow completion."); 16 To create a workflow instance, add this code following the line of code you just located: // Create the workflow instance WorkflowInstance instance = workflowRuntime.CreateWorkflow(typeof(TrackedWorkflow .Workflow1 ));... void ShowWorkflowTrackingEvents(Guid instanceId) { SqlTrackingQuery sqlTrackingQuery = new SqlTrackingQuery(ConfigurationManager ConnectionStrings["TrackingDatabase"] ConnectionString); 90 Part I Introducing Windows Workflow Foundation (WF) SqlTrackingWorkflowInstance sqlTrackingWorkflowInstance = null; sqlTrackingQuery.TryGetWorkflow(instanceId, out sqlTrackingWorkflowInstance); if (sqlTrackingWorkflowInstance... TrackedWorkflow, into the Global Assembly Cache or place their dynamic-link library (DLL) into the same directory as the WorkflowMonitor’s executable file, WorkflowMonitor.exe For this example, it’s easier just to copy the WorkflowMonitor.exe file into the same directory as our workflow executable code Chapter 5 Workflow Tracking 97 Execute WorkflowMonitor 1 Copy the WorkflowMonitor executable file (WorkflowMonitor.exe)... you Monitor your workflows Build and execute WorkflowMonitor, the source code for which is included with the workflow samples that load when you install Workflow Foundation Note you’ll need to introduce your workflow assemblies to the Global Assembly Cache or copy their DLLs into the same subdirectory as WorkflowMonitor.exe so that WorkflowMonitor can display the designer for the workflows it finds... \Workflow\ Chapter5\WorkflowTracker\WorkflowTracker\bin\Debug subdirectory containing the executable and library file for the WorkflowTracker application that we created to demonstrate SqlTrackingService You should find the WorkflowMonitor.exe executable file in the following directory, assuming you built the debuggable version of the application: \Workflow\ Chapter5\Applications\WorkflowMonitor\CS\WorkflowMonitor\bin\Debug\... \Workflow\ Chapter5\Applications\WorkflowMonitor\CS\WorkflowMonitor\bin\Debug\ 2 In Windows Explorer, double-click the WorkflowMonitor.exe file to execute the WorkflowMonitor application 3 WorkflowMonitor stores configuration information in the WorkflowMonitor.config configuration file, found in Application.LocalUserAppDataPath (If you are running SQL Server Express, you may see an error message when WorkflowMonitor tries to connect to SQL Server;... Part I Introducing Windows Workflow Foundation (WF) 5 WorkflowMonitor should then open a connection to the tracking database and read the tracking records it finds there If it has type information, it will display the designer for the workflows it finds In this case, the only workflow it should find is TrackedWorkflow, but as you create more workflows, more will be displayed The WorkflowMonitor user interface... Create the workflow tracking database After creating a new database for the task, execute the SQL scripts you find in the \Microsoft. NET\Framework\v3.0 \Windows Workflow Foundation\ SQL\EN directory within SQL Server Management Studio Express You’ll need to execute both the Tracking_Schema.sql script and the Tracking_Logic.sql script Use the SqlTrackingService After creating an instance of WorkflowRuntime... it easier to monitor your workflow when we use WorkflowMonitor later in the chapter 3 After you have completed the steps to add the workflow library project, Visual Studio opens the visual workflow designer for editing If it doesn’t, locate the Workflow1 .cs file in Visual Studio’s Solution Explorer and click the View Designer toolbar button to activate the designer 4 For this workflow, let’s combine . activities, which when executing are managed by a WorkflowInstance object. Workflow instances are queued and controlled by the WorkflowRuntime. But Windows Workflow Foundation (WF) doesn’t just provide. <%WINDIR%> Microsoft. NETFrameworkv3.0 Windows Workflow Foundation SQLEN, where <%WINDIR%> is your Windows directory (typically, C: Windows) . From SQL Server Management Studio Express’s. Chapter 3 to house our new workflow. (See the section in Chapter 3 entitled “Adding a sequential workflow project to the WorkflowHost solution”.) Name this workflow library TrackedWorkflow