B# .NET Blog : .NET Framework 3.0 (WinFX)

.NET Framework Library Source Code now available

bart — Thu, 17 Jan 2008 01:30:00 GMT

That's right - we've published the .NET Framework Library Source Code to the public. Scott Guthrie has the full details. Getting the sources out for the WPF team has been one of my first jobs on the team, which was an interesting experience crawling through the source tree, finding out about build system stuff, and so much more. In technical terms, you now have access to the PDB files over HTTP, as outlined by Shawn Burke over here.

Anyway, enjoy debugging through the BCL sources!

WF - Hello World via the Command Line (wfc.exe explained)

bart — Thu, 07 Dec 2006 22:08:00 GMT

Introduction

A reader of mine noticed I'm using Visual Studio 2005 as the tool to create all of my Windows Workflow Foundation related samples, instead of taking my favorite minimal command-line approach to create basic samples. So here it is today: a simple Hello World demo of WF using the command-line.

Please welcome WFC

Just like csc.exe is the C#'s programmer best friend, wfc.exe plays that role for WF programmers. Basically it turns a .xoml file (which stands for eXtensible Object Markup Language) into a .dll assembly file representing the workflow you've designed. Below you can see a simple demo.xoml file:

This simple sample can be compiled into a .dll file by invoking the following:

>wfc demo.xoml

In this case, we've been using a CDATA section to put the code inline between the XOML definition. Another approach would be to put the following in the demo.xoml file:

and to create another file called demo.cs:

using System;

namespace FooBar
{
   partial class Demo
   {
      void sayHello_ExecuteCode(object sender, EventArgs e)
      {
         Console.WriteLine("Hello World");
      }
   }
}

which can be compiled using:

>wfc demo.xoml demo.cs

Notice the use of the partial keyword in the class definition. In the end, the .xoml file is a partial definition of the workflow class, so the .cs file is another part of it and has to be marked as "partial". Both compilations will yield the same assembly:

Using the assembly in a host application is another concern of course. Basically you just have to compile the following piece of code with a reference to the demo.dll file generated above:

using System;
using System.Threading;
using System.Workflow.Runtime;

namespace FooBar
{
   class Hello
   {
      public static void Main()
      {
         using (WorkflowRuntime workflowRuntime = new WorkflowRuntime())
         {
            AutoResetEvent waitHandle = new AutoResetEvent(false);

            workflowRuntime.WorkflowCompleted += delegate(object sender, WorkflowCompletedEventArgs e)
            {
               waitHandle.Set();
            };

WorkflowInstance instance = workflowRuntime.CreateWorkflow(typeof(FooBar.Demo));
instance.Start();

            waitHandle.WaitOne();
         }
      }
   }
}

which might be a little difficult to add the reference to the System.Workflow assemblies which reside in the GAC. A more convenient demo approach is to merge the host application and the code-behind for the workflow into one single .cs file, like this:

using System;
using System.Threading;
using System.Workflow.Runtime;

            workflowRuntime.WorkflowCompleted += delegate(object sender, WorkflowCompletedEventArgs e)
            {
               waitHandle.Set();
            };

WorkflowInstance instance = workflowRuntime.CreateWorkflow(typeof(FooBar.Demo));
instance.Start();

            waitHandle.WaitOne();
         }
      }
   }

   partial class Demo
   {
      void sayHello_ExecuteCode(object sender, EventArgs e)
      {
         Console.WriteLine("Hello World");
      }
   }
}

Now compile this file (demo.cs) together with the .xoml file, as follows:

>wfc /target:exe /r:System.Xml.dll demo.xoml demo.cs

MsBuild style

There's of course another approach that leans more towards Visual Studio 2005 compilation, i.e. using MsBuild. Assuming you have a file called demo.xoml:

and a file called hello.cs:

using System;
using System.Threading;
using System.Workflow.Runtime;

            workflowRuntime.WorkflowCompleted += delegate(object sender, WorkflowCompletedEventArgs e)
            {
               waitHandle.Set();
            };

WorkflowInstance instance = workflowRuntime.CreateWorkflow(typeof(FooBar.Demo));
instance.Start();

            waitHandle.WaitOne();
         }
      }
   }
}

you can create a .csproj build file that contains this:

<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<RootNamespace>FooBar</RootNamespace>
<AssemblyName>Demo</AssemblyName>
<OutputPath>.</OutputPath>
</PropertyGroup>
<ItemGroup>
<Reference Include="System" />
<Reference Include="System.Xml" />
<Reference Include="System.Workflow.Activities" />
<Reference Include="System.Workflow.ComponentModel" />
<Reference Include="System.Workflow.Runtime" />
</ItemGroup>
<ItemGroup>
<Compile Include="Hello.cs">
<DependentUpon>demo.xoml</DependentUpon>
<SubType>Component</SubType>
</Compile>
</ItemGroup>
<ItemGroup>
<Content Include="demo.xoml"/>
</ItemGroup>
<Import Project="$(MSBuildBinPath)\Microsoft.CSharp.Targets" />
<Import Project="$(MSBuildExtensionsPath)\Microsoft\Windows Workflow Foundation\v3.0\Workflow.Targets" />
</Project>

which can be built using:

>msbuild

Enjoy command-line compiling WF-apps (for demo purposes only I hope)!

WF - Working with events and the ListenActivity

bart — Thu, 19 Oct 2006 09:09:00 GMT

Introduction

This post builds upon the foundation created in yesterday's post about the HandleExternalEventActivity. Please follow the instructions in that post before continuing with this one. As you've learned from this previous post, waiting for an external event to occur is a very powerful mechanism to drive execution of a workflow. There are a lot of scenarios however where you'll want to wait for more than one event at the same time, or you want to timeout such a wait for an event to get raised. To make this kind of dreams reality, WF has the ListenActivity in its magic toolbox.

The demo

Take the solution you built in the previous post on working with events and go to Workflow1.cs's designer view. It should look like this:

Your next job is to transform this into the following:

An easy way to accomplish this is outlined below:

Add a ListenActivity below the WhileActivity.
Rename the left branch of the ListenActivity to clientArrived and the right branch to timeoutOccurred.
Drag and drop the clientArrival and doWork activities from the while loop to the left branch.
Delete the SequenceActivity from the WhileActivity's body.
Drag and drop the ListenActivity to the body of our WhileActivity.
Add a DelayActivity (set to 10 seconds) called timeout to the right branch, as well as a CodeActivity called oops with the following ExecuteCode handler code:

Console.ForegroundColor = ConsoleColor.Cyan;
Console.WriteLine("Oops! Timeout occurred");
Console.ResetColor();

Basically, the ListenActivity blocks till one branch completes. Notice you can add additional branches, e.g. to listen to three, four, ... events at the same time:

When you try to execute this workflow, you'll see timeouts occurring when the client waits to long to enter her name:

I'm sorry for the defaced console output, but hey that's not the goal of the demo is it?

Conclusion

