In some scenarios, you may want to save your workflow definitions to images so that you can use them later. For example:

1. Attach them in some document
2. Show them in some web pages to illustrate the definitions of the workflows
3. Etc.

You may have already noticed that you can save the workflow definition to an image by right click on the designer surface and like Copy as Image or Save as Image. However, this is a manual approach. What if I want to write some code to save the images? You may ask.

Good news is, you can do it. Bad news is, you need to write some code, maybe a little bit more than you expected. (If you don’t want read the entire blog, you can find the sample I used here)

“What the hack?” You may wonder. Shouldn’t there be a public API for me to use? Even WF 3.x has that API. Well, it appears to be it should till you get to know why we didn’t provide one. But hanging there. It’s not hard to implement it by yourself. I promise. It will also help you to have a better understanding about how workflow designer works.

Why there is no public API for this?

WF4 workflow designer is written in WPF while WF 3.x workflow designer is written in WinForm. This is a very significant difference. WPF doesn’t support generating an image of the UI when the UI itself has been drawn yet. So in order to save a workflow definition to an image, you need to create and actually make WPF draw the workflow definition in a workflow designer first.

This is the main reason why we didn’t provide any public API for saving as image. Because even if we did, you will only be able to use it after the workflow designer is opened, which is confusing. And it’s hard to imagine Microsoft will release an API in .NET Framework saying “You have to call it after you open the workflow designer UI”. That’s just bad API.

Basic idea of the solution

OK, knowing why we didn’t provide a public API for this. Let’s look at how we are going to achieve the goal by ourselves. At the high level, we need to

1. Create a workflow designer
2. Load the workflow definition which you want to save to an image
3. Make sure the workflow designer is drawn by WPF (basically putting it into a visible UI control)
4. Capture an image of the workflow definition
5. Save the image to a file
6. Close the workflow designer

For the sake of convenience, I won’t show you how to create a rehost workflow designer. Instead, I’ll jump in directly to the “save image” part. You can find a sample of creating rehost workflow designer here.

Let’s try some code

OK, let’s write some code. Following is a code snippet showing the basic idea of a rehost workflow designer.

namespace Microsoft.Samples.DesignerRehosting
{
    public partial class RehostingWfDesigner : Window
    {
        private WorkflowDesigner workflowDesigner;

        public RehostingWfDesigner()
        {
            InitializeComponent();
        }

        protected override void OnInitialized(EventArgs e)
        {
            base.OnInitialized(e);

            // register metadata
            (new DesignerMetadata()).Register();
            // create a big workflow for saving image
            Activity workflow = new Sequence
            {
                Activities = { 
                    new Sequence(), new Sequence(), new Sequence(),
                    new Sequence(), new Sequence(), new Sequence(),
                    new Sequence(), new Sequence(), new Sequence()
                }
            };
            // create the workflow designer and load the workflow
            workflowDesigner = new WorkflowDesigner();
            workflowDesigner.Load(workflow);
            DesignerBorder.Child = workflowDesigner.View;
        }
    }
}

Now let’s look at how to generate an image of the workflow definition using the standard mechanism of WPF. After all, workflow designer canvas is a WPF control.

BitmapFrame CreateWorkflowDefinitionImage()
{
    const double DPI = 96.0;
    // this is the designer area we want to save
    Visual areaToSave = ((DesignerView)VisualTreeHelper.GetChild(
        this.workflowDesigner.View, 0)).RootDesigner;
    // get the size of the targeting area
    Rect size = VisualTreeHelper.GetDescendantBounds(areaToSave);
    RenderTargetBitmap bitmap = new RenderTargetBitmap((int)size.Width, (int)size.Height,
       DPI, DPI, PixelFormats.Pbgra32);
    bitmap.Render(areaToSave);
    return BitmapFrame.Create(bitmap);
}

The above C# method is very straightforward. Just get the workflow diagram part of the workflow designer and create an in-memory image of it using some WPF API. The next thing is simple: create a file and save the image.

void SaveImageToFile(string fileName, BitmapFrame image)
{
    using (FileStream fs = new FileStream(fileName, FileMode.Create))
    {
        BitmapEncoder encoder = new JpegBitmapEncoder();
        encoder.Frames.Add(BitmapFrame.Create(image));
        encoder.Save(fs);
        fs.Close();
    }
}

At last, let’s try to invoke the above 2 methods in the OnInitialized() method to hook it up and then close the application.

protected override void OnInitialized(EventArgs e)
{
    // ...
    this.SaveImageToFile("test.jpg", this.CreateWorkflowDefinitionImage());
    Application.Current.Shutdown();
}

Exception? What the hell?

Run the code to have a try. Wait a sec, exception thrown. What?

After some debugging work, it’s not hard to find that the root cause of this exception is because the size of the UI control we are trying to capture is negative.

Why? This is because although we invoked the above 2 methods to save the image after creating the workflow designer, the workflow designer hasn’t been fully created by WPF yet.

