Ron Jacobs

WF4: How To Access Out Arguments

2009-09-25T01:12:30Z

To get a value from your workflow you must access the dictionary of output arguments returned from the workflow.

Note: This example is based on Visual Studio 2010 Beta 2

Consider a workflow that accepts two arguments

Name	Direction	Argument Type
UserName	In	String
Greeting	Out	String

The workflow uses an assign activity to set the result of the expression "Hello " & UserName & " from Workflow 4" to the Greeting out argument. The hosting program can access the Greeting out argument from the dictionary of output values returned from the WorkflowInvoker or WorkflowApplication.

Because the values in the output dictionary are stored as objects with a string as the key, there are three possible outcomes when you try to access an argument value.

The key does not exist in the dictionary
The key exists but the type of the value is not what you expected
The key exists and the type is compatible with what you expected

Whenever you access an out argument you must consider these outcomes. In the event that the key does not exist or the type of the value is not what is expected you may encounter a KeyNotFoundException or InvalidCastException

You can choose to

Let these exceptions propagate possibly terminating the host with an unhandled exception
Catch the exceptions
Code defensively using TryGetValue to access the key from the collection or the C# keyword “as” or VB function TryCast to avoid the invalid cast

Accessing Out Arguments with WorkflowInvoker

The following example shows a method that Invokes the SayHello workflow passing in the UserName and accessing the out argument named “Greeting” after the workflow completes.

Watch Out
This example is not coding defensively or catching exceptions so if the key did not exist or the type of the value was not compatible the exception would propagate to the caller.

C#

private static void GetArgumentsFromWorkflowInvoker()
{
    IDictionary<string, object> output = WorkflowInvoker.Invoke(
        new SayHello() { UserName = "Test" });

    string greeting = (string)output["Greeting"];

    Console.WriteLine("WorkflowInvoker said {0}", greeting);
}

Visual Basic

Shared Sub GetArgumentsFromWorkflowInvoker()
    Dim output As IDictionary(Of String, Object) =
        WorkflowInvoker.Invoke(New SayHello() With {.UserName = "Test"})

    Dim greeting As String = output("Greeting")

    Console.WriteLine("WorkflowInvoker said {0}", greeting)
End Sub

Accessing Out Arguments with WorkflowApplication

WorkflowApplication invokes the workflow on a thread from the CLR threadpool. To capture the outputs you must assign a delegate to the WorkflowApplication.Completed property. Keep in mind that your delegate is called whenever the workflow completes successfully or not. You can check the CompletionState property to find out if the activity closed or faulted. Because accessing the Outputs dictionary may result in an exception you should wrap the access with a try/catch/finally block as shown.

C#

private static void GetArgumentsFromWorkflowApplication()
{
    AutoResetEvent sync = new AutoResetEvent(false);
    string greeting = null;
    Exception argException = null;

    WorkflowApplication wfApp = new WorkflowApplication(
        new SayHello()
        {
            UserName = "Test"
        });

    wfApp.Completed = (e) =>
        {
            // Did the workflow complete without error?
            if (e.CompletionState == ActivityInstanceState.Closed)
            {
                try
                {
                    // Accessing the output arguments dictionary
                    // might throw a KeyNotFoundException or
                    // InvalidCastException                            
                    greeting = (string)e.Outputs["Greeting"];
                }
                catch (Exception ex)
                {
                    argException = ex;
                }
                finally
                {
                    // Must be sure to unblock the main thread
                    sync.Set();
                }
            }
        };

    wfApp.Run();
    sync.WaitOne();

    // Show the exception from the background thread
    if (argException != null)
        Console.WriteLine("WorkflowApplication error {0}", argException.Message);
    else
        Console.WriteLine("WorkflowApplication said {0}", greeting);
}

Visual Basic

Shared Sub GetArgumentsFromWorkflowApplication()
    Dim sync As AutoResetEvent = New AutoResetEvent(False)
    Dim greeting As String = Nothing
    Dim argException As Exception = Nothing
    Dim wfApp As WorkflowApplication =
        New WorkflowApplication(New SayHello() With {.UserName = "Test"})

    wfApp.Completed = Function(args)
                          If (args.CompletionState = 
                                         ActivityInstanceState.Closed) Then
                              Try
                                  ' Accessing the output arguments dictionary
                                  ' might throw a KeyNotFoundException or
                                  ' InvalidCastException                            
                                  greeting = args.Outputs("Greeting")
                              Catch ex As Exception
                                  argException = ex
                              Finally
                                  ' Must be sure to unblock the main thread
                                  sync.Set()
                              End Try
                          End If

                          ' VB requires lambda expressions to return a value
                          Return Nothing
                      End Function

    wfApp.Run()
    sync.WaitOne()

    ' Show the exception from the background thread
    If (argException Is Nothing) Then
        Console.WriteLine("WorkflowApplication said {0}", greeting)
    Else
        Console.WriteLine("WorkflowApplication error {0}", argException.Message)
    End If
