(WF4) Visual Workflow Tracking and WorkflowInspectionServices
Over time a few folks have asked on the forum for information about writing rehosted visual workflow debugger applications (a.k.a. workflow simulator, a.k.a. visual workflow tracking…).
Many of these folks have already seen the Visual Workflow Tracking sample (MSDN), and even read at least one of Kushal’s related blog posts (“Debugging in Workflow 4.0” , “VisualWorkflowTracking aka Workflow Simulator”, and “Visual Workflow Tracking with Step Service”). But since it’s still a reasonably popular subject to ask questions on it seems like a good time to rehash it, and add a little information on very closely related subjects.
1 – General Limitations
At first glance (at the pictures) the Visual Workflow Tracking samples might appear to show a debugging experience extremely similar to the workflow debugging experience Visual Studio. Now actually it is different, and while it is true that the two scenarios rely on some of the same code, one significant difference to be aware of is that Visual Studio is literally debugging the activities as you run because it has information about which activity is executing gained because it is attaching as a debugger. This is immediately different from the Visual Workflow Tracking sample which is working based on a completely different source of information about workflow execution, namely data from the Workflow 4.0 ‘Tracking‘ feature (for a very quick intro on the Tracking feature see here, but please note that it refers to Beta 1 of .Net 4.0, not the final release. Also see the MSDN description which refers to the actual release). This means you might not be able to easily implement every debugging feature you are familiar with such as breakpoints, or if you can implement them that they may end up needing to behave slightly different to the Visual Studio behavior.
Now most parts of the sample code are useful no matter you get information about the currently executing state of the workflow – if you get creative it could be something completely different from workflow tracking. However, there is one more limitation of the sample code, which many people will want to overcome. The sample itself contains a workflow which executed live and in the same process as the visual workflow tracker. In many cases customers are interested in doing something which is not the same, what they actually want to do is allow a) visualizing a workflow which ran in a different process (e.g. on a server machine) or b) replay of a workflow which finished executing some time in the past.
The impact of this is that instead of working from an Activity object, which is available as part of the TrackingRecord (on the derived subclasses) received by Participants, as the initial input into figuring out which activity is executing and needs displaying in the debugger, instead one must work with whatever Activity tracking data the TrackingParticipant saves to a database or log, which would typically include not the Activity object itself (this wouldn’t do what we want), instead it would usually include information such as an Activity ID.
2 - Activity IDs
OK, that’s great but what is an Activity ID? Well, it’s actually a special string. Here’s a concrete example that I totally made up and might even look wrong:
“0.1.2.1.4”
The important part of the example which isn’t wrong is that an Activity ID is just a series of numbers – numbers of significance! The numbers are in fact a path in your Activity tree. This is basically just like a file system path, “C:\foo\bar\temp\readme.txt”, so it refers to a unique entity within a tree, and a given Activity ID always refers to a particular Activity as long as you are talking about the same exact workflow.
Yes, I need to clarify that. It has to be the same exact workflow (workflow structure, not workflow instance) for two reasons.
First reason:
Look at the Activity ID string again. “0.1.2.1.4” is really, when interpreted as a suffix instead of a complete string, just a relative path – it’s relative to some root activity.
Second reason:
Think about the numbers! How is “0” actually going to map to an Activity in a workflow tree? It’s going to work by position. If you change the number of activities in your workflow, or change the workflow’s Activity tree structure in any way, this is going to render all of your Activity IDs worthless.
A note to NativeActivity subclassers: how is position of activities in a workflow determined? It’s determined by the Children collection which you create in CacheMetadata. And by the way, if you’re not overriding CacheMetadata, you probably should be [why here, more or less].
So, is it safe to rely on there being a consistent scheme which maps Activity IDs to Activities? The answer is mostly yes, but the onus on you is to make sure you have the right workflow tree for applying this mapping. Or if you have anything special, such as a wrapper activity which ends up giving you different IDs at runtime and debugging time, you might need to do some fixups.
3 – Actually using an Activity ID to get an Activity
Intuitively the process should be simple, you can guess that this general outline should work:
- Figure out which XAML file the Activity ID is for. Hopefully you saved some data which lets you determine this!
- Load the XAML File. Now you have a root Activity.
- Somehow walk the Activity tree looking for a matching ID.
Sadly there is a bit of devil in the details. (Step 1 is fine, the issues are in 2 and 3.)
The main issue in Step 2 is that for our later requirements of getting XAML line numbers to be met, we will need to load the XAML file in a way which is compatible with SourceLocationProvider.CollectMapping(). As explained in the linked thread, the only way I know of which is actually compatible is calling WorkflowDesigner.Load(string) passing the name of a physical file on disk, and the file should also need the correct XamlDebuggerXmlReader attribute contained in its XAML. If you don’t have such a file available, or it’s missing the attribute a messy workaround to create one is to load your XAML temporarily into a WorkflowDesigner(), and then save it to disk with WorkflowDesigner.Save().
The main issue in Step 3 is that Activities don’t have IDs until the entire workflow tree is known and in some sense ‘prepared to run’. A workflow isn’t prepared to run until the root Activity is known. Consider this example:
Activity i = new If();
Activity s = new Sequence { Activities = { i } };
Which of these 2 activities is the root of the workflow? Trick question, neither! It turns out that the next line of code is
Activity p = new Parallel { Activities = { s } };
and this is followed by WorkflowInvoker.Invoke(p);
The point of this example is to show you that Activities’ location in a Workflow really is not known until the workflow to be run is also known.
The good news, now that I’ve beaten that point to death, is that we don’t actually have to run a workflow using WorkflowInvoker.Invoke in order to prepare it for running in the sense that it will have Activity IDs. And this is where WorkflowInspectionServices come in (if you can still remember the post title).
4 – The rather useful class WorkflowInspectionServices
WIS has two APIs which I would consider using here. Let’s start with number 1:
WorkflowInspectionServices.GetActivities(Activity) – this will give you a list (well, IEnumerable<>) of all the child activities of any workflow in the tree. We could start from the root and work our way down, but why do that when we have API number 2:
WorkflowInspectionServices.Resolve(Activity root, string id) – woohoo! Looks like this actually just straight-up solves the exact problem we were trying to solve, and saves us all the trouble of walking the tree ourselves. Great!
And yes, I believe (but am too lazy to verify right now) that either of these do put the Activity into the ‘nearly runnable’ state where all the metadata is cached, and Activity IDs are fully generated. (Assuming I am right so far, WorkflowInspectionServices.CacheMetadata() probably also has that effect.)
(Aside – you may have inferred from this that good things do not happen if you try to use a single Activity object in more than one workflow simultaneously. Yes indeed.)
5 – Back to visual workflow debugging – nearly done!
Yes, we’re really nearly done. We have the Activity, and the Activity ID. All we need now is a line number… wait… do we even need that? You know, maybe not. For purposes of highlighting an activity, that information could be good enough, if we are willing to write our own Adorner code. But you might want line numbers anyway… for displaying the XAML or something… or utilizing DebugService. The good news is at this point you really should be able to just follow the sample. (Kick up a constructive fuss if it doesn’t work!)
Please use the comments form below if you have questions, bouquets or brickbats!
Tim