You may know that every WPF UI control has a LayoutUpdated event, meaning the layout has been completed. This sounds like a plan. However, only this is not enough, ‘cause before workflow designer draws the workflow definition completely, the layout will be changed multiple times, which will trigger multiple LayoutUpdated events. In order to solve this issue, we need a Timer.

private Timer timer;
private delegate void TimerDelegate();

protected override void OnInitialized(EventArgs e)
{
    this.timer = new System.Timers.Timer(1000);
    this.timer.AutoReset = false;
    this.timer.Elapsed += new ElapsedEventHandler(CaptureTimer_Elapsed);
    this.timer.Start();
    workflowDesigner.View.LayoutUpdated += new EventHandler(View_LayoutUpdated);
}

void CaptureTimer_Elapsed(object sender, ElapsedEventArgs e)
{
    this.timer.Stop();
    this.timer = null;
    this.workflowDesigner.View.Dispatcher.BeginInvoke(
        System.Windows.Threading.DispatcherPriority.ApplicationIdle,
        (TimerDelegate)delegate()
        {
            this.SaveImageToFile("test.jpg", this.CreateWorkflowDefinitionImage());
            Application.Current.Shutdown();
        });
}

void View_LayoutUpdated(object sender, EventArgs e)
{
    if (this.timer != null)
    {
        this.timer.Stop();
        this.timer.Start();
    }
}

Now let’s try it again. Good! No exceptions any more! Check out the bin\Debug folder. Bam, there it is, test.jpg.

No exception, good. But wait, why I get a uncompleted image?

Now you may think it’s done, which unfortunately is not the case. Open the image and take a look. You will find that the there will be several Sequence activities at the bottom shown as blank box. Why did this happen? (The image should be vertical. I rotated the image here in order to save some space.)

In order to understand this, we need to discuss a advanced mechanism of workflow designer: Virtualization. Imagine you have a huge workflow. When you open it in workflow designer, since the viewport is a fixed size (based on the size of your workflow designer window), it’s a big waste to draw all parts of the workflow since only a small portion will be shown at once. So what virtualization does is delay the drawing of the workflow diagram till when you really need it, which means when you move the viewport to the specific region. This can improve the performance of workflow designer dramatically.

However, it also causes some trouble when you are trying to save an image. Because due to virtualization when you invoke the methods to save the image, the workflow diagram hasn’t been drawn completely yet.

Filling the last piece

So how can we solve this problem? Well, you may notice that there is a Fit to Screen button in workflow designer. The only we need to do is to use this button to show the entire workflow before capturing the image. See the following code.

private bool IsVirtualized = false;

void View_LayoutUpdated(object sender, EventArgs e)
{
    if (!IsVirtualized)
    {
        ((RoutedCommand)DesignerView.FitToScreenCommand).Execute(null,
            this.workflowDesigner.Context.Services.GetService<DesignerView>());
        IsVirtualized = true;
    }
    if (this.timer != null)
    {
        this.timer.Stop();
        this.timer.Start();
    }
}

Now let’s run the project for one last time. Bingo! All the activities have been captured successfully!

Conclusion

I hope this is not too overwhelming to you. Although the code I showed above is not the most intuitive one, but I hope you can understand why we need to write it in this way. Again, we would love to provide a kick-ass API but there are constraints.

You can find the full sample code here. Hope this would help and let me know if you have any questions/feedbacks.

Good news is, the WPF team has already release a hotfix for it. So if you are experiencing bad performance/hang with WF4 workflow designer, I would recommend you to install this hotfix and try again. Although I cannot guarantee it will solve the issue in your case (since the root cause may be different), there is still a good chance that it will help.

You can find the hotfix using either of the links below.

http://archive.msdn.microsoft.com/KB2484841

http://connect.microsoft.com/VisualStudio/Downloads/DownloadDetails.aspx?DownloadID=35604

I would also encourage you to download the following .NET cumulative update patch which includes a bunch of other improvements from WPF and WF4 workflow designer.

http://www.microsoft.com/download/en/details.aspx?id=3556

Have a try and tell us whether it works for you~

Variable

Variables are modeled by Variable class.

    namespace System.Activities

    {  

        public abstract class Variable : LocationReference

        {

            public ActivityWithResult Default { get; set; }

            public string Name { get; set; }

            …

            public object Get(ActivityContext context);       

            public void Set(ActivityContext context, object value);

        }

}

    public sealed class Variable<T> : Variable

    {

        public Activity<T> Default { get; set; }

        …

        public T Get(ActivityContext context);

        public void Set(ActivityContext context, T value);

    }

         Code 15. Variable class definition

The most basic attributes of a variable should be name and type. Name is defined as a property in Variable abstract class; type is captured by generic type argument of Variable<T>, concrete subclass of Variable. Similar to Argument, Variable also has Get()method to get runtime value from ActivityContext, and Set() method for the other way around.

Public and Implementation Variable

So far we could always map WF4’s data model back to similar concept of typical procedural language like C#. There is one exception though when it comes to variables.