End Sub

Accessing Out Arguments with Defensive Coding Style

In this example, we are accessing the Out Argument with a defensive coding style that will insure no exceptions are thrown.

ContainsKey() vs. TryGet()
You should use TryGet instead of ContainsKey() to first check for the key and then Get() to access the key. The reason for this is that you will iterate over the collection twice, once to determine if the key is present and again to access the value.

C#

private static void GetArgumentsFromWorkflowInvokerDefensive()
{
    IDictionary<string, object> output = WorkflowInvoker.Invoke(
        new SayHello() { UserName = "Test" });

    object obj = null;
    string greeting = null;

    if (!output.TryGetValue("Greeting", out obj))
    {
        Console.WriteLine("Greeting not found");
    }
    else
    {
        greeting = obj as string;
        if (greeting == null)
            Console.WriteLine("Greeting could not be converted to a string");
        else
            Console.WriteLine("WorkflowInvoker said {0}", greeting);
    }
}

Visual Basic

Shared Sub GetArgumentsFromWorkflowInvokerDefensive()
    Dim output As IDictionary(Of String, Object) =
        WorkflowInvoker.Invoke(New SayHello() With {.UserName = "Test"})

    Dim obj As Object = Nothing

    Dim greeting As String

    ' TryGetValue will not throw an exception
    If (Not output.TryGetValue("Greeting", obj)) Then
        Console.WriteLine("Greeting not found")
    Else
        ' Not sure what type it is, try to convert it
        greeting = TryCast(obj, String)
        If (greeting Is Nothing) Then
            Console.WriteLine("Greeting could not be converted to a string")
        Else
            Console.WriteLine("WorkflowInvoker said {0}", greeting)
        End If
    End If
End Sub

WF4: Passing Arguments to Activities

2009-09-15T03:49:18Z

In Windows Workflow Foundation .NET 4 (WF4) everything is an Activity. That is a class that inherits from System.Activities.Activity. Activities can have in, out or in/out arguments and do their work then the Activity.Execute() method is called. You could think of them as being similar to a static method except for the fact that a static method can have only 1 return argument where an Activity can have more than one.

Passing arguments to an activity can be done one of two ways. You can use Initialization syntax when creating the activity to set the input arguments (which are just public properties of type InArgument<T>) or you can pass a Dictionary<string, object> which will be used to initialize the arguments.

Passing Arguments with Initialization syntax

        1: [TestMethod]

       2: public void ShouldReturnGreetingWithName()

       3: {

       4:     var output = WorkflowInvoker.Invoke(

       5:         new SayHello()

       6:         {

       7:             UserName = "Test"

       8:         });

       9:     Assert.AreEqual("Hello Test from Workflow 4", output["Greeting"]);

      10: }

This works well except that out arguments (OutArgument<T>) will also show up in the Intellisense window as well as other public properties such as the DisplayName. In this example from the beta 2 release of the “Introduction to Workflow 4” hands on lab (look for it at the PDC) you will see three properties from Intellisense but only one of them is an in argument suitable for initialization.

As you can see initializing an OutArgument looks possible, but if you try it…

What’s going on here? InArgument<T> will implicitly construct from an argument of type T but OutArgument<T> won’t do this so even though it appears like you can do this, you can’t because it won’t compile. But this is a good thing because you shouldn’t initialize an OutArgument anyway.

In practice, I think most people will wrap activity initialization and (possibly) invocation inside of other methods so that developers who are unfamiliar with workflow can just call those methods to do the work.

WCF Essentials – Great Stuff now online

2009-09-10T21:47:36Z

Michelle Leroux Bustamante has written some great new papers for MSDN that you really should check out. They are in the WCF Essentials series.

What I like the most about these articles is that she gives really great practical advice. For example check out this sentence from Getting Started with WCF

“The default is PerSession which is typically not the desired setting.”

Wow – you won’t read that in the MSDN documentation about the InstanceContextMode Enumeration but it is probably something that you should know. It is the kind of advice you can expect from a seasoned WCF developer.

Are you doing WCF Services or SOA in your organization?

If so, I’d like to talk with you about your solution as a part of some research we are doing for future releases. Please contact me through my blog if you would be willing to have a short phone discussion with me about your solution and needs.

Testing a SendMail activity with WF4

2009-09-01T21:00:31Z

Many applications send email. After all it is the preferred binding for async app to human communication. I noticed that many of my colleagues were creating samples that simulate email by dropping a text file into a directory. Then they would open the file and copy and paste a GUID into a form. There is a much better way of course. In the real world people would send an HTML mail with a link that brings you back to the website with the GUID in place.