Waiting for one event to occur is a common requirement; waiting for multiple events can be even a more common requirement. WF makes it really easy to do this, without having to mess around with threading and waithandles (even more: in a stateful long-running world relying on additional runtime services like persistence) using the ListenActivity. I bet you'll find yourself leveraging the power of this activity on a regular basis, especially in combination with a DelayActivity to model timeouts. Now you know everything about waiting for events in WF, it's time to wake up yourself and don't wait any longer to explore WF! Cheers!

WF - Handling external events with HandleExternalEvent, External Data Exchange and Local Communications Services

bart — Wed, 18 Oct 2006 08:04:00 GMT

Introduction

In yesterday's post, you learned that the vast majority of workflows need to exchange data with other parties to get their jobs done. Just one of the benefits of workflows is the possibility to visualize this kind of interaction by means of different activities, like the CallExternalMethodActivity that was explained in the previous post. Based on a contract definition (read: interface) a workflow can be defined while the choice of the service implementation is left as a decision for the workflow host application. In today's post, we continue our journey on the Local Communication Services and External Data Exchange path with the HandleExternalEventActivity.

Scenario

The CallExternalMethodActivity explained in the previous post is used to perform methods calls from inside the workflow to some service. Based on an interface and method contract, the workflow can be defined. At runtime, an appropriate service implementation is attached to the workflow and chosen by the engine to process service requests. An example is a workflow calling to an order processing system in some way defined by the contract (e.g. PlaceOrder).

Beside making calls from the workflow to some party outside, one can also rely on the host application to notify the workflow when it needs to do something. This is done using the HandleExternalEventActivity which makes a workflow block till the corresponding event (again in a contract-based manner) is raised by some service. As an example, think of a workflow waiting for approval based on some event (e.g. OrderApproved).

A simple demo

Workflow definition

As usual on this blog, we'll try to keep things simple and approachable, to focus on the basics of the topic discussed. Create a simple Sequential Workflow Console application called EventsDemo:

Next, create the following workflow definition in Workflow1.cs:

This needs some elaboration. On top, we have some CodeActivity called start with the simple ExecuteCode event handler displayed below. At the bottom, there's a similar activity with the event handler shown below as well:

private void start_ExecuteCode(object sender, EventArgs e)
{
   Console.ForegroundColor = ConsoleColor.Green;
   Console.WriteLine("Waiting for clients...");
   Console.ResetColor();
}

private void stop_ExecuteCode(object sender, EventArgs e)
{
   Console.ForegroundColor = ConsoleColor.Red;
   Console.WriteLine("Served 5 clients; time for early retirement!");
   Console.ResetColor();
}

Next, there's an activity called clientListener of the type WhileActivity. This one just loops till five clients have been served, based on the following Declarative Rule Condition:

this.clientCount < 5

relying on the following private variable in the code-behind:

private int clientCount = 0;

A WhileActivity can only contain one single child activity. Because of this, a SequenceActivity is added to the body of the WhileActivity. Inside this SequenceActivity, two child activities are added:

clientArrival is of type HandleExternalEventActivity and will be discussed below shortly
doWork is of type CodeActivity and has the following ExecuteCode event handler:

private void doWork_ExecuteCode(object sender, EventArgs e)
{
   Console.ForegroundColor = ConsoleColor.Yellow;
   Console.WriteLine("Event captured - Hello {0}. You're client number {1}.", args.Name, clientCount);
   Console.ResetColor();
}

The core of the workflow is the HandleExternalEventActivity called clientArrival. This activity works in a similar way as the CallExternalMethodActivity and relies on an interface and in this case an event to wait for. The logical next step is to define this interface (IBar.cs):

using System;
using System.Workflow.Activities;

namespace EventsDemo
{
   [ExternalDataExchange]
   public interface IBar
   {
      event EventHandler<FooEventArgs> Foo;
   }

   [Serializable]
   public class FooEventArgs : ExternalDataEventArgs
   {
      public FooEventArgs(Guid instanceId, string name) : base(instanceId)
      {
         this.name = name;
      }

      private string name;

      public string Name
      {
         get { return name; }
         set { name = value; }
      }
   }
}

Notice the interface definition being annotated with the ExternalDataExchangeAttribute, which is required for workflow to communicate with it using Local Communication Services. Next, the defined event has an event arguments object derived from ExternalDataEventArgs. The constructor of this event arguments object is worth to mention because it requires a base call to one of the base class's constructors that require a workflow instance identifier to be passed on:

public FooEventArgs(Guid instanceId, string name) : base(instanceId)
{

This is required for the workflow runtime to be able to correlate the event with the right workflow instance.

When you've defined the interface with the event, you can continue to set up the HandleExternalEvent activity. Start by setting the InterfaceType to the IBar interface. Next, set the EventName to Foo. In order to capture the event arguments in the workflow instance to d something useful with it in a later stage, you can bind the e parameter (à la EventArgs e) to some local variable:

private FooEventArgs args;

public FooEventArgs Args
{
get { return args; }
set { args = value; }
}

Finally hook up an event handler for the Invoked event of the HandleExternalEvent activity. This will be used to increment the counter that keeps track of the number of served clients (you could do this inside the doWork CodeActivity too):

private void clientArrival_Invoked(object sender, ExternalDataEventArgs e)
{
clientCount++;
}

Notice you could use this event handler too in order to extract information from the event args that were raised with the exception.

Finally, the property grid of the HandleExternalEventActivity clientArrival should look like this:

The host

On to the host side now. What we want to do, is ask the end-user for a name and then raise the event to the workflow instance to indicate a "client arrival". The workflow should then proceed in the WhileActivity loop and perform work for the newly arrived user.

To do this, we'll first implement IBar as follows:

class Bar : IBar
{
   public event EventHandler<FooEventArgs> Foo;

   public void RaiseEvent(Guid instanceId, string name)
   {
      if (Foo != null)
      {
         EventHandler<FooEventArgs> evt = Foo;
         FooEventArgs args = new FooEventArgs(instanceId, name);
         evt(null, args);
      }
   }
}

Next, to establish the communication between the workflow and the "Bar" service, we need to register an ExternalDataExchangeService (from System.Workflow.Activities):

bar = new Bar();
ExternalDataExchangeService svc = new ExternalDataExchangeService();
workflowRuntime.AddService(svc);
svc.AddService(bar);

I've created bar as a local variable in the host class:

private static Bar bar;

Once the workflow instance is started, we'll start a new thread (rather quick-n-dirty) to accept user input till the workflow terminates:

WorkflowInstance instance = workflowRuntime.CreateWorkflow(typeof(EventsDemo.Workflow1));
instance.Start();

Thread userInput = new Thread(UserInput);
userInput.Start(instance.InstanceId);

waitHandle.WaitOne();

userInput.Abort();

That is, the background thread userInput is started with a parameter to indicate the workflow instance to raise events in. When the workflow completes (when waitHandle is set), the background thread is aborted (there exist cleaner ways to implement this idea, but for demo purposes this should be okay). This background thread is defined as follows:

static void UserInput(object instanceId)
{
   for (; ; )
   {
      Thread.Sleep(500); //dirty demo trick
      Console.Write("User name: ");
      string name = Console.ReadLine();
      bar.RaiseEvent((Guid) instanceId, name);
   }
}

The core line of code is indicated in bold and does the real work of notifying the workflow instance of the simulated "client arrival". Don't worry about the Thread.Sleep call which is just there to keep the console output nice and smooth in a very dirty way to keep things simple and clean.

Now run the application, it should produce the following output (enter a few names and see what happens):

Conclusion

Local communication between a workflow and external data services is an absolute must for a lot of workflow scenarios. In this post and the previous post, you learned how to establish this kind of communication with a workflow in both directions, by making method calls and by waiting for events to occur. Enjoy!

WF - Introducing External Data Exchange, the CallExternalMethodActivity and Local Communications Services

bart — Tue, 17 Oct 2006 19:25:00 GMT

Introduction

Workflows don't stand on their own; they need a host application to run in but in a lot of cases there's more: external services are needed to provide functionality to the workflow. You might think, let's just use a CodeActivity to call into some piece of functionality but that doesn't offer enough flexibility in most cases. Okay, you can work with an interface and parameterize the workflow, but still the workflow doesn't reveal its intentions visibly: a CodeActivity is an opaque container where the visualized world of workflows is traded for procedural code again.

Enter the Communication Services, part one. In this post, you'll learn how to exchange data with the workflow by hooking in a "external data exchange service".

CallExternalMethodActivity

At the core of external data exchange is the CallExternalMethodActivity. In a later post, we'll focus on HandleExternalEvent but for now, let's just rely on plain simple method calls. The scenario is the following:

We need a workflow to get the job done (for reasons that may vary a lot, which have been discussed extensively already).
It can't be 100% self-contained and has to rely on external services to process things, for example to make an order.
This external service communication needs a big deal of genericity, so that it can be replaced by an alternative implementation when required. In other words, it needs to be contract-based.

(And no, it isn't a web service we want to call, because in that case we could rely on InvokeWebService.)

Demo

A workflow definition

Right, on to the demo with a somewhat simplified contract: let's call a simple calculator to get things done (I don't want to get the curse of the bad demo gods :-)). Start by creating a simple console-based workflow application:

Next, add a single CallExternalMethodActivity from the toolbox to the workflow definition as shown below:

This is what you should get to see when you set the properties correctly as outlined below. First, go to the code behind of the workflow and add three properties:

private int a;

public int A
{
   get { return a; }
   set { a = value; }
}

private int b;

public int B
{
   get { return b; }
   set { b = value; }
}

private int result;

public int Result
{
   get { return result; }
   set { result = value; }
}

Now, add an interface to the project called ICalculator:

[ExternalDataExchange]
interface ICalculator
{
   int Add(int a, int b);
   int Subtract(int a, int b);
   int Multiply(int a, int b);
   int Divide(int a, int b);
}

Notice the use of the ExternalDataExchangeAttribute, which lives in System.Workflow.Activities. This indicates the interface acts as the contract for external data exchange.

Now go back to the designer and set the CallExternalMethodActivity properties. Start by specifying the InterfaceType:

Next, set the MethodName to Add. Then, set the parameters a, b and (ReturnValue) that appear in the property grid to point to the properties A, B and Result respectively:

If you've done things correctly, this should result in the following:

Right, so now your workflow knows how to transform some input parameters into the corresponding output.

Letting the host know about data services

That's all what's needed for the workflow definition itself. On to the host now (Program.cs). First, we'll parameterize the workflow instantiation as follows:

Dictionary<string, object> parameters = new Dictionary<string, object>();
parameters.Add("A", 1);
parameters.Add("B", 2);

WorkflowInstance instance = workflowRuntime.CreateWorkflow(typeof(ExternalDataDemo.Workflow1), parameters);
instance.Start();

Next, create some class that implements ICalculator. In this case this is very straightforward since we live in the same project as the workflow definition. In reality you'd have to reference the assembly with the interface definition of course. For the sake of the demo, a simple implementation as a nested class inside Program will meet our needs:

class CalculatorService : ICalculator
{
   #region ICalculator Members

   public int Add(int a, int b)
   {
      return a + b;
   }

   public int Subtract(int a, int b)
   {
      return a - b;
   }

   public int Multiply(int a, int b)
   {
      return a * b;
   }

   public int Divide(int a, int b)
   {
      return a / b;
   }

   #endregion
}

Now it's time to hook in this service to the workflow runtime, so that instances can rely on it to get their jobs done. This is done in the Program class again, as follows:

ExternalDataExchangeService edx = new ExternalDataExchangeService();
workflowRuntime.AddService(edx); //keep this order!
edx.AddService(new CalculatorService()); //keep this order!

It's important to keep the order of the last two lines, otherwise you'll end up with an exception. Also, import the System.Workflow.Activities namespace that contains the ExternalDataExchangeService class. This class acts as a container for all external data exchange services, i.e. implementations of interfaces that were annotated with the ExternalDataExchangeAttribute earlier on. You can only have one implementation of each service.

Finally, to get the result back, we'll change the WorkflowCompleted event handler as displayed below:

int res = 0;

AutoResetEvent waitHandle = new AutoResetEvent(false);
workflowRuntime.WorkflowCompleted += delegate(object sender, WorkflowCompletedEventArgs e)
{
res = (int) e.OutputParameters["Result"];
waitHandle.Set();
};

...

In here, res is a variable declared on top of the the Main method which gets printed out at the end of the method:

WorkflowInstance instance = workflowRuntime.CreateWorkflow(typeof(ExternalDataDemo.Workflow1), parameters);
instance.Start();

waitHandle.WaitOne();

Console.WriteLine(res);

The result when executing should be obvious :-).

Conclusion

Exchanging data with external parties should be apparent when looking at the workflow definition. Therefore, one has created the CallExternalMethodActivity to encapsulate such a call for external data. By doing so, external data exchange has the potential to become just yet another service, like tracking and persistence. In the next post, we'll talk about events. Enjoy!

WF - Using the WorkflowMonitor in combination with Dynamic Updates

bart — Mon, 16 Oct 2006 20:15:00 GMT

Introduction

In the past, I've been talking about making a workflow dynamic by applying changes to it at runtime:

Yesterday, you learned how to use tracking (and persistence) services to visualize what's going on inside a workflow in flight, using the WorkflowMonitor sample application that comes with the Windows SDK. Today, we'll combine both the dynamic adaptation of a workflow with tracking services.

Modifying the WorkflowMonitor

As discussed yesterday, the WorkflowMonitor tracks workflows by polling a tracking database used by WF. To visualize what's a workflow keeping itself busy with, it relies on the workflow definition type that gets loaded in the workflow designer that's rehosted by the sample application. However, when making dynamic changes, the WorkflowMonitor doesn't visualize the modifications made to the workflow, because the type doesn't get reloaded. To make things work in a quick-n-dirty fashion, you'll need to change the WorkflowMonitor sample a bit (one line to be precise).

Go to MainForm.cs and locate the method called UpdateActivities. Change the code as follows (only a few lines are displayed, just enough for you to find the spot where modification is needed):

...