In C#, variables are used to share data among statements within a scope (e.g, a method). Those statements are considered private to that scope, so are the variable. It’s natural to think an Activity is a method in WF, and its child Activities as statements of the method. Along this line of thinking, any variable should also be private to its defining Activity and accessible by all child Activities.

But in WF, a lot of Activities are to model control flows and their child Activities are actually given by users of those Activities. For example, Sequence is used to execute a list of child Activities, but those child Activities are not defined by Sequence itself, but injected from outside. The closest concept in C# for this is delegate, so let me try to simulate Sequence Activity with a C# method using delegate:

        static void Sequence(params Action[] statements)

        {

            foreach (Action statement in statements)

            {

                statement();

            }

        }

                  Code 16. simulate Sequence Activity using a C# method

One would call Sequence method like this:

        Sequence(

                ()=>Console.WriteLine("hello"),

                ()=>Console.WriteLine("world!")

                );

                Code 17. calling the C# Sequence method with delegates

As illustrated, from Sequence’s point of view, it’s children activities are actually from outside. In WF term, we call this type of children “public children”, versus “implementation children” which is purely defined by the parent activity itself. When an Activity declares its children Activities in CacheMetadata, it needs to say whether a child is “public” or “implementation” (personally I don’t like the word “public” in this context because it reminds people for the “public” keyword in OO languages but means something totally different).

What if those public child Activities want to share some data? Naturally they should use variables. But those variables could not be defined by the parent Activity since it wouldn’t even know what the public children are, let alone the data they want to share. Again, I could illustrate the idea with C# code:

        static void Sequence(params Action[] statements)

        {           

            //tries to access the variable defined outside the method

            //this does not compile!

            //outside = 5;            

            int inside = 5;

            foreach (Action statement in statements)

            {

                statement();

            }

        }

               //to call the sequence with statements sharing a variable

        int outside = 0;

        Sequence(

                ()=>Console.WriteLine (outside++),

                () => Console.WriteLine(outside++),

                () => Console.WriteLine(outside++),

                () => Console.WriteLine(outside++)

                //tries to access a variable defined inside the method,

                //this does not compile!

                //,() => Console.WriteLine(inside)

                );

                   Code 18. illustrate how "public" children share data using C# code

As we could see, variables used by “public” statements have to be defined outside of method, and not visible to implementation of the method. WF programming model allow such variables to be declared on the parent Activity itself as “public variables”. For example, class Sequence is defined this way:

    public sealed class Sequence : NativeActivity

    {

        public Collection<Activity> Activities { get; }

        public Collection<Variable> Variables { get; }

        …

    }

        Code 19. Sequence Activity interface

The Variables collection holds a list of “public” variables which could be defined by users of Sequence and accessible by its “public” child Activities.

If an Activity needs some bookkeeping data for its own execution, it could declare it as an “implementation” variable and no need to expose it as a public property on the class in general.

Here is an example to demo how to declare public and implementation variables plus difference between them:

    public class MySquence : NativeActivity

    {

        //this is an implementation variable, no need to expose to users

        Variable<int> index = new Variable<int>();  

        //a collection of public child activities for users to fill

        Collection<Activity> activities = new Collection<Activity>();

        public Collection<Activity> Activities

        {

            get { return this.activities; }

        }

        //a collectoin of public variables for users to fill

        Collection<Variable> variables = new Collection<Variable>();

        public Collection<Variable> Variables

        {

            get { return this.variables; }

        }

        protected override void CacheMetadata(NativeActivityMetadata metadata)

        {

            //base.CacheMetadata(metadata);

            foreach (Activity child in this.Activities)

            {

                //declare a public child Activity

                metadata.AddChild(child);

            }

            foreach (Variable variable in this.Variables)

            {

                //declare a public variable

                metadata.AddVariable(variable);

            }

            //declare a implementation variable

            metadata.AddImplementationVariable(this.index);

        }

        protected override void Execute(NativeActivityContext context)

        {

            //store data in the implementation variable

            this.index.Set(context, 0);

            ScheduleNextChild(context);

        }

        void ScheduleNextChild(NativeActivityContext context)

        {

            //access data in the implementation variable

            int nextChildIndex = this.index.Get(context);

            if (nextChildIndex < this.Activities.Count)

            {

                context.ScheduleActivity(this.Activities[nextChildIndex], onChildCompleted);

                this.index.Set(context, nextChildIndex + 1);

            }

        }

        void onChildCompleted(NativeActivityContext context, ActivityInstance instance)

        {

            ScheduleNextChild(context);

        }

    }

         Code 20. A simple implementation of Sequence Activity with both public and implementation variables.

This Activity has a collection of variables for its users to fill and it declare it as public by using “metadata.AddVariable” in CacheMetadata method; it also has a variable to keep track of execution progression, it’s never exposed to the Activity’s users and is declared as implementation by using “metadata.AddImplementationVariable”.

Note that, if base.CacheMatadata is called in CacheMetadata method, the 2 foreach loops are not necessary anymore. Because the base implementation of CacheMetadata reflects all the public properties of the Activity, and automatically declare any public Activity, including Activity in public collections, as its public child; it does similar thing for variables.

