Although WF and therefore workflows run within the process space of the host, the host does not directly interact with a workflow instance. This may seem counterintuitive. After all, if the host application and workflow model are both .NET applications, why the need for an intermediary? The reason is that the WF runtime provides support services. The two main ones it provides are threading and reloading persisted workflows. When you call a workflow, the runtime accesses it for you and handles most threading details. Second, workflows sleep throughout most of their lifetime and are therefore persisted. The runtime receives the call and, if necessary, reloads the workflow and then transmits your request to it. For these reasons, and possibly others, host applications don’t, or at least shouldn’t, communicate directly with workflows.

Figure 4.1 illustrates the WF runtime brokering communication between hosts and workflows.

FIGURE 4.1 General hostworkflow data exchange.

In this hour, we look at one type of host-workflow communication that is commonly referred to as external data exchange or local service. The reason is that this type of communication is conducted by a class that implements an interface that is, in turn, configured with an ExternalDataExchange attribute. There are other host-workflow communication options available in WF, including directly accessing its queuing system (discussed in Hour 22, “Creating Typed Queued and EventDriven-Enabled Activities,” on which all other host-workflow communication schemes are built.

Figure 4.2 offers another view of the local service-based host-workflow data exchange. It shows the host and workflow being mediated by the local service in the middle. The local service contains a contract with a specific set of events and methods to facilitate a particular data exchange. The host raises events to communicate with the workflow, and the workflow invokes methods to communicate with the host. These can be thought of as custom events and methods created for one particular data exchange, such as sending an order to a workflow and waiting for the workflow to announce approval or rejection. These events are in addition to the standard workflow events, such as completed and idled, that are available to all workflows.

FIGURE 4.2 Local service-based host-workflow data exchange.

A Windows Forms application will be used as the host because most developers are familiar with them and they are simple to use. The general concepts, however, apply to just about any other application that hosts a workflow.

There are four steps in host-workflow communication:

A couple of other adjunct steps, such as creating the runtime host and creating dependency properties, are also covered. Some of the headings are prefixed with Step 1, Step 2, and so on to help you know which topics directly relate to implementing local service-based host-workflow communication.

There are three projects in this solution. One will hold the Windows Forms host. Another will hold the local service interface that permits host-workflow communication. The third will hold the workflow that holds the WF local service-based communication activities. Factoring the projects out makes reuse easier.

Creating the Windows Forms Project

Add the Windows Forms host project in the next steps.

1.   Right-click DataExchangeSolution in the Solution Explorer, and select Add, New Project.

2.   Expand the Visual C# project templates and select Windows.

3.   Select the Windows Forms Application project template.

4.   Enter BasicWorkflowHost as the Name.

5.   Enter or browse to C:SamsWf24hrsHoursHour04HostWorkflowDataExchangeDataExchangeSolution for the Location.

6.   Click OK.

7.   Rename Form1.cs to BasicHostForm.cs in the Solution Explorer. Again, click Yes to rename all references.

8.   Right-click the BasicWorkflowHost project in the Solution Explorer, select Add, Add a Reference to both the LocalServiceWorkflows and the LocalService projects.

9.   Add a reference to the workflow trio as well (System.Workflow.Activities, System.Workflow.Runtime, and System.Worfklow.Componentmodel).

10.   Your Solution Explorer should now look like Figure 4.3:

FIGURE 4.3 The DataExchangeSolution in Solution Explorer.

The local service interface contains the contract between the host and the workflow. The local service holds an ExternalDataExchange attribute, the events that will be raised against the workflow by the host, and the methods the workflow will invoke on the host. In the next steps you create a local service interface.

You have now created a local service interface that contains two methods for workflow-to-host communication and one event for host-to-workflow communication. The events raised on the workflow are asynchronous, and the methods from the workflow are synchronous. Communicating with the workflow asynchronously is mandated so that the WF runtime’s threading and reloading services do not take place while the host is waiting for a response to its method call.

All local service-based event payloads are delivered by a class that is derived from ExternalDataEventArgs. Because WF may persist workflows, all event args payload classes (those derived from ExternalDataEventArgs) must be marked as serializable. The workflow instance id must be part of the payload because the WF runtime will need it to determine which workflow instance to route the event to. To ensure this the host must pass the workflow instance id in all events it raises on the workflow, and the event args class must contain the following statement in its constructor: : base(instanceId)

Follow the next steps to create the EventArgs class.

Now it is time to connect the local service interface to the workflow. This is accomplished by using the HandleExternalEvent and CallExternalMethod activities. The HandleExternalEvent activity wraps to the events coming from the host to the workflow. The CallExternalMethod serves the same purpose for workflow-invoked methods on the host. These activities can be wired to any ExternalDataExchange-attributed interface accessible by the workflow project. This means the local service may be within the workflow project itself or in a project referenced by the workflow project. Before adding the communication activities, you will add a couple of properties as described in the next section.

Step 3A: Creating a HandleExternalMethod Activity

Now back to data exchange. Let’s add the HandleExternalEvent activities that receive the events in the next set of steps.

1.   Double click on LocalServiceWorkflow in the solution explorer to open it in design mode.

2.   Drag and drop a HandleExternalEvent activity onto the workflow and name it ReceiveOrder.

3.   Click the InterfaceType property, then click the ellipsis, select LocalService, and then select ILocalService in the middle of the form.

If ILocalService does not show up, make sure the LocalService project is referenced and built. The easiest way is to add a new reference to it from the LocalServiceWorkflows project and build it again.

      Your screen should look like Figure 4.4.

FIGURE 4.4 Local Service selection dialog.

4.   Click OK.

5.   Click the drop-down in the EventName property and select the OrderWorkflowInitialization event.

6.   Enter OrderInvoked in the Invoked property.

7.   Enter the following code in the OrderInvoked handler to retrieve the OrderNumber from the event args.

  // Retrieve the order number from the eventArgs
  OrderNo = (e as LocalService.OrderInitEventArgs).OrderNumber;

8.   Switch back to the workflow designer, and the ReceiveOrder activity property window should look like Figure 4.5.

FIGURE 4.5 The ReceiveOrder activity’s properties.

This activity is now wired to the OrderWorkflowInitialization event and will execute when the event is raised. In addition, the OrderInvoked method will be invoked after the event is raised and will be used to retrieve the OrderNo from the OrderInitEventArgs class.

Adding an IfElse Activity and Rules

In the next steps you will add an IfElse activity and configure its rules.

1.   Drag and drop an IfElse activity onto the workflow below the ReceiveOrder activity.

2.   Name the IfElse activity CheckCredit, name the left branch IsApproved, and name the right branch IsRejected.

3.   Click the red exclamation mark in the left branch, then click Property ‘Condition’ Is Not Set. You will now be into the Condition property ready to input a rule to determine whether this IfElseBranch should execute.

4.   Click the drop-down in the Condition property and select Code Condition.

5.   Click the + at the left of the Condition property, enter CheckOrderCondition in the Condition property, and press Enter.

6.   You are placed in the CheckOrderCondition handler.

7.   Enter the following code in the CheckOrderCondition handler to approve orders ending in 1:

        if (OrderNo.EndsWith("1"))
            e.Result = true;
        else
            e.Result = false;

8.   Switch back to the workflow designer, and your workflow should now look like Figure 4.6.

FIGURE 4.6 Workflow with HandleExternalEvent and IfElse activities.

Adding CallExternalMethod Activities

Step 3B: Add the First CallExternalMethod Activity

This is the activity that will invoke the Approve method that is part of the interface and will be added to the host. From a process standpoint, it will send approval to the host. In the next steps, you add the CallExternalMethod activity to approve the order.

1.   Drag and drop a CallExternalMethod activity into the left IfElse activity branch.

2.   Click the InterfaceType property, then click the ellipsis, select the LocalService, and then select ILocalService in the middle of the form.

3.   Click OK.

4.   Click the drop-down in the MethodName property and select the Approve method.

5.   Enter ApproveIt into the MethodInvoking property (called before the approve method is called; thus it is a good place to perform preparatory work, such as initializing variables).

6.   Enter the following in its code handler:

        Status = "Approved";

7.   Switch back to the workflow designer view.

8.   Bind the OrderNo DependencyProperty to the orderNumber parameter by clicking the orderNumber property, then clicking its ellipsis, selecting OrderNo, and clicking OK.

9.   Bind the Status DependencyProperty to the status parameter by clicking the status property, then clicking its ellipsis, selecting Status, and clicking OK.

10.   Your CallExternalMethod activity property window should now look like Figure 4.7:

FIGURE 4.7 CallExternalMethod activity property window.

Step 3C: Add the Second CallExternalMethod Activity

This is the activity that will invoke the Reject method that is part of the interface and will be added to the host. From a process standpoint it will send rejection to the host. In the next steps you add the CallExternalMethod activity that rejects the order.

1.   Drag and drop a CallExternalMethod activity into the right IfElse activity branch.

2.   Click the InterfaceType property, then click the ellipsis, select the LocalService, and then select ILocalService in the middle of the form.

3.   Click OK.

4.   Click the drop-down in the MethodName property and select the Reject method.

5.   Enter RejectIt in the MethodInvoking property (called before the reject method is called; thus it is a good place to perform preparatory work, such as initializing variables).

6.   Enter the following in its code handler:

         Status = "Rejected";

7.   Switch back to the workflow designer view.

8.   Bind the OrderNo DependencyProperty to the orderNumber parameter by clicking on the orderNumber property, then clicking on its ellipsis, selecting OrderNo, and clicking OK.

9.   Bind the Status DependencyProperty to the status parameter by clicking on the status property, then clicking on its ellipsis, selecting Status, and clicking OK.

10.   Your workflow should now look like Figure 4.8:

FIGURE 4.8 Workflow configured with HandleExternalEvent and CallExternalMethod activities.

11.   Build your LocalServiceWorkflows project and fix compilation errors, if any.

12.   The code in your workflow code-beside file should look like Listing 4.4:

LISTING 4.4 LocalServiceWorkflow Code-Beside File

---

using System;
using System.ComponentModel;
using System.ComponentModel.Design;
using System.Collections;
using System.Drawing;
using System.Workflow.ComponentModel.Compiler;
using System.Workflow.ComponentModel.Serialization;
using System.Workflow.ComponentModel;
using System.Workflow.ComponentModel.Design;
using System.Workflow.Runtime;
using System.Workflow.Activities;
using System.Workflow.Activities.Rules;

namespace LocalServiceWorkflows
{
     public sealed partial class LocalServiceWorkflow: SequentialWorkflowActivity
     {
          public LocalServiceWorkflow( )

          {
               InitializeComponent( );
          }

        public static DependencyProperty OrderNoProperty =
            DependencyProperty.Register("OrderNo",
            typeof(string),
            typeof(LocalServiceWorkflow));

        [DescriptionAttribute("OrderNo")]
        [CategoryAttribute("OrderNo Category")]
        [BrowsableAttribute(true)]

[DesignerSerializationVisibilityAttribute(DesignerSerializationVisibility.Visible
)]

        public string OrderNo
        {
            get
            {
                return
((string)(base.GetValue(LocalServiceWorkflow.OrderNoProperty)));
            }
            set
            {
                base.SetValue(LocalServiceWorkflow.OrderNoProperty, value);
            }
        }

        public static DependencyProperty StatusProperty =
            DependencyProperty.Register("Status",
            typeof(string),
            typeof(LocalServiceWorkflow));

        [DescriptionAttribute("Status")]
        [CategoryAttribute("Status Category")]
        [BrowsableAttribute(true)]

[DesignerSerializationVisibilityAttribute(DesignerSerializationVisibility.Visible
)]

        public string Status
        {
            get
            {
                return
((string)(base.GetValue(LocalServiceWorkflow.StatusProperty)));
            }
            set
            {
                base.SetValue(LocalServiceWorkflow.StatusProperty, value);
            }
        }

        private void OrderInvoked(object sender, ExternalDataEventArgs e)
        {
            // Retreive the order number from the eventArgs
            OrderNo = (e as LocalService.OrderInitEventArgs).OrderNumber;
        }

        private void CheckOrderCondition(object sender, ConditionalEventArgs e)
        {
            if (OrderNo.EndsWith("1"))
                e.Result = true;
            else
                e.Result = false;

        }

        private void ApproveIt(object sender, EventArgs e)
        {
            Status = "Approved";
        }

        private void RejectIt(object sender, EventArgs e)
        {
            Status = "Rejected";
        }
        }
}

---

You will create a Windows Forms application that implements the local service interface you created. It will create the event args payload used by the local service and raise events to the host. Likewise it will act on the methods invoked by the workflow. It will also instantiate the WorkflowRuntime and create and start a WorkflowInstance as you saw in Hour 3, “Learning Basic Hosting.”

Whereas a Console Host application runs sequentially from beginning to end and then terminates, a Windows Forms application remains running until explicitly exited. The main implication of this is that you need to plan where you will instantiate the WorkflowRuntime. You do not want to do this each time an order is submitted. There needs to be only one WF runtime per application that will, in turn, run all the individual workflow instances.

Therefore, we are adding the runtime instantiation to the form load method, which is called only once in our application. For good measure and practice for other hosting scenarios, you first check to see if the runtime has already been instantiated. If so, you return the existing runtime. If not, you create a new runtime.

You also learn to use a new runtime service called the ExternalDataExchangeService. It is a container for one or more local services. You first add the ExternalDataExchangeService to the runtime and then add the local service you created to the ExternalDataExchangeService, as you will see shortly. We will add this service in code, but it can be added though configuration files as you did with the persistence service in Hour 3.

Adding Controls to the Form

In the next steps you add controls to the form.

1.   Create the form in the BasicHostForm.cs designer, as shown in Figure 4.9. (Control names are conveyed in the next task.)

FIGURE 4.9 Basic approval form.

2.   Name the text boxes textBoxOrderNumber and textBoxStatus. Name the command button buttonSubmitOrder. The labels can retain their default names.

Building and Running the Project

The project is rather simple. Entering an order number ending in 1 will result in approval. Any other ending number will conversely result in rejection.

In the next steps, you run the project.

1.   Set the BasicWorkflowHost project as the startup project.

2.   Run the project, enter an order number ending in 1, and you should see results similar to Figure 4.10.

FIGURE 4.10 Approved approval form.

You can now create a simple workflow, build a basic host, and perform mid-flight host-workflow communication. You used local services, event args classes, HandleExternalEvent activities, and CallExternalMethod activities to conduct mid-flight host-workflow communication. You also learned about the DependencyProperty type and hosting the WF runtime in a Windows Forms application. In the next hour you will build on what you learned in an application that supports escalation across multiple forms.