Nearly everyone has done this with a web site where you register with the site, they send you an email to confirm and then you click a link in the email to complete the registration process. I decided to build out this scenario using a workflow to manage the registration process but then I ran into the issue of how to test the email.

At first I thought I would just use Hotmail. This would work for a demonstration but you have to have network connectivity and verifying that the message arrived would require coding to open the mailbox with POP3 and look for a particular message. Then I found an easier way. You can configure the SmtpClient to drop mail messages into a folder rather than send them.

Of course, many of you will say “Duh! I can’t believe Ron didn’t know about this…”. Well it was news to me so I’m sure that some people didn’t know about it either so here is how it works.

First off, here is the very simple SendMail activity (using .NET 4 Beta 1)

        1: public class SendMail : CodeActivity

       2: {

       3:     public InArgument<string> From { get; set; }

       4:     public InArgument<string> Recipients { get; set; }

       5:     public InArgument<string> Subject { get; set; }

       6:     public InArgument<string> Body { get; set; }

       7:     public InArgument<bool> IsBodyHtml { get; set; }

       8:     protected override void Execute(CodeActivityContext context)

       9:     {

      10:         SmtpClient client = new SmtpClient();

      11:         MailMessage message = new MailMessage(From.Get(context),

      12:             Recipients.Get(context), Subject.Get(context), Body.Get(context));

      13:         message.IsBodyHtml = IsBodyHtml.Get(context);

      14:         client.Send(message);

      15:     }

      16: }

Now I want to test my SendMail class. So I created a Unit Test project and added an app.config file with the necessary configuration magic.

       1: <?xml version="1.0" encoding="utf-8" ?>

       2: <configuration>

       3:   <system.net>

       4:     <mailSettings>

       5:       <smtp deliveryMethod="SpecifiedPickupDirectory">

       6:         <specifiedPickupDirectory pickupDirectoryLocation="c:\maildrop"/>

       7:       </smtp>

       8:     </mailSettings>

       9:   </system.net>

      10: </configuration>

Now all that I need to do is write the test. I want to be sure that when I send a mail that a file ends up in the c:\maildrop directory. The file will have a random GUID as the name. I’m not worried about reading the file to be sure that it contains the correct text. That would be testing the SmtpClient class which I assume works properly.

       1: [TestMethod]

       2: [DeploymentItem("MyActivities.dll")]

       3: public void ShouldSendMail()

       4: {

       5:  

       6:     // Remove all files from the drop location

       7:     if (Directory.Exists(mailDrop))

       8:         Directory.Delete(mailDrop, true);

       9:     Directory.CreateDirectory(mailDrop);

      10:  

      11:     // Create and send the message

      12:     WorkflowInvoker.Invoke(new MyActivities.SendMail()

      13:     {

      14:         From = "test@tempuri.org",

      15:         Recipients = "foo@bar.org, baz@foo.com",

      16:         Subject = "Test HTML message",

      17:         IsBodyHtml = true,

      18:         Body = messageBody

      19:     });

      20:  

      21:     // Find the message in the drop location

      22:     var messages = Directory.EnumerateFiles(mailDrop);

      23:     Assert.AreEqual(1, messages.Count());

      24: }

And the really cool thing is that you can open this file with Windows Live Mail and click the link if you want to demonstrate how it works.

I decided to screencast this code check it out
endpoint.tv Screencast - Spike on Workflow Managed Email Verification

Windows Workflow in .NET 4 and Web Services

2009-07-29T23:33:59Z

Today I published 10-4 episode 29: Workflow Web Services on our Channel 9 10-4 Show about Workflow Services in .NET 4 beta 1.

People have asked me why they would want to implement a web service with a workflow rather than with code using WCF. It is a valid question. Over the next few blog posts I’ll describe some of the reasons why I find workflows a very interesting solution for implementing web services.

Workflows are a simple way to implement web services

Remember the ABC’s of web services with WCF? Every service has an Address, Binding and Contract right? Well it turns out that this isn’t as simple as it sounds. With Workflow services I don’t have to bother so much with the ABC’s. Instead I can focus on a declarative model where I simply create a variable of some type that I want to receive and put it into a receive shape.

Here is a screenshot of a Declarative Sequential Workflow Service in Visual Studio 2010 Beta 1.

This picture is a visualization of XAML that describes a contract. And what is the contract? You can see it from the WCF Test Client

Ok – so the name is a bit ugly but it is just a property of the receive activity easy to change. I have a contract with a method named GetData. And what does the GetData method use as an argument? The value is an Int32, of course because this is a web service message the value might not be included so the WCF Test Client now allows me to use a Nullable<Int32>