Data scoping

With “public” and “implementation” defined, it’s easier to define scoping. In WF4, variables and arguments are all scoped with those rules:

·         An Activity’s arguments and implementation variables could only be accessed by its implementation child Activities

·         An Activity’s public variables could only be accessed by its public child Activities

Hopefully those rules are pretty clear after the explanation in the previous section.

Yun Jin
Development Lead
http://blogs.msdn.com/yunjin

Last year in PDC2009, I ran a chalk talk on our work on WF 4 State Machine Activities and promised the team would ship an implementation for public review after the release of Visual Studio 2010.  Today, I am so excited to let you know that we have delivered it on CodePlex as planned.

This CTP contains a state machine runtime and a graphical state machine designer implementation, and they are optimized to handle event-driven scenarios.   We simplified the runtime object model and enhanced the designer experience so that handling transitions among states should be more intuitive and require fewer clicks or drag-and-drops comparing to WF3. In WF 4, we have also introduced the Flowchart modeling style. State Machine and Flowchart styles are highly complementary. They are suitable for different scenarios. We will talk more about that in future blogs.

So, go ahead to download and install the bits. The user guide is a good starting point.  If you are interested in how it is implemented, you can download the source code. For WF 3 users, you can find the comparison between the state machine in WF3 and this CTP in the user guide.  And the team will continue to blog about different features such as composite states, conditional transition, etc… 

Your feedback is important to us.  We would like to understand more about your State Machine scenarios to build the State Machine right for your business needs.  So, please be encouraged to validate the implementation with your scenarios and let us know how it fits or doesn’t fit your scenarios.

Alan Ko (alanko@microsoft.com)

Program Manager (The WF team)

The WF ADO.NET Activity Pack CTP1 contains a set of WF 4 Activities based on .NET Framework Data Providers. These activities enable accessing a database through SQL commands or stored procedures within a workflow.  You can drag-and-drop the ADO.NET Activities to your designer surface and access the database just like what you can do with ADO.NET. It is a very simple way for you to integrate business data into your workflows.

Click here to download and install the bits, the user guide, and the source code.

The Microsoft WF Team

Argument

We’ve briefly touched this before: in WF4, arguments are modeled by Argument class.

namespace System.Activities

{  

public abstract class Argument

{

    public Type ArgumentType { get; internal set; }       

        public ArgumentDirection Direction { get; internal set; }       

public ActivityWithResult Expression { get; set; }

…

        public object Get(ActivityContext context);

        public void Set(ActivityContext context, object value);

        …

}

}

                 Code 5. Argument class definition

This class has some pretty straightforward properties you’d expect to define an argument like ArgumentType and Direction (In, Out, InOut). Expression is a formula given by Activity caller to tell WF runtime how to evaluate an Argument’s value at execution time, which we will discuss in details later. The most important methods on Argument is Get() and Set(). Get() is to fetch runtime value of an input argument from ActivityContext; similarly, Set() is used to set runtime value of an output argument to ActivityContext.

Look closely, you will find Argument is just an abstract class, so you could not instantiate this class directly. All it does is to provide a common interface for different type of arguments. This is the class diagram for Argument type tree: 

Figure 1. Argument class hierarchy

In the tree, there are 3 more abstract classes with predefined ArgumentDirection: InArgument, OutArgument, and InOutArgument. And then there are 3 concrete classes which allow user to specify ArgumentType using generic type parameter: InArgument<T>, OutArgument<T>, and InOutArgument<T>. Eventually users of an Activity need to assign an argument to instance of one of those classes.

Argument declaration

In C#, developers enclose arguments in a pair of parentheses after method name to “declare” those arguments to C# compiler. In WF, an Activity tree is executed by WF runtime, how would the runtime knows which Activity has defined what arguments?   The answer is that Activity class needs to report its metadata, including arguments and variables, to the runtime using a virtual method CacheMetadata. Here is an example about how this method could be used to declare an argument:

    public class MyWriteLine : CodeActivity

    {

        public InArgument<string> Text

        {

            get;

            set;

        }

        protected override void CacheMetadata(CodeActivityMetadata metadata)

        {

            RuntimeArgument textArgument = new RuntimeArgument("Text", typeof(string), ArgumentDirection.In);

            metadata.Bind(this.Text, textArgument);

            metadata.AddArgument(textArgument);

        }

        …

    }

        Code 6. How to declare one argument on an Activity

What WF runtime needs is really a RuntimeArgument object, the Argument object on Activity is only used to providing binding for the RuntimeArgument.

You may find interesting that MyWrite activity has worked before without overriding CacheMetadata method. The reason is that the method’s default implementation actually queries all public properties of an Activity using .Net reflection. For any property with type Argument, it automatically creates a RuntimeArgument with correct binding. So for most of common cases, an Activity would just work even without declaring arguments in CacheMetadata. However for developers who are sensitive to performance, it might be a good idea to override CacheMetadata to avoid cost of reflection.