ListViewItem currentWorkflow = listViewWorkflows.SelectedItems[0];
if (currentWorkflow != null)
{
   Guid workflowInstanceId = workflowStatusList[(currentWorkflow.SubItems[0]).Text].InstanceId;

   SqlTrackingWorkflowInstance sqlTrackingWorkflowInstance = null;
   if (true == monitorDatabaseServiceValue.TryGetWorkflow(workflowInstanceId, out sqlTrackingWorkflowInstance))
   {
      //Edited by Bart De Smet - 10/05/06
      GetWorkflowDefinition(workflowInstanceId);
      //End edit

      listViewActivities.Items.Clear();
      activityStatusListValue.Clear();

      ...

Dynamic updates

To keep things easy, I'll rely on the results of yesterday's work, so follow those instructions first and make sure the app runs fine. Then go to Workflow1.cs in the TrackingDemoLibrary project and change the ExecuteCode eventhandler for allowAccess like this:

private void allowAccess_ExecuteCode(object sender, EventArgs e)
{
   Console.ForegroundColor = ConsoleColor.Green;
   Console.WriteLine("You're granted access");
   Console.ResetColor();

   WorkflowChanges wc = new WorkflowChanges(this);

   CodeActivity hello = new CodeActivity("hello");
   hello.ExecuteCode += new EventHandler(hello_ExecuteCode);

   IfElseActivity ageChecker = (IfElseActivity)wc.TransientWorkflow.Activities["ageChecker"];
   IfElseBranchActivity plusEighteen = (IfElseBranchActivity)ageChecker.GetActivityByName("plusEighteen");
   plusEighteen.Activities.Add(hello);

   this.ApplyWorkflowChanges(wc);
}

Next, add another delay on top of the workflow, set to 10 seconds. This will give us the opportunity to see the dynamic change happen in the WorkflowMonitor:

Recompile and make sure to re-register the workflow definition assembly in the GAC:

You might need to recreate the tracking database too (that the easy way to clean it when doing demos), as explained in the post on Tracking Services. Just drop the SqlTrackingDatabase, create it again and execute the two .sql scripts.

Now start the adapted (see above) WorkflowMonitor and then start the TrackingDemo solution. Keep an eye on the WorkflowMonitor and see what happens:

The result of the execution looks as follows thanks to dynamic adaptation:

Conclusion

Tracking in a world of dynamic updates is even more interesting and with one simple change to the WorkflowMonitor sample code, one creates a very appealing piece of tracking functionality. Have fun!

WF - Working with Tracking Services

bart — Sun, 15 Oct 2006 10:15:00 GMT

Introduction

In the previous post I've covered the use of persistence services with Windows Workflow Foundation to enable long-running workflows in a reliable way. However, there's still another dark side to long-running workflows that needs a solution: what's happening inside? As you can imagine, a workflow in progress can be blocked waiting for a lot of things, such as the expiration of a timer to indicate a timeout (e.g. by putting a DelayActivity in parallel with another activity using a ParallelActivity) or a wait for an external chunk of data to arrive. In order to visualize what's going on inside, at runtime, the WF Gods created tracking services.

Getting started

Just like persistence services, tracking services rely on some store to put information - in casu tracking information - in. Again, WF comes with a SQL Server enabled service out of the box, called the SqlTrackingService. There's quite a bit to tell about tracking services, but we'll stick with the basics in this post. Nevertheless, a short list of cool things:

Filtering tracking information using tracking profiles
Querying tracked information using SqlTrackingQuery

These might get covered in much more detail somewhere in the future. As usual, in case you have questions, you can contact me too.

Right, on the the real stuff now. To enable tracking services using SQL Server (2000, 2005, MSDE, Express) we need to create a tracking database first. We'll use SQL Server 2005 Express Edition in this post (download here) with SQL Server Management Studio Express installed on the machine:

Connect to the database server:
Create a new database called SqlTrackingDemo:
Now define the database structure and logic required by tracking services, based on two .sql scripts that ship with WF in the %windir%\Microsoft.NET\Framework\v3.0\Windows Workflow Foundation\SQL\EN folder:
Execute (in order) Tracking_Schema.sql and Tracking_Logic.sql, while making sure you've selected the newly created database from step 2:
Finally you should find a bunch of tables and stored procedures in the database (check this).

A tracking-enabled workflow project

A simple solution

Create a new Sequential Workflow Console Application first, called TrackingDemo:

Remove Workflow1 from the Solution Explorer and add a new Sequential Workflow Library project to the solution, called TrackingDemoLibrary:

This step is required because we'll use our workflow definition to visualize tracking information and to do so, the assembly containing the workflow definition will be put in the GAC (as shown later on). Next, add a reference to the TrackingDemoLibrary project in the TrackingDemo (host) project:

In the code of the host application (Program.cs) change the call to CreateWorkflow as follows:

WorkflowInstance instance = workflowRuntime.CreateWorkflow(typeof(TrackingDemoLibrary.Workflow1));

Finally, go the project properties of TrackingDemoLibrary and make the assembly strong-named:

Defining the workflow

Now go to Workflow1 in the TrackingDemoLibrary project. First, parameterize the workflow by adding two properties to the code:

private string firstName;

public string FirstName
{
   get { return firstName; }
   set { firstName = value; }
}

private int age;

public int Age
{
   get { return age; }
   set { age = value; }
}

Now create the following workflow definition:

In here, the IfElseActivity's plusEighteen branch relies on a Declarative Rule Condition defined as follows:

The ExecuteCode event handlers for the different CodeActivity activities are defined like this:

private void welcome_ExecuteCode(object sender, EventArgs e)
{
   Console.WriteLine("Welcome " + firstName);
}

private void allowAccess_ExecuteCode(object sender, EventArgs e)
{
   Console.ForegroundColor = ConsoleColor.Green;
   Console.WriteLine("You're granted access");
   Console.ResetColor();
}

private void denyAccess_ExecuteCode(object sender, EventArgs e)
{
   Console.ForegroundColor = ConsoleColor.Red;
   Console.WriteLine("You're denied access");
   Console.ResetColor();
}

Finally, the delay activities in the workflow were added to simulate long-running operations and have a timeout value set to 10 seconds.

To test things, go to the Program.cs file and change the workflow instance creation code to pass through parameters:

Dictionary<string, object> parameters = new Dictionary<string, object>();
parameters.Add("FirstName", "Bart");
parameters.Add("Age", 23);

WorkflowInstance instance = workflowRuntime.CreateWorkflow(typeof(TrackingDemoLibrary.Workflow1), parameters);
instance.Start();

No magic yet:

Track it

Time to enable tracking. This is done by adding just one single line of code to the host code (Program.cs):

using System.Workflow.Runtime.Tracking;

...

workflowRuntime.AddService(new SqlTrackingService("Data Source=localhost\\SQLEXPRESS;Initial Catalog=SqlTrackingDemo;Integrated Security=SSPI;"));

Now, execute the application once more and then go to the SQL Server Management Studio Express to execute the following query:

use SqlTrackingDemo
exec dbo.GetWorkflows

This will result in something like this (a few columns were hidden in the screenshot):

In here you can see the identifier of the workflow instance as well as information about the workflow type. Other database tables include much more detailed information about the current state the workflow is in, effectively enabling tracking scenarios. Instead of doing low level work with these tables or stored procedures, we'll use a monitor application to see what's going on.

Lights on the WorkflowMonitor

When you install the Windows SDK, a folder with samples is created on the system, typically in %programfiles%\Microsoft SDKs\Windows\v6.0\Samples:

Extract the WFSamples.zip folder to some location on your system. In the Applications\WorkflowMonitor\CS subfolder of the samples, you'll find a WorkflowMonitor application that we'll take a look at now. Open it in Visual Studio 2005.

Now run the application. After a few seconds, the app will crash with the following error message:

This is because we didn't use the default configuration for tracking (i.e. different database name etc). However, we get the opportunity to change the settings right away:

The settings shown above are the valid ones in our case, using SQL Server 2005 Express with the right database name and a polling time of 5 seconds.

When you now try to start the monitoring (using the green "play" button) you'll likely see the following error (or something similar). You might need to restart the application to see the message popping up too:

Basically this means that the WorkflowMonitor is able to get the workflows using GetWorkflows but now tries to load the type specified in the database to visualize the workflows (which may be in flight). For the WorkflowMonitor to find our TrackingDemoLibrary.Workflow1 type, it will need to find the assembly containing the definition. You can either copy the dll file to the bin\Debug (or bin\Release depending on how you're running the WorkflowMonitor sample) folder of the WorkflowMonitor or register the workflow definition in the GAC. We choose the latter one:

Now restart the WorkflowMonitor and you should see something like this:

Notice the mark signs indicate the followed path during execution. It's a very interesting time investment to look at the code of this sample to find out how the workflow information is queried using SqlTrackingQuery. This sample is also interesting because of the designer rehosting used to visualize the workflow in the right-hand side pane. I'll cover designer rehosting some time in the future on this blog too.

Now, run our workflow application again while the monitor is polling the tracking database. Contrary to what you might expect, you won't see a new workflow instance appearing in the list right away. This happens because tracking only performs its job when asked so, e.g. because of a persistence opportunity (this statement is somewhat simplified, check out the docs to get full info on how the system works, related to work batches and so on). As an exercise, try to combine persistence (see previous post) with tracking to track a workflow in progress. You'll end up with a piece of hosting code like this:

workflowRuntime.AddService(
   new SqlWorkflowPersistenceService(
      "Data Source=localhost\\SQLEXPRESS;Initial Catalog=SqlPersistenceDemo;Integrated Security=SSPI;",
      true,
      TimeSpan.FromHours(1.0),
      TimeSpan.FromSeconds(5.0)
   )
);

workflowRuntime.AddService(
   new SqlTrackingService(
      "Data Source=localhost\\SQLEXPRESS;Initial Catalog=SqlTrackingDemo;Integrated Security=SSPI;"
   )
);

Chances are high your app will block or throw an exception. This is because the system needs to connect to the two databases at the same time in a transactional manner. To have this work, you need to start the DTC service on your machine:

Now execute the app again and you should see the following in the monitor:

As you can see, it's now possible to monitor a workflow in flight.

Note: An alternative approach to avoid the DTC problem is to use the - fasten your seatbelts - SharedConnectionWorkflowCommitBatchService service instead of a combination of the tracking service and the persistence service. As the name implies, this one uses a shared connection for both, effectively avoiding distributed transactions and the need for DTC to be enabled and started on the machine. I won't cover this here.

Conclusion

The use of long-running workflows in combination with a lot of services can turn the whole thing in a opaque box without you (and managers) knowing what's going on inside. Tracking services are the window into the internals of workflow instances in all their states, even when in progress. Combining this goodness with things like designer rehosting can open up a lot of great scenarios as shown in the WorkflowMonitor sample.

WF - Working with Persistence Services

bart — Sun, 15 Oct 2006 03:48:00 GMT

Introduction

In the past, I've been writing about WF quite a bit. If you haven't read these articles already, you might find it interesting to check these out first before digging into this one. That being said, this post will focus on persistence services (also known as state persistence services).

Why persistence?

Before we dive deeper in the technical details, let's answer a crucial question: why persistence? As you probably know by now, workflows can be defined (at least partially) as a great tool to visualize either human workflow (e.g. approval processes) or machine workflow (e.g. business integration scenarios). Instead of writing procedural code, one creates a flow diagram or state diagram that represents the underlying logic that gets managed by the workflow runtime and engine. Read my WF introduction post for more information on this.

A common question is why one would prefer to use workflow instead of classic procedural code. There are a lot of answers to the question, one of which relates to the graphical aspect of a workflow that makes it more approachable and easier to understand. Another good answer is the support for scenarios that would end up with a rather high level complexity in procedural code, like parallel execution, data exchange with other components, transactional support, etc. Yet another one - the one that will interest us most - is a set of runtime services available to cope with more complex situations, including persistence services.

Beside the distinction of state workflows and sequential workflows and the distinction between machine workflows and human workflows, one can also draw a line between long-running and non-long-running workflows. It's not atypical (even more, rather typical) for workflows to be long-running. For example, approval processes will require human interaction by one or more parties to continue the workflow execution. Yet another example is a business integration application that waits for external data to arrive. In such a case we say a workflow to be idled. Needless to say, it would be a waste of resources (and even unreliable) to keep state of an idle workflow in memory. That's why we need persistence services.

The basics: getting idle

We'll start by taking a look at a workflow becoming idle. Start by creating a simple sequential workflow:

To force a workflow getting idle, we can use the DelayActivity. So, define the following workflow, containing a DelayActivity with the delay set to 10 seconds:

Next, define the ExecuteCode event handler for both CodeActivity activities as follows:

private void codeActivity1_ExecuteCode(object sender, EventArgs e)
{
   Console.ForegroundColor = ConsoleColor.Green;
   Console.WriteLine("CodeActivity1 speaking");
   Console.ResetColor();
}

private void codeActivity2_ExecuteCode(object sender, EventArgs e)
{
   Console.ForegroundColor = ConsoleColor.Green;
   Console.WriteLine("CodeActivity2 speaking");
   Console.ResetColor();
}

When you launch this workflow application, no surprises will happen. At least not visibly (yet). The workflow will be launched, the "CodeActivity1 speaking" message will be printed out, the workflow will pause for 10 seconds, and then "CodeActivity2 speaking" will appear. Behind the scenes however, the workflow is idled when the delay activity is started. To visualize this, go to the host application's Program.cs file and hook in an event handler for the WorkflowIdled event as show below:

class Program
{
   static void Main(string[] args)
   {
      using(WorkflowRuntime workflowRuntime = new WorkflowRuntime())
      {
         AutoResetEvent waitHandle = new AutoResetEvent(false);
         workflowRuntime.WorkflowCompleted += delegate(object sender, WorkflowCompletedEventArgs e) {waitHandle.Set();};
         workflowRuntime.WorkflowTerminated += delegate(object sender, WorkflowTerminatedEventArgs e)
         {
            Console.WriteLine(e.Exception.Message);
            waitHandle.Set();
         };
         workflowRuntime.WorkflowIdled += new EventHandler<WorkflowEventArgs>(workflowRuntime_WorkflowIdled);

         WorkflowInstance instance = workflowRuntime.CreateWorkflow(typeof(PersistenceDemo.Workflow1));
         instance.Start();

         waitHandle.WaitOne();
      }
   }

   static void workflowRuntime_WorkflowIdled(object sender, WorkflowEventArgs e)
   {
      Console.WriteLine("Idled " + e.WorkflowInstance.InstanceId);
   }
}

Run the application now. It should print the following before it completes (i.e. screenshot taken during the delay activity execution):

How persistence works

When a workflow gets idle, it can be persisted, so that it can be unloaded from memory. A persistence service inherits from the System.Workflow.Hosting.WorkflowPersistenceService base class that's used by the workflow engine to perform persistence. I recommend you to check out this class. Workflow comes with a SQL Server driven persistence service out of the box, defined in System.Workflow.Hosting.SqlWorkflowPersistenceService.

When a workflow gets idle, the system checks in the registered services to find a persistence service, if any. If it finds when, the persistence service gets called to perform the persistence. Next, the system uses the persistence information to find out about the "next timer expiration" to wake up the idled workflow instance when required, so that it can continue its job executing.

Setting up persistence

The first step to set up persistence using SQL Server (2000, MSDE, 2005, Express) is to create the persistence database. In this post, I'll use SQL Server 2005 Express Edition to illustrate the persistence service. You can download the software over here. Don't forget to install SQL Server Management Studio Express too.

Open SQL Server Management Studio Express and connect to the server (typically localhost\SQLEXPRESS):
Next, create a new database called SqlPersistenceDemo, either by invoking CREATE DATABASE or by using the tools:
Now it's time to define the database by executing the WF .sql scripts provided in %windir%\Microsoft.NET\Framework\v3.0\Windows Workflow Foundation\SQL\EN:
First, execute SqlPersistenceService_Schema.sql, then execute SqlPersistenceService_Logic.sql. Make sure to use the right database when you execute the scripts (SqlPersistenceDemo):
You're ready. The persistence database should contain the following tables and sprocs:

Now, we can alter the code to support persistence. This is done in the host application by creating an instance of the SqlWorkflowPersistence class and registering it as a service with the workflow runtime:

workflowRuntime.AddService(
   new SqlWorkflowPersistenceService(
      "Initial Catalog=SqlPersistenceDemo;Data Source=localhost\\SQLEXPRESS;Integrated Security=SSPI;",
      true,
      TimeSpan.FromHours(1.0),
      TimeSpan.FromSeconds(5.0)
   )
);

The first parameter is straightforward and points to the database. In this case I'm using the SQLEXPRESS instance and connecting using windows integrated authentication. The second parameter is called "unloadOnIdle" which unloads the workflow when it's idled. This is the point in time where persistence happens. The third parameter isn't relevant for our elaboration right now and is used when multiple hosts can hydrate/dehydrate workflow instances from the database (it sets the ownership duration for the host, so that if another host tries to load the instance during that interval, it doesn't succeed in doing so and an exception will be thrown). The last parameter specifies the loading interval used to check whether a workflow instance has to be dehydrated (i.e. loaded from the database). We set this value to 5 seconds for the sake of the demo.

Tip: Check out SqlConnectionStringBuilder is you didn't do so yet and you want a more structured approach to create a connection string:

SqlConnectionStringBuilder sb = new SqlConnectionStringBuilder();
sb.IntegratedSecurity = true;
sb.DataSource = "localhost\\SQLEXPRESS";
sb.InitialCatalog = "SqlPersistenceDemo";
string connString = sb.ToString();

Testing it

Time to test. But before we do so, let's hook in another set of event handlers to find out about unload/load/persist events for the workflow:

   workflowRuntime.WorkflowIdled += new EventHandler<WorkflowEventArgs>(workflowRuntime_WorkflowIdled);
   workflowRuntime.WorkflowLoaded += new EventHandler<WorkflowEventArgs>(workflowRuntime_WorkflowLoaded);
   workflowRuntime.WorkflowUnloaded += new EventHandler<WorkflowEventArgs>(workflowRuntime_WorkflowUnloaded);
   workflowRuntime.WorkflowPersisted += new EventHandler<WorkflowEventArgs>(workflowRuntime_WorkflowPersisted);

...

static void workflowRuntime_WorkflowPersisted(object sender, WorkflowEventArgs e)
{
   Console.WriteLine("Persisted {0} on {1}", e.WorkflowInstance.InstanceId, DateTime.Now.ToUniversalTime());
}

static void workflowRuntime_WorkflowUnloaded(object sender, WorkflowEventArgs e)
{
   Console.WriteLine("Unloaded {0} on {1}", e.WorkflowInstance.InstanceId, DateTime.Now.ToUniversalTime());
}

static void workflowRuntime_WorkflowLoaded(object sender, WorkflowEventArgs e)
{
   Console.WriteLine("Loaded {0} on {1}", e.WorkflowInstance.InstanceId, DateTime.Now.ToUniversalTime());
}

static void workflowRuntime_WorkflowIdled(object sender, WorkflowEventArgs e)
{
   Console.WriteLine("Idled {0} on {1}", e.WorkflowInstance.InstanceId, DateTime.Now.ToUniversalTime());
}

Before we press the magic F5 button, there's one more thing to do. Go to SQL Server Management Studio Express and create a new query:

use SqlPersistenceDemo

exec dbo.RetrieveAllInstanceDescriptions
select * from dbo.InstanceState

Basically, the two are almost identical. Generally, I'd recommend to rely on the stored procedures to retrieve information about the workflow instances in progress, but let's just illustrate both:

Now, run the workflow application. You'll see something like this:

As you can see, the idled event is followed by unloading the workflow, thanks to the persistence service (cf. the second "unloadOnIdle" parameter in the constructor call of SqlPersistenceService). Next, when the workflow is unloaded, it's time to persist the workflow instance in the database. While the application is running you have 10 seconds to re-run the query to see this:

If you want to understand how a workflow is persisted, check out the Windows SDK documentation on writing a custom persistence service (search for "Creating Custom Persistence Services"). All of this works using serialization of the runtime workflow instance state.

Finally, the workflow will be reloaded and execution continues:

Notice execution didn't proceed after 10 seconds, but it took 15 seconds instead. The reason for this is the specified loading interval (cf. last parameter to the SqlPersistenceService constructor parameter). Based on this interval, the runtime checks whether a timer has expired amongst the persisted workflow instances.

Tip: Lower the delay's TimeoutDuration to 9 seconds and see what happens. Keep in mind little delays incurred by the runtime to do the persistence when analyzing the results.

Conclusion

In this post, we've seen the basics of the workflow state persistence services. Thanks to this service, long-running workflows can be implemented efficiently without you having to worry much about the persistence itself. In other words, services like persistence services free developers from the burden to cope with error-prone tasks and recurring patterns like implementing persistence. In the next workflow post, I'll focus on the tracking service, so keep an eye on my RSS feed.

.NET Framework 3.0 September CTP

bart — Mon, 25 Sep 2006 05:19:00 GMT

Short no-nonsense post: here it is. Associated tools can be found in the Related Resources section of the page. For the Belgians reading this blog: cu tomorrow in Brussels for the .NET Framework 3.0 event (house fully booked).

Cheers!

Creating a WCF POP3 tunnel - Part 3 - A look on the client-side

bart — Fri, 15 Sep 2006 07:21:00 GMT

Introduction

In the introductory post of this blog series, I explained our mission statement: the creation of a POP3 tunnel over SOAP/HTTP using WCF. The first part of the implementation was covered in part 1 of this blog series: "A simple POP3 client in C#". In part 2 we exposed the POP3 client using a WCF service. In this final episode, we leave the server side and enter the scene of the client, where we need a WCF client as well as a little local POP3 server to capture POP3 commands and translate these into calls to the WCF service. This realizes our SOAP-based and firewall-friendly tunnel.

Where are we?

The diagram below shows the piece of the solution we'll be focusing on in this post:

********************LOCALHOST*******************
*                                              *
* +-------------+              +-------------+ *
* | Mail client | -(TCP:110)-> | POP3 server | *
* +-------------+              +------+------+ *
*                                     |        *
*                              +------+------+ *
*                              | WCF client | *
*                              +------+------+ *
*                                     |        *
**************************************|*********
                                      |
                                (HTTP/SOAP:80)
                                      |
******************TUNNEL SERVER*******|*********
*                                     |        *
* +--------------+             +------+------+ *
* | POP3 client +-----<==-----+ WCF server | *
* +------+-------+             +-------------+ *
*        |                                     *
*********|**************************************
         |
     (TCP:110)
         |
*********|********TARGET SERVER*****************
*        |                                     *
* +------+-------+                             *
* | POP3 server +                             *
* +--------------+                             *
*                                              *
************************************************

Legend:

Gray - External components
Blue - Implemented in previous posts
Red - Covered in this post
Green - To be covered in further posts

A WCF service proxy

On the client-side, we need two things: a POP3 server and a WCF service client. To keep things easy, we'll host these two in a simple Console Application.

If we want to talk to our WCF service, we'll need a service proxy on the client-side. So, let's kick off by generating one using the Visual Studio 2005 built-in support that's added by the .NET Framework 3.0 tool support setup. To do this, go to the Solution Explorer, right click the project node and choose "Add Service Reference" as depicted below:

In order to do this, make sure you're running the WCF service host application we built in part 2. Also make sure the address of the service is spelled correctly to reflect the address you've chosen when implementing the part 2 stuff (normally it should be just fine as it is).

A lightweight POP3 server

Time to start the implementation effort for the POP3 server. This lightweight POP3 server will run on the client's machine and take in all POP3 commands that have to be sent to the real target POP3 server. Instead of having the mail client talk to the target POP3 server directly (e.g. foo.mydomain.local:110) we'll make the mail client talk to localhost:110 instead. The POP3 server on the local machine will then establish a session with the target POP3 server by calling the Connect method first (e.g. Connect("foo.mydomain.local", 110)):

Mail client software connects to localhost:110.
Local POP3 server connects to the WCF service and sends Connect("foo.mydomain.local", 110) - this establishes a session on the WCF service.
WCF service establishes a connection with the target POP3 server "foo.mydomain.local".

From this point on, POP3 commands can flow between the mail client software and the target POP3 server using the HTTP/SOAP tunnel.

Mail client software sends "USER bart" to localhost:110.
Local POP3 server receives the "USER bart" command and parses it in order to make a User("Bart") call on the WCF service.
WCF service rebuilds the original "USER bart" call upon receiving the User("Bart") method call and sends it to the target POP3 server "foo.mydomain.local".

Let's start with the beginning: the class skeleton:

public class Pop3Server
{
   private TcpListener listener;
   private Thread tListener;
   private string url;

   public Pop3Server(int port, string url)
   {
      listener = new TcpListener(IPAddress.Loopback, port);
      this.url = url;
   }
}

Next, add two methods to start and stop the local POP3 server:

public void Start()
{
   listener.Start();
   tListener = new Thread(new ThreadStart(Listen));
   tListener.Start();
}

public void Stop()
{
   tListener.Abort();
   while (tListener.ThreadState != ThreadState.Aborted)
      ;
   listener.Stop();
}

To do this, we just use some quick-n-dirty threading stuff. A cleaner approach can be taken to stop the server more smoothly in order to close communications with the server in a friendly way. However, for demonstration purposes this approach should be okay. Here's the Listen method that acts as the server's background listening thread:

private void Listen()
{
   while (true)
   {
      TcpClient client = listener.AcceptTcpClient();
      new Thread(new ParameterizedThreadStart(StartSession)).Start(client);
   }
}

Basically, this method sits and wait for incoming client connections (i.e. connections made from the mail client software to localhost:110). When a connection is made, a background session thread is started, passing in the TcpClient object as a parameter through the ParameterizedThreadStart delegate (new in .NET 2.0):

private void StartSession(object state)
{
   TcpClient client = state as TcpClient;
   if (client != null)
      new Pop3Session(client).Start();
}

Time has come to start the real work: the Pop3Session class. I've declared this class as a nested private class inside the Pop3Server class. Let's start by examining the class' skeleton:

private class Pop3Session
{
private const string server = "foo.mydomain.local";
private const int port = 110;

   private ASCIIEncoding encoding = new ASCIIEncoding();

   private NetworkStream stream;
   private StreamReader sr;
   private localhost.Pop3TunnelServiceClient svc;

   public Pop3Session(TcpClient client)
   {
      this.stream = client.GetStream();
      this.sr = new StreamReader(stream);

      svc = new localhost.Pop3TunnelServiceClient();
   }
}

Notice that we've hardcoded the target server and port that we want our WCF service session to connect to. In reality, you'll obtain this information through configuration (app.config, the registry, whatever you want) and maybe pass it to the Pop3Session from the Pop3Server upon creation of a session.

Basically, this class has two faces. The first one is the TCP socket one, supported by the stream member. The second one is the WCF client one, supported by the svc proxy instance. As long as the local POP3 session lasts, the WCF service session keeps alive too.

On to the Start method which contains the main loop that waits for commands sent by the local mail client software to the localhost:110 local POP3 server:

public void Start()
{
   string result = svc.Connect(server, port);
   Write(result);

   for (; ; )
      if (!ExecuteCommand(sr.ReadLine()))
         break;

   sr.Close();
   stream.Close();
}

The first thing the Start method does (which is - for the record - called on a separate thread by the Pop3Server's Listen connection listening loop) is connecting to the target server by calling the svc.Connect method. This method starts a WCF session; recall the WCF service contract defined in part 2:

[OperationContract(IsInitiating = true)]
string Connect(string server, int port);

Next, we start to wait for POP3 commands sent by the local mail client. POP3 commands are straightforward to take in because they come in as single-line strings, terminated by a CRLF (\r\n) pair. Therefore, the ReadLine method of the StreamReader attached to the NetworkStream will just do its job fine.

Every command is then forwarded to the ExecuteCommand helper method, defined below:

private bool ExecuteCommand(string command)
{
   if (command == null || command.Length < 3)
   {
      SendError();
      return true;
   }

   string[] cmds = command.Split(' ');
   if (cmds.Length == 0)
   {
      SendError();
      return true;
   }

   switch (cmds[0].ToUpper())
   {
      case "USER":
         if (cmds.Length != 2)
            SendError();
         else
            Write(svc.User(cmds[1]));
         break;
      case "PASS":
         if (cmds.Length != 2)
            SendError();
         else
            Write(svc.Pass(cmds[1]));
         break;
      case "STAT":
         if (cmds.Length != 1)
            SendError();
         else
            Write(svc.Stat());
         break;
      case "LIST":
         if (cmds.Length > 2)
            SendError();
         if (cmds.Length == 1)
            Write(svc.List());
         else
         {
            uint msg;

            if (!uint.TryParse(cmds[1], out msg))
               SendError();
            else
               Write(svc.List2(msg));
         }
         break;
      case "DELE":
         if (cmds.Length != 2)
            SendError();
         else
         {
            uint msg;
            if (!uint.TryParse(cmds[1], out msg))
               SendError();
            else
               Write(svc.Dele(msg));
         }
         break;
      case "RETR":
         if (cmds.Length != 2)
            SendError();
         else
         {
            uint msg;
            if (!uint.TryParse(cmds[1], out msg))
               SendError();
            else
               Write(svc.Retr(msg));
         }
         break;
      case "TOP":
         if (cmds.Length != 3)
            SendError();
         else
         {
            uint msg;
            uint n;
            if (!uint.TryParse(cmds[1], out msg) || !uint.TryParse(cmds[2], out n))
               SendError();
            else
               Write(svc.Top(msg, n));
         }
         break;
      case "QUIT":
         if (cmds.Length != 1)
            SendError();
         else
         {
            Write(svc.Quit());
            return false;
         }
         break;
      case "RSET":
         if (cmds.Length != 1)
            SendError();
         else
            Write(svc.Rset());
         break;
      case "UIDL":
         if (cmds.Length > 2)
            SendError();
         if (cmds.Length == 1)
            Write(svc.Uidl());
         else
         {
            uint msg;
            if (!uint.TryParse(cmds[1], out msg))
               SendError();
            else
               Write(svc.Uidl2(msg));
         }
         break;
      case "APOP":
         if (cmds.Length != 3)
            SendError();
         else
            Write(svc.Apop(cmds[1], cmds[2]));
         break;
   }
   return true;
}

Again, I've omitted all Console.Write* stuff that prints diagnostic information on the screen. This ExecuteCommand method should be very easy to understand. It performs some basic parsing of the command that's received by our local POP3 server and calls the appropriate method on the WCF service through the svc proxy instance. Two helper methods are required:

private void SendError()
{
   Write("-ERR Protocol error.");
}

private void Write(string msg)
{
   string s = msg + "\r\n";
   byte[] b = encoding.GetBytes(s.ToCharArray());
   stream.Write(b, 0, b.Length);
}

As you recall from the service contract, every POP3 equivalent web method takes in all of the parameters required for that command and returns the POP3 response string that was obtained by the target POP3 server. Using the Write method this answer is sent back to the local mail client, with the trailing CRLF pair:

Write(svc.User(cmds[1]));

In order to run this client, we need some simple host code (read: a Main method):

class Program
{
   static void Main(string[] args)
   {
      int port = 110;
      string url = new BdsSoft.Net.Mail.localhost.Pop3TunnelServiceClient().Endpoint.Address.Uri.ToString();

      Console.WriteLine("WCF POP3 Tunnel Client");
      Console.WriteLine("======================");
      Console.WriteLine();

      Console.WriteLine("Initializing local tunnel endpoint...");
      Console.WriteLine("- Local POP3 server listening on TCP port {0}", port);
      Console.WriteLine("- Forwarding to {0}", url);
      Console.WriteLine();

      new Pop3Server(port, url).Start();
      Console.ReadLine();
   }
}

Configuration

Last but not least, our client needs some configuration. The WCF "Add Service Dialog" will have added an app.config file already but it requires some changes, as shown below. These changes are required to deal with large responses, e.g. in response to a RETR POP3 command that retrieves an entire mail message (the default of 16 KB is not sufficient for our purposes). If you decide to implement this stuff for production purposes, you'll want to change the endpoint address to some remote server of course, not just the local machine which we are using for demo purposes (tunnel server and localhost are the same machine).

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
   <system.serviceModel>
      <bindings>
         <wsHttpBinding>
            <binding name="WSHttpBinding_IPop3TunnelService" closeTimeout="00:01:00"
               openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01:00"
               bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard"
               maxBufferPoolSize="524288" maxReceivedMessageSize="2147483647"
               messageEncoding="Text" textEncoding="utf-8" useDefaultWebProxy="true"
               allowCookies="false">
               <readerQuotas maxDepth="32" maxStringContentLength="2147483647" maxArrayLength="16384"
                  maxBytesPerRead="4096" maxNameTableCharCount="16384" />
               <reliableSession ordered="true" inactivityTimeout="00:10:00"
                  enabled="false" />
               <security mode="Message">
                  <transport clientCredentialType="Windows" proxyCredentialType="None"
                     realm="" />
                  <message clientCredentialType="Windows" negotiateServiceCredential="true"
                     algorithmSuite="Default" establishSecurityContext="true" />
               </security>
            </binding>
         </wsHttpBinding>
      </bindings>
      <client>
         <endpoint address="http://localhost:8080/BdsSoft.Net.Mail/Pop3TunnelService"
            binding="wsHttpBinding" bindingConfiguration="WSHttpBinding_IPop3TunnelService"
            contract="BdsSoft.Net.Mail.localhost.IPop3TunnelService" name="WSHttpBinding_IPop3TunnelService">
            <identity>
               <userPrincipalName value="something" />
            </identity>
         </endpoint>
      </client>
   </system.serviceModel>
</configuration>

Take it to the test

Right, let's try it. Make sure the target server and port are set correctly (i.e. to some POP3 server you have a mailbox on) in the Pop3Session class:

private const string server = "foo.mydomain.local";
private const int port = 110;

Next, make sure the WCF service from part 2 is up and running. When the server-side has started, you can launch the client-side tool we've been creating in this episode:

Now configure your mail client software to connect to the local POP3 server (you can set the SMTP server to whatever server you want, we won't send mail for now):

Tip: For testing purposes, I recommend to check the "Leave a copy of messages on server" checkbox, to avoid loosing mail.

You should see some result like this if you add some logging code to the client and server applications (note: the code that's available for download has this kind of logging code):

Download the code

You can download the code for the client-side implementation of the POP3 server and WCF client over here. Make sure to check out part 1 and part 2 of this series to download the associated server-side code.

All usual disclaimers apply. The writer of this blog doesn't make any warranties or guarantuees about the quality of this software, and isn't responsible for possible information loss under any circumstance whatsoever. The code on this blog post and in the download are made available for demonstration purposes only.

Conclusion

Using WCF it's fairly easy to create a HTTP/SOAP tunnel for an older protocol such as POP3. It won't be difficult at all to tunnel protocols like SMTP and IMAP4 too, although every protocol has its own characteristics and implementation complexities. Luckily, POP3 is a pretty simple protocol that allowed me to illustrate you the principle of all this beauty with a relatively small amount of code.

Time to tunnel?