And the workflow definition is just a XAMLX file that I can drop on the web server (along with any assemblies it uses) and have a complete working service.

        1: <Service xmlns="http://schemas.microsoft.com/netfx/2009/xaml/servicemodel" xmlns:d="clr-namespace:DeclarativeSequentialServiceLibrary1;assembly=DeclarativeSequentialServiceLibrary1" xmlns:p="http://schemas.microsoft.com/netfx/2009/xaml/activities" xmlns:sad="clr-namespace:System.Activities.Debugger;assembly=System.Activities" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

       2:   <WorkflowServiceImplementation ConfigurationName="Service1" Name="Service1">

       3:     <p:Sequence DisplayName="Sequential Service" sad:XamlDebuggerXmlReader.FileName="c:\scratch\DeclarativeSequentialServiceLibrary1\DeclarativeSequentialServiceLibrary1\Service1.xamlx">

       4:       <p:Sequence.Variables>

       5:         <p:Variable x:TypeArguments="CorrelationHandle" Name="handle" />

       6:         <p:Variable x:TypeArguments="x:Int32" Name="data" />

       7:       </p:Sequence.Variables>

       8:       <Receive x:Name="__ReferenceID0" CanCreateInstance="True" DisplayName="ReceiveRequest" OperationName="GetData" ServiceContractName="Contract1" ValueType="x:Int32">

       9:         <Receive.AdditionalCorrelations>

      10:           <p:InArgument x:TypeArguments="CorrelationHandle" x:Key="ChannelBasedCorrelation">[handle]</p:InArgument>

      11:         </Receive.AdditionalCorrelations>

      12:         <Receive.KnownTypes>

      13:           <x:Type Type="x:Int32" />

      14:         </Receive.KnownTypes>

      15:         <p:OutArgument x:TypeArguments="x:Int32">[data]</p:OutArgument>

      16:       </Receive>

      17:       <d:TraceActivity Message="[String.Format(&quot;Received data {0}&quot;, data)]" />

      18:       <SendReply Request="{x:Reference __ReferenceID0}" DisplayName="SendResponse" ValueType="x:String">

      19:         <p:InArgument x:TypeArguments="x:String">[data.ToString()]</p:InArgument>

      20:       </SendReply>

      21:     </p:Sequence>

      22:   </WorkflowServiceImplementation>

      23: </Service>

This is a pretty cool way to declare a service. If I want to get a little more complex, I can create a type that is received with multiple properties and such. This is exactly what we are doing in the Introduction to Workflow Services lab from the Visual Studio 2010 Training Kit.

Another reason I love Windows 7 - The Network Troubleshooter

2009-07-28T19:46:43Z

After installing the RTM release of Windows 7 I dropped by the office this morning and when I put the laptop on the docking station I fired up the web browser and got… nothing. My PC was acting like it had no network connection even though it was connected both to a wired and wireless connection on the corporate network.

I’ve been through this enough times to know that the issue was probably something to do with the corporate firewall and proxy settings on IE but I decided to test out the Windows 7 Network Troubleshooter.

When people say that Windows 7 is just a minor update to Windows Vista they underestimate the great work the Windows team did on this release. Somebody who doesn’t know the first thing about networking or proxies would have to call the helpdesk to fix this problem but Windows 7 includes troubleshooter “packs” that help you to solve common problems without becoming a networking guru.

First I select the Troubleshoot Internet connections

Notice that this dialog shows a publisher – I assume this means that others can publish troubleshooting packs though I’m not sure what the process is for this. I click next.

Since I’m having trouble connecting to any website I’ll use the first option which will test microsoft.com

After short time I got the problem fixed automatically

The problem was that I forgot to install the ISA firewall client that automatically sets up the proxy settings when I’m on corpnet. I used to do product support many years ago. How I would have loved a tool like this. Way to go Windows 7!

Mocking the Console

2009-06-10T04:21:15Z

I’ve posted an update to the Microsoft.Activities.Simulation library. Today at the team meeting I showed the library to the Windows Workflow team and Ed Pinto said “That is cool!” so I must be doing something right.

Today’s update is a better TestConsole. This time I’ve had the TestConsole redirect the Console output stream by calling Console.SetOut. Now the stream will go into a StringWriter backed by a StringBuilder as the buffer.

        1: StringBuilder _buffer;

       2:  

       3: public TestConsole()

       4: {

       5:     StringWriter outWriter = new StringWriter(_buffer);

       6:     Console.SetOut(outWriter);

       7: }

This way anything that writes to the console will now be captured and therefore it will become testable.

When I want to verify that something was written to the console there are two ways I can do it. I can access the StringBuilder by calling TestConsole.Buffer.ToString() and then look for something in the string.

Or if I prefer a line oriented approach I can do something like this test.

       1: Assert.AreEqual("Scope 1 Number is 1", results.Console.Lines[0]);