A common scenario where explicit argument declaration is required is dynamic argument: an Activity could take a list of arguments whose number and name are not predetermined by the Activity author. For example, if MyWriteLine wants to support formatted output similar to “Console.WriteLine(string format, params Object[] arg)”, it needs to be written this way:

    public class MyWriteLine : CodeActivity

    {

        Collection<InArgument> args = new Collection<InArgument>();

        public InArgument<string> Format

        {

            get;

            set;

        }

        public Collection<InArgument> Args

        {

            get { return this.args; }

        }

        protected override void CacheMetadata(CodeActivityMetadata metadata)

        {

            RuntimeArgument formatArgument = new RuntimeArgument("Format", typeof(string), ArgumentDirection.In);

            metadata.Bind(this.Format, formatArgument);

            metadata.AddArgument(formatArgument);

            for (int i = 0; i < this.Args.Count; i++)

            {

                RuntimeArgument argArgument = new RuntimeArgument("Arg" + i, this.Args[i].ArgumentType, ArgumentDirection.In);

                metadata.Bind(this.Args[i], argArgument);

                metadata.AddArgument(argArgument);

            }

        }

        protected override void Execute(CodeActivityContext context)

        {

            string format = this.Format.Get(context);

            object[] arguments = new object[this.Args.Count];

            for (int i = 0; i < this.Args.Count; i++)

            {

                arguments[i] = this.Args[i].Get(context);

            }

            Console.WriteLine(format, arguments);

        }

    }

        Code 7. How to declare and use dynamic arguments

Base implementation of CacheMetadata would not know how to handle the Args collection, so overriding the method is necessary.

There is a special case for argument definition. If a C# method only has one output, there is no need to declare an out argument. Generally people would just use the return result, which is really a implicit and unnamed output argument.  WF4 uses the same paradigm to simplify programming experience. If an Activity is derived from base class Activity<T>, it will inherit an out argument called “Result”. There is no need to explicitly declare this argument unless CacheMetadata is overridden.

Argument binding and evaluation

In C#, caller of a method could use an expression to define runtime value of an argument to the method. The expression could be a constant value, a variable, a math expression, or any programming structure with a value. For example:

        static void Foo(int x);

        …

        int a = …;

        Foo(5);

        Foo(a);

        Foo(new Random().Next());

                 Code 8. Argument binding in C#

Similarly, in WF, users of an Activity need to provide expressions for its arguments. Activity is the basic unit of WF program.  So an expression in WF is just an Activity which has a return value, a subclass of Activity<T>. WF also defines a base class for Activity<T>, called ActivityWithResult:

    public abstract class ActivityWithResult : Activity

    {

        public OutArgument Result { get; set; }

        public Type ResultType { get; }

    }

        Code 9. ActivityWithResult

As showed before, Argument.Expression is defined as an ActivityWithResult. So client of an Activity needs to bind arguments to some Activities with return result. WF has defined some Activities for common expressions.

·         Literal<T>: models literal value. T could only be string and value types. Sample usage:

MyWriteLine writeLine = new MyWriteLine

            {

                Format = new InArgument<string> { Expression = new Literal<string> ("{0}, {1}")}

            };

                  Code 10. Sample usage of Literal<T>

Argument has constructor to take literal value and create Literal<T> internally, so the code could be simplified as:

        MyWriteLine writeLine = new MyWriteLine

            {

                Format = new InArgument<string>("{0}, {1}")

            };

                Code 11. Sample usage of Literal<T>

·         VariableValue<T>: models accessing value of a variable. Sample usage:

         MyWriteLine writeLine = new MyWriteLine

            {

                Format = new InArgument<string> { Expression = new VariableValue<T>(a)} //a is a WF variable, of type Variable

            };

        Code 12. Sample usage of VariableValue<T>

Argument also has constructor to take Variable and create VariableValue<T> internally, so the code could be simplified as:

        MyWriteLine writeLine = new MyWriteLine

            {

                Format = new InArgument<string>(a) //a is a WF variable, of type Variable

            };

                  Code 13. Sample usage of VariableValue<T>

                To bind a variable to an OutArgument as L-value, one could use VariableReference<T>.

·         VisualBasicValue<T>: models an expression written in VB string. Symbols like WF variable and argument name could be used in the expression string. Sample usage:

MyWriteLine writeLine = new MyWriteLine

            {

                Format = new InArgument<string> { Expression = new VisualBasicValue<string>("a + b")} //a and b are both WF variables

            };

                  Code 14. Sample usage of VisualBasicValue<T>

There is no syntax sugar in Argument class to simplify the code. But WF visual designers have direct support of VisualBasicValue<T> so it’s easy to write expressions as VB language directly in designer.

To bind a VB expression to an OutArgument as L-value, one could use VisualBasicReference<T>.

Developers could always implement their own version of Activity<T> for their own argument binding logic.

When an Activity is scheduled, WF runtime will needs to evaluate expressions of all arguments of this activity before execute the activity. Evaluation process includes scheduling the ActivityWithResult, and getting the out argument Result after it completes. One thing worth mentioning is that runtime schedule all expressions at the same time as if they are in a Parallel Activity, rather than a predefined order like C#.

To be continued…

Yun Jin
Development Lead
http://blogs.msdn.com/yunjin

Argument and Variable 101

WF is just another higher level programming language that share a lot of similarity with popular imperative procedural programming languages. So let’s first take a look at data model of a typical procedural language. Here is a C# code snippet.

        static void Main(string[] args)

        {

            string answer = Prompt("1+1=?");

            Console.WriteLine("Answer is {0}", answer);

            Console.ReadLine();

        }

        static string Prompt(string question)

        {

            Console.WriteLine("Please enter your name:");

            string name = Console.ReadLine();

            Console.WriteLine("{0}, {1}", name, question);

            return Console.ReadLine();

        }

                 Code 1

As we learnt from the first programming class, functions/methods are basic execution unit for procedural languages and the basic mechanism to model data is arguments and variables:

Arguments are to model data flow in/out of a function, like “question” for method Prompt; variables are used to store states which could be shared among multiple statements, like “name” in method Prompt and “answer” in method Main; both arguments and variables are defined by name and type; arguments are always private to a method; variables are visible to the scope where they’re declared (the closest brace which enclose the declaration).

Not surprisingly, WF4 also chooses Argument and Variable to model data flow and internal states for Activities.  And WF’s Arguments/Variables share a lot of those basic characteristics as their C# counterparts. So far the concept of arguments and variables seems to be very simple, now I need to touch something more subtle before talking about WF4’s implementations.

Separation of data and program

Code1 only describes how to manipulate data like “question” and “name”, but doesn’t talk about where the data is stored. In my 32-bit machine with .Net 4.0, the C# code is compiled into this piece of X86 assembly code at runtime:

00000000  push        ebp

00000001  mov         ebp,esp

…

//copy argument “question”from register ecx to stack location [ebp-4]

00000006  mov         dword ptr [ebp-4],ecx

…

//call Console.ReadLine()

00000027  call        5053D5A0

//copy return value of ReadLine from register eax to stack location [ebp-c] as variable “name”

0000002c  mov         dword ptr [ebp-0Ch],eax

//load argument “question”from stack location [ebp-4] and push it to stack

//as the 3^rd argument to WriteLine method call

00000035  push        dword ptr [ebp-4]

//load literal string “{0},{1}”from constant memory location to ecx

//as the 1^st argument to WriteLine

00000038  mov         ecx,dword ptr ds:[03292094h]

//load variable “name”from stack and store in edx as the 2^nd argument to WriteLine

0000003e  mov         edx,dword ptr [ebp-8]

//call Console.WriteLine

00000041  call        5053DBE0

…

Code 2

As I annotated, variables and arguments are saved in stack or registers in a running process. The program does not know location of those variables at compile time, it just reference them with a relative address like “ebp-4 “ (an address calculated by subtracting 4 from value of register “ebp”).  At runtime, register “ebp” will be populated with frame address for this method so variables will automatically be saved into the right place. Abstracting stack and register away, we could say arguments and variables are just names for some locations to a runtime environment; the program does not need to concern the real storage, it just needs to reference those names as if they were the real runtime data.

As Andrew Au pointed out, the design to separating program and data is basic yet critical to today’s programming systems. However, WF 3.X has an architecture where program and data are mixed together. For example, this is a simple activity defined in WF3.X model:

    public class WriteLineActivity : SequenceActivity

    {

        public static DependencyProperty TextProperty = DependencyProperty.Register("Text", typeof(string), typeof(WriteLineActivity));

        public string Text

        {

            get { return (string)base.GetValue(TextProperty); }

            set { base.SetValue(TextProperty, value); }

        }

        protected override ActivityExecutionStatus Execute(ActivityExecutionContext executionContext)

        {

            Console.WriteLine(this.Text);

            return ActivityExecutionStatus.Closed;

        }

    }

       Code 3

The activity defines a property “Text” for its input. There are several problems with this design, including:

·         Data is stored in the program itself. A WriteLineActivity instance is not only execution logic for the activity, but also storage for the activity’s state. That means multiple running instances of the activity could not share the same WriteLineActivity object instance. Actually in WF3, a clone of WriteLineActivity object is created for every WhileActivity iteration and every ParallelActivity branch.

·         There are no way to express intention and scope of the data. It’s hard for users of WriteLineActivity to reason whether “Text” is meant for input, output, or shared state for the activity’s own children. This of course leads to confusion and spaghetti code. Also, the runtime system has hard time to figure out data dependency between the Activities and sometimes could not even cleanup activities when it could otherwise.

In WF4, Activity data model is redesigned, and the number one goal is to create a separation between data and program.

Workflow program, workflow instance, and ActivityContext

In previous section, we analyzed how a C# program code is detached from its running state. The key is to separate the concept of variable/argument as names and their real location at runtime. WF4 does exactly that. Here is a WF4 version of WriteLine:

    public class MyWriteLine : CodeActivity

    {

        public InArgument<string> Text

        {

            get;

            set;

        }

        protected override void Execute(CodeActivityContext context)

        {

            string text = this.Text.Get(context);

            Console.WriteLine(text);

        }

    }

        Code 4