Here I have a SimulationResults type with a TestConsole member named Console. I can access a string[] named Lines that will return each line from the TestConsole buffer by calling Regex.Split

       1: public string[] Lines

       2: {

       3:     get

       4:     {

       5:         // Split it only if we need to

       6:         if (Buffer.Length != _lastBufferSplit)

       7:         {

       8:             _lastBufferSplit = Buffer.Length;

       9:             _lines = Regex.Split(Buffer.ToString(), Environment.NewLine);

      10:         }

      11:  

      12:         return _lines;

      13:     }

      14: }

Since splitting the buffer is a little work, I only split it if the length of the buffer has changed since the last time I split it. One side effect of using Regex.Split is that you always get an empty last line. Since the CancellationScope Activity Sample also uses this library I put the library in place and found that I had to update all the unit tests that relied on a line count. If they asserted the count should be 2 I had to change it to 3.

I’ m not enough of a Regex guru to know how to work around this. For now I think it is ok to just say that you will always get one empty line at the end of the array and that is just the way it is.

If you are interested in the Microsoft.Activities.Simulation library, let me know by posting some discussion threads

How to test WF4 Workflows with Microsoft.Activities.Simulation

2009-06-05T19:10:54Z

Recently I posted a new sample for the CancellationScope activity. Of course, I’m building these samples on .NET 4 Beta 1. But the team is already making rapid progress towards the next major milestone. They are checking in changes that may or may not break my sample applications and hands on labs. How will I know if things are broken?

Most people rely on manual testing to detect broken code. The problem is that manual testing is time consuming and expensive. I wanted to find a way to unit and acceptance test the sample applications and labs. There are significant challenges to this but I’ve got some ideas that I think will work and I’m going to describe them to you on my blog as I get them in place.

Unit Testing A Workflow

I’ve covered this on my blog in the past. In fact, the WF4 Hands On Labs (Lab 1) from the Visual Studio 2010 training kit includes unit testing. One issue I did not cover was how to use a Test Double with workflow. Why would you do this? Because some activities do things that are not testable or desirable in a unit test.

The WriteLine activity writes text to the console
A Send activity sends a message to an endpoint that might not be available when testing
A Receive activity requires a message to cause the workflow to continue.

One response to things like this is to use Dependency Injection with Inversion of Control containers to replace these troublesome components with something more testable. The Microsoft patterns & practices group has produced the Unity container for this very purpose.

These solutions do not work with workflow activities because they rely on having some measure of control over the creation of dependencies so they can resolve them at runtime.

Microsoft.Activities.Simulation

I found a way to get around this specifically for workflow. I’m using the term “Simulation” to describe it because in the long run I believe we can build something that would be useful to technical business users for testing workflows. To understand how it works consider the CancellationScope activity sample. If I want to test this sample, how would I do it?

The sample writes data to a console window to show how the cancellation scope allows you to execute activities that will be triggered when a workflow element is cancelled. It uses the System.Activities.Statements.WriteLine activity to do this. So what I need is a way to verify that the correct messages are output by WriteLine in the correct order. What I really wanted to do was to replace WriteLine with another activity I call MockWriteLine.

The strategy I use is to modify the XAML for testing. Consider the following XAML snippet.

        1: <p:CancellationScope DisplayName="Cancellation Scope 1">

       2:     <p:CancellationScope.CancelHandler>

       3:       <p:WriteLine DisplayName="WriteLine Cancel Scope 1">["Cancelling scope 1..."]</p:WriteLine>

       4:     </p:CancellationScope.CancelHandler>

Here you can see the solution staring you in the face. If you could just change <p:WriteLine to <p:MockWriteLine and made the MockWriteLine activity have the same properties as WriteLine then you can do whatever you want from MockWriteLine to make the workflow testable.

Great, but what should MockWriteLine do? I want to capture what it would have written to the console. I need to get data from this activity without modifying the workflow more than I already have. The solution is to use the Test Spy pattern with a workflow extension.

I created a class called TestConsole that will store up the WriteLine output in a buffer that I can verify later. I can then add this extension to the workflow instance.

       1: WorkflowInstance workflowInstance = new WorkflowInstance(wfElement, inputs);

       2: TestConsole testConsole = new TestConsole();

       3:  

       4: // Add the testConsole to the extensions collection

       5: workflowInstance.Extensions.Add(testConsole);

       6:  

       7: // Run the test...

       8: RunTheTest();

       9:  

      10: // Check the first line of the buffer

      11: Assert.AreEqual("Some text to verify", testConsole.Buffer.ElementAt(0));

There is much more to say about this but I’m running out of time. To see it in action, check out the updated version of the CancellationScope Activity Sample.

WF / WCF 4 and “Dublin” Resources

2009-06-03T01:12:27Z

Every now and then somebody will ask me about resources for WF/WCF 4. I usually copy a bunch of links into an email for them. Today I decided I ought to share these resources with all of you. I’ll try to remember and come back to this page and add more as we make more.

Videos

Code / Samples

Questions

CancellationScope Activity

2009-06-01T22:00:46Z

Last Edit: 2-Jun-2009

How do you cancel work in your application? Many middle tier components and services rely on transactions to handle cancellation for them. This makes a great deal of sense because transactional programming is well understood. However there are many times when you must cancel work that cannot be done under a transaction. Cancellation can be very difficult because you have to track work that has been done to know how to cancel it. WF4 also includes compensation activities that can be used to do clean up work as well.

Windows Workflow Foundation 4 helps you with this by providing a CancellationScope activity.

In today’s example I’m going to show you how you can use a cancellation scope to manage cleanup work.

How does cancellation happen?

Before we consider how the CancellationScope, let’s think about how cancellation happens in a workflow. There are 2 ways it can happen, from inside of a workflow or from the outside. Child workflow activities are scheduled by their parent activity (such as a Sequence, Parallel, Flowchart or some custom activity). The parent activity can decide to cancel child activities for any reason. For example, a Parallel activity with three child branches will cancel the remaining child branches whenever it completes a branch and the CompletionCondition expression evaluates to true.

The workflow can also be cancelled from the outside by the host application by calling the Cancel method on the WorkflowInstance.

How does the cancellation scope work?

It’s very simple really, the cancellation scope has a Body. This is where you do the work that you might have to cancel later. The CancelHandler contains the activities you want to run if the activity is canceled.

Does an unhandled exception cause the cancellation handler to be invoked?

No it does not. Unhandled exceptions cause the workflow to abort, cancellation handlers are not invoked.

What if my cancellation handler throws an unhandled exception?

If you have an unhandled exception in the cancellation handler the workflow will immediately terminate with the exception. This is similar to throwing an exception from within a catch block.

Show me a sample

I created some sample code for this blog post that cancels the workflow from the outside. In this example you can observe the behavior of nested cancellation.

When it starts you enter a number between 1 and 3 to determine the number of nested levels you want to call. When you get to the limit of that level the workflow will call a custom activity I created call GoIdle that simply sets a bookmark. This will cause the workflow to become idle and the WorkflowInstance.OnIdle handler will be invoked handing control back to the host.

In program.cs I’ve created two AutoResetEvents, one that will be signaled when the workflow goes idle and another that will be signaled when the workflow completes or terminates with an exception. This is a little unusual but I know that my workflow will go idle when it matches one of the nesting levels 1,2 or 3.

Try It Out

Download the sample code from here. (This sample requires Visual Studio 2010 / .NET 4 Beta 1)

Explore the sample, check out program.cs and Sequence1.xaml
Press Ctrl+F5 to compile and run the sample
When it prompts you for a level try level 1 or 2. You will see that cancellation happens in reverse order of invocation (level 2 cancels before level 1).
To see what happens when you have an unhandled exception thrown in the cancel handler, try level 3.

Ready to learn WF/WCF 4?

2009-05-19T21:02:02Z

Tomorrow Visual Studio 2010 and .NET 4 beta 1 will be available for everyone to download. I’ve been keeping quiet about the work I’ve been up to for the last month and a half while we got some great resources ready for you.

Ok – I let some of this out on endpoint.tv already but now you can get hands on with the technology and learn it yourself.

Download the WF / WCF 4 Hands On Labs

Introduction to Workflow 4

In this lab you will get to know the basics of creating, hosting and running a workflow. This lab is also intended to be an introduction to the new workflow authoring constructs in the .NET Framework 4 and Visual Studio 2010, including the new Workflow Designer, expressions, variables and arguments. Additionally, you will explore the use of some basic built-in activities.

Introduction to Workflow Services using .NET Framework 4

This hands-on lab is intended to introduce developers to writing workflow services using .NET Framework 4. You will examine the different messaging activities of Windows Workflow, and learn how to configure them to create a distributed application. This lab is built around a specific HR business scenario where candidates submit their applications and are hired or rejected based on an evaluation process.

Workflow Designer Programming Model

This hands-on lab introduces you to the designer programming model of Windows Workflow 4. You will learn how to rehost the workflow designer in a WPF desktop application and how to create composite custom designers for your workflow activities.

Creating Flowchart Workflows

This lab is intended to be an introduction to the Flowchart paradigm used in Workflow development. In this lab you will learn how to create Flowchart Workflows using the designer, and you will also learn the usage of several of the provided activities and how to create custom activities easily.

Monitoring Workflow Services using .NET Framework 4

During the life cycle of an application, developers and system administrators often need to monitor running services in order to perform health checks or troubleshoot issues. The Windows Communication Foundation (WCF) and Windows Workflow Foundation (WF) runtimes already come with a built-in tracking infrastructure, making it easy to enable monitoring within your WCF and WF applications. In this hands-on lab you will learn how you can leverage some of the main WF and WCF monitoring features to track application execution and troubleshoot problems with services when necessary.