Arguments and variables are modeled by Argument and Variable classes. But the Argument class does not store the argument value itself, same as Variable. When the “Text” argument is defined on MyWriteLine, it only tells users that this Activity has a string input named “Text”, so that users could bind data to this name and the Activity itself could use this name in its internal expressions. But the real data is saved in an ActivityContext class. Every running workflow instance has its own ActivityContext just like every running method has its own frame in call stack. To access its runtime data, the activity needs to use Argument.Get(ActivityContext) to fetch the data out of the context. That way, different running instances could share the same MyWriteLine object instance yet have their own copy of runtime state.

With the separation of program and running instance, we often call an object instance of an Activity class a "Workflow program", similar to a copy of C# program in code. It’s a static description of logic detached with runtime environment; on the other hand, when the Activity object is scheduled by the WF runtime, it creates a "workflow instance", which is more of an abstract concept like the process for a C# program. It encapsulates the program’s runtime state. One WF program could have multiple running WF instances, similiar to relationship of C# program and processes. Workflow runtime use ActivityContext class to keep all states of a running WF instance. Through ActivityContext, an Activity could get its arguments and variables. As we introduced previously, there are different flavor of Activity modeling style with different Activity base classes. Accordingly, WF has defined different flavor of ActivityContext classes which expose different level of runtime functionalities.

 To be continued...

Yun Jin
Development Lead
http://blogs.msdn.com/yunjin

Andrew Au

Continue with our last article, we will work on allowing parallelism and create the workflow/host communication pattern. This pattern is actually very common, such as waiting for multiple approvers to approve a document. Last time we notice the problem is that ScheduleActivity can only be called once, so the most obvious solution is to allow multiple delegates to be put in the states. Looking at states.Frames, it is a stack and we access the top of the stack anytime. With parallelism, we want to have a stack like data structure with multiple tops. Think about it, this is really just a rooted tree. In our data structure, we will keep all the leaves and have parent pointers for the parent frames. With multiple tops, activity execution with a pointer to the set of all states will not work, because the activity doesn’t know which frame it is in. We changed the delegate from Action<State> to Action<Frame> and the rest will become obvious.

Code Sample: Version 8

We are using the old activities because we want to keep safe. No parallelism feature is used in the last sample, we will now introduce parallelism. Parallel is the simplest activity out of the box and we will use parallel to schedule two Reads.

 Code Sample: Version 9

Notice the sequential execution of the work despite of the use of Parallel activity. Parallel activity essentially allows multiple outstanding works. When these work items are waiting for external signals, then these external signals are all waiting together. We used frame as dependencies for delegates, but sometimes delegates are not ready for execution not because of control dependencies, but data dependencies. These data eventually come from the host. From states, we can signal the host to wait for these data, and from the host, those dependencies could be broken when the data is ready. WF3 provided this mechanism though WorkflowQueue, and WF4 provided this through Bookmarks. Queue is sometimes overkill when the program really just request one item.

Code Sample: Version 10

This will be the end of our home made WF series, certainly we still have a long way to go until we get what will have today for workflow foundation. But I guess up to now you should able to appreciate what WF brings to you and how to best leverage WF for your application.

HomeMadeWF.zip

Andrew Au

Continue with our last article, we will work on separating program and data. Program and data are very distinct concepts from the perspective of a programmer. For example, you can run code, but you can’t run data. Code are not expected to be changed during runtime (except some circumstances such as hook or overlay), but data are expected to be changed all the time. From the processor’s perspective, they are no different. They are just some bytes. From an operating system perspective, the fact that code is read only allow optimization of main memory usage, because a single copy of the code can be used to run multiple processes.

Exactly the same argument applies for workflow. We think of Sequence as the program, but then sequenceCounter is just execution data. The fact that sequenceCounter is defined on the Sequence class made them inseparable. Consider multiple workflows are running on the same definition, the sequenceCounter will mix up and cause problem.

Reading the code for Activity, the fact that States is defined on the workflow is an even bigger problem. Instead of having them accessible from the activity as a protected field, we will retrieve it from the parameter of the Execute method. Similarly, we should not allow NextDelegate to be defined on the activity as well. This one is getting more complicated, as Sequence execution will require storage of two delegate objects. To solve this problem, we will use a Stack<Frame> holder for these objects. Diligent readers are recommended to perform the exercise himself, because we are going to take a quantum leap (instead of small refactorings) to move to the next version as shown below

Code Sample: Version 6

I tried to keep modification of Version 6 from Version 5 as small as possible. As we are moving the delegate storage from the activity to state, we also optimized Sequence execution. For now, executing a particular activity will not pass through sequence, but rather just saving the continuation of the sequence in the stack. Given the code is good now, I will refactor. In particular, we will move more logic into States so that the stack is maintained by state instead of being distributed in Sequence and Program. Making Frames a private field drives all these refactorings. All I did is really just giving the right name to the set of operations I did to the states.

Version 7 has no structural change, just encapsulation of the stack.

Code Sample: Version 7

We are getting very close now. For we are now serializing the state object, we should have completed the separation? The answer is NO. This is because the states contain a reference to the delegates, and then the delegates will link back to the program. To break this link, we cannot serialize the delegate anymore. We will serialize the MethodInfo and the activity ID as well, where activity ID can be obtained from a traversal of the activity tree. We will skip this part as this complicates our sample. Another problem is that the program is not constrained to be read only. There are multiple ways of solving it. WF3 chooses to make a copy of the program and always run the copy, while WF4 chooses to make a copy of the program (parts that is important to the runtime) and verify the main program is not modified at runtime. We could have also done by making user fail when program is changed at runtime as well. Again, this complicates the sample and we will stop our discussion here. Trying to implement or reading the existing implementation is a good way to appreciate this.

Another big problem with program and data is that a program line can be executed multiple times in a process. The simplest example is a loop. Those data has to be stored on the frame instead of the state. In fact, all states should be stored on a frame. Storing on States itself make them global variables. With frames, we can control variable scoping. This is one big improvement over the last version of WF.

Look at the implementation of States. One problem is ScheduleActivity can only be called once, because calling a subsequent call to ScheduleActivity will overwrite the NextDelegate field. In this next post, I will talk improve ScheduleActivity to allow multiple outstanding activities, and workflow-host communication through Bookmarks.

HomeMadeWF.zip

Andrew Au

Inspired by the book Essential Windows Workflow Foundation that describes the last version of Workflow Foundation, I can’t stop myself trying to write an equivalent piece for WF4. While the basic working principle is fundamentally the same, the programming model is quite different. We will start from the same principle of using serialization of delegate, and we will develop our ‘home-made’ workflow runtime, and we will see how WF4 made its design decisions.

First of all, let’s review the underlying CLR technology for continuation. Continuation is a point that can be saved for resuming execution, and therefore it needs to contain pointer to executable code. Delegate is used for this purpose. The great thing about delegate can be round-tripped to a binary store and back remain executable. Here is a code sample to show the roundtrip of that delegate works.

Code Sample 1: SerializableDelegate

Serializable delegate provided us with a mechanism to suspend a running managed thread, and resume in another process (perhaps on another machine). Doing so has a lot of advantages. The most important one is that we remove the ‘affinities’. The code is no longer stuck to original process or even the original machine. This allows us to scale the application by simply adding more machines. Moreover, we now have control. For example, we could delete the serialized delegate instead of resuming it. By doing so, we essentially canceled the execution. Similarly, we could suspend the execution for days without worrying main memory are being used. Let us take a look at this code sample to see how serializable delegate allow us to break a program into several processes.

Code Sample: Version 1

Run the program three times, you will see “Hello world to homemade workflow foundation!” is displayed on the console. With the code above, we have just engineered our first most primitive workflow application using the code above. Needless to say, this is rough and there are a lot of things we can improve upon. We will take our first step to separate the concern of scalability (i.e. the fact that we are serializing delegates from the business logic). For that, we create a new class named ReadReadWrite, move the business logic method there, and that leads us to the version 2.

Code Sample: Version 2

First, I put a while loop in the main program to avoid run the program three times. This is really just for convenience. It is good enough for us to know we CAN break them into different processes, but we don’t have to. The refactoring is mostly straightforward, but there is one thing that worth notice here. I made NextDelegate a property of ReadReadWrite. This is to allow all delegates to share a uniform signature.

The hosting program and the business logic are separated now. At this point, we have the still got two coupling between the host and the business logic. The host need to know the starting point is RunStep1, and the host need to know NextDelegate is the property storing the continuation. These coupling make the host not a generic one. We could remove these coupling by having a base class for ReadReadWrite. Let’s call it Activity.

Code Sample: Version 3

The refactoring is straightforward. Looking at ReadReadWrite, the code is now pretty easy to write. One thing that we don’t like is that the Execute method and the RunStep2 method are essentially the same piece of logic to read a file, it is best to share the logic into reusable components. To tackle this problem, we realize there are really two hurdles. One is that they update different states, and that they return different delegates. The fact that they are returning different delegate is a problem, because these delegates are really control logic, and is orthogonal to reading a file. We made them together and therefore the logic not cohesive. Now we further optimize the structure by separating them.

Code Sample: Version 4

It is non-trivial to write the Sequence activity, and it is far from optimal for now. We will postpone the discussion of optimizing Sequence to the next post. For now I want to focus on removing the duplication of Read1 and Read2. With the code above, Read1 and Read2 are really just reading file now. The last step to merge these two classes together is to make them access the state by name instead of a static field reference.

Code Sample: Version 5

Now we have reached a state where we can write reusable activity. These activities don’t have to concern themselves with the serialization. Without reading the code of Main, one does not even know serialization is happening. Looking at Read or Write, does it look like our activities API? In the next post of this series, we will continue to work on this example and show why there is a parameter to the Execute method, and how that separates program from data.

HomeMadeWF.zip