WCF Service Discovery using .NET Framework 4

Windows Communication Foundation 4 includes a new feature that enables service discovery. Service discovery allows you to locate services on the same subnet using ad hoc discovery, or using a proxy to establish connections with servers regardless of where they are. In this lab you will create a simple chat application that will use both methods to learn about available services.

Configuring a VPC for the REST Starter Kit Hands On Labs

2009-04-04T01:24:47Z

Today I was given a VPC image that someone had started and asked to put the WCF REST Starter Kit Hands On Labs on the image so we can use it at Tech-Ed.

I ran into some interesting problems and I thought I would share the solutions with you in case you run into the same thing.

Problem #1 SQL Server Name

The REST Starter Kit labs assume that the SQL Server is “.\SQLExpress”. Normally this works pretty well since Visual Studio installs this instance. However the image I was working with did not have this server present. They had uninstalled it (since it was SQL Server 2005) and replaced it with a SQL Server 2008 install at (local).

I had two choices now. I could go through all the labs and docs and change the connection strings or… I could use a SQL Alias. If you have never used these, they are way cool. SQL Server allows you to create an alias for a server and that is just what I did.

Now I can refer to the server as (local) or as “.\SQLExpress” which means I don’t have to change any scripts, docs or connection strings.

Problem #2 Default.htm is blank

Every now and then I run into something I had never seen before. When I opened Lab 2, I right clicked on default.htm and selected “View in browser” which promptly launched IE and displayed an empty page. I thought that perhaps I had accidentally deleted the content of the page so I opened it in Visual Studio and the HTML was there and displaying properly in the VS Design Mode editor.

I launched the site in the debugger and refreshed IE several times… no luck. I did View Source and saw that an empty HTML was being returned. Now I was really confused. Then I realized that the IIS7 installation allows you to pick and choose features. Once of those features is “Static Content”. I’ve always selected this option and didn’t know what would happen if I didn’t. Sure enough, this option was not enabled. I had to go into Server Manager (on Windows Server 2008) and enable the feature. No big deal but this sure threw me for a minute.

Problem #3 Network Service login to SQL Server

Now that I have the web page showing, I test and get a security exception. The Network Service account doesn’t have permission to open the database. I’m sure that everybody has run into this a dozen times, I know that every now and then I have to fix up a server like this but it seems like I can never remember the exact way to do it. Fortunately my friends in the patterns & practices team have published a great “How to” document on this called How To: Use the Network Service Account to Access Resources in ASP.NET. This document tells me exactly how to grant access.

And now everything is working great for the people who are going to be at Tech-Ed North America 2009.

Installing Microsoft URL Rewrite Module on Windows 7 Beta

2009-03-27T17:29:06Z

Recently I said that the IIS 7 URL rewrite module will not work on Windows 7. Someone commented on my blog post that there is a workaround posted on the iis.net site. I know the IIS team says this works but I’ve tried it on multiple machines and it never works for me. I have not tried it on Windows Server 2008 R2 so perhaps it works there.

Today on endpoint.tv – The REST Collection Template

2009-03-26T20:42:45Z

One of the more interesting (challenging?) things we did with the WCF REST Starter Kit is the REST Collection Service Template. The idea behind this template was to produce a service that allows you read/write access to a service using a simple REST style interface. The idea is to provide both a contract and base class that takes care of most of the REST-“isms” and you simply override the methods to support your business logic.

And how does this template help?

Provides the URI templates for your service based on a very simple model of a resource per service with an ID parameter
Supports content negotiation with a query string parameter i.e. “?format=json”
Supports HTTP status codes such as 201 – “Created” when you add a new item or 404 – Not Found when you try to update or delete an item that does not exist
Supports append to the collection via POST

What do you think?

One of the reasons we are putting this out to the community in a Codeplex release is that we want to get your constructive feedback. Here is a good starting point. Answer this question

What is wrong with this template?

I’m not tying to sound defensive, I just want to know what you really think.

We know that it isn’t perfect, but if you don’t like it, what do you not like about it? How can we improve it?

The best way to answer these questions is to give it a test drive by running through Lab 3 from the WCF REST Starter Kit Hands On Labs so download and give it a go. You can help us make it better.

RESTful Services and Business Exceptions

2009-03-23T21:33:24Z

Last week I had the privilege of speaking at MIX09. My session RESTful Services for the Programmable Web with Windows Communication Foundation is already available for online viewing (pretty cool how fast they turned that around). This morning I got an email from Francois who saw the session on the web and he had an excellent question.

“I just wanted to know how you deal with business exceptions (concurrency, invalid state transitions, ...) when an update or delete is performed. Do you simply return HTTP error codes? How do you do the equivalent of returning a Soap Fault?”

Great question, to answer it let me first lay some foundation then consider the second part of your question with regard to SOAP faults and finally use some examples to hopefully make this more clear.

REST and HTTP Status Codes

One of the key values of REST is that you are using a universal API known as HTTP. Because of this you must try to understand the way that HTTP wants you to deal with this. And how does HTTP want me to deal with this issue? By using an HTTP Status code.

The first line of an HTTP response is the status line – HTTP clients look to this line to understand the outcome of their request. It isn’t just a matter of errors, there are many different response codes you could return or encounter when invoking RESTful services. (For more information on the Status-Line see the HTTP spec, section 6.1)

       Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF

The status code comes from a long list of codes, according to the spec, the list of codes is extensible but you should follow the model based on the categories of errors

      - 1xx: Informational - Request received, continuing process
      - 2xx: Success - The action was successfully received,
        understood, and accepted
      - 3xx: Redirection - Further action must be taken in order to
        complete the request
      - 4xx: Client Error - The request contains bad syntax or cannot
        be fulfilled
      - 5xx: Server Error - The server failed to fulfill an apparently
        valid request

Even so, I would not go about creating custom HTTP status codes. Instead I would try to use the commonly used status codes listed in section 10 of the HTTP spec.

REST equivalent of SOAP faults

The designers of SOAP had exceptions in mind when they created SOAP faults. Previous distributed computing environments (DCOM, CORBA etc.) did not have a model for propagating exceptions across boundaries. SOAP came along 10+ years after these technologies a time during which exceptions became accepted as a better way of dealing with errors. Many SOAP stacks (WCF being the prime example) will catch an exception, turn it into a SOAP fault and pass it along to the client side which will unpack the message and throw an exception on the client side.

SOAP faults are different than HTTP status codes because they are always errors and there is no taxonomy of errors, just whatever you want them to be. In other words, the “error protocol” is application specific.

In REST HTTP status codes are common and they are not always errors. However the errors do fall into 2 categories 4XX (Client) and 5XX server errors. Now let’s consider some common scenarios where you must deal with errors and status codes.

Error Scenarios

The first class of errors you must consider are (4XX) client request errors. Generally it means that the server rejected the request for some reason.

Get or Update record that does not exist

Client does an HTTP GET for a resource ID that does not exist in the database. On the server you might call into the data layer to update a record an get a KeyNotFoundException (like I did in the video). What happens if you do nothing? Well WCF will catch all unhandled exceptions and return a status code of 500 - “Internal Server Error”. This is not what you want, because it implies that the problem is a server problem.

In this case you should return a HTTP status code of ~~400~~ 404 “Not Found” (edit – 3/25 – thanks Clemens!)

10.4.1 400 Bad Request

The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

Here is some code that processes a GET request by looking it up in a dictionary. This is the fixed version of what I showed in the video. As you can see I’m converting an exception into a status code by throwing a WebProtocolException.

[OperationContract]
[WebGet(UriTemplate = "/{id}")]
SessionData GetSession(string id)
{
    try
    {
        return _sessions[id];
    }
    catch (KeyNotFoundException)
    {
        throw new WebProtocolException(
            HttpStatusCode.NotFound);
    }
}

Add a resource with missing or invalid data

Client does an HTTP POST with missing or invalid data in the request body. The server attempts to validate the request and rejects it because of the invalid or missing data. The HTTP status code should be 400 – Bad request

Server Processing Errors

Suppose that the request is valid, the resource exists and for whatever reason (concurrency or some other processing error) the server cannot complete the request. Then what?

10.5 Server Error 5xx

Response status codes beginning with the digit "5" indicate cases in which the server is aware that it has erred or is incapable of performing the request. Except when responding to a HEAD request, the server SHOULD include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. User agents SHOULD display any included entity to the user. These response codes are applicable to any request method.

You should return a HTTP status code of 500 along with some text to let the user know what is happening (if you want to). Here is an example of code that would do this kind of processing.

[OperationContract]
[WebInvoke(Method = "PUT", UriTemplate = "/{id}")]
SessionData UpdateSession(string id, SessionData updatedSession)
{
    try
    {
        if (!_sessions.Contains(updatedSession.ID))
            throw new WebProtocolException(HttpStatusCode.BadRequest);
        if (!_sessions.IsValidSession(updatedSession))
            throw new WebProtocolException(HttpStatusCode.BadRequest);
        return _sessions.Update(updatedSession);
    }
    catch (TimeoutException)
    {
        throw new WebProtocolException(HttpStatusCode.InternalServerError,"Update session timeout",null);
    }
}

WebProtocolException does provide mechanisms for passing more detail in a SOAP Fault like way as a part of the HTTP response body. Sounds like a good topic for my next post.