Using Correlation in Workflows

Article
10/14/2009

The Windows Workflow Foundation runtime engine uses correlation to map an inbound message with a specific HandleExternalEventActivity activity in a workflow instance. The mapping to the instance is done when the workflow instance InstanceId is passed to the ExternalDataEventArgs constructor.

You define a correlation by using interface attributes. The Windows Workflow Foundation workflow communication services interface can specify additional metadata for correlation. This correlation data is required to correlate an event activity for a workflow instance. The correlation metadata specification takes the form of an attribute on the interface, the CorrelationParameterAttribute attribute.

Note

Providing correlation attributes for communication interfaces is optional. By default, communication interfaces are uncorrelated. Users should only add correlation attributes if they need correlation to deliver a message to a specific activity instance.

Interface Attributes

The following table describes the full set of interface attributes that can be used in definitions of interfaces that are consumable by the Windows Workflow Foundation workflow communication services.

Attribute	Description
CorrelationParameterAttribute	Used to specify the name of a parameter that is used in the methods and events defined in the interface and used for correlation. If a method or event contains a formal parameter that matches the name, that parameter defines the correlation value on that method or event. If the method or event has no such parameter, the method or event can define the location of the correlation value using a CorrelationAliasAttribute. This attribute can appear more than once on an interface.
CorrelationInitializerAttribute	Used on a method or event to indicate that the value of the correlation parameter is initialized when that method is invoked or the event is raised. For a given CorrelationToken, an initializer method or event must be invoked or received before any other method or event in the conversation executes. Any method or event that might initialize a new conversation, that is, new correlation tokens, must be marked with this attribute. The method or event must contain either an appropriately named parameter, or a CorrelationAliasAttribute, for each correlation token.
CorrelationAliasAttribute	Used on the method or event definition to override the CorrelationParameter setting for that member. The CorrelationAliasAttribute attribute specifies the location in the available parameters from which the correlation value is obtained. The string parameter is a dotted path over the formal parameter set. It indicates where the matching data value can be found. If there is more than one correlation token defined, the token Name named parameter must also be specified.

Using Correlation Attributes

CorrelationParameterAttribute names the conversation identifier, correlation. Each method or event on the interface is then declared with a formal parameter of that name, for example, id, as shown in the following ITaskService interface code example. You can also use other attributes to describe more complex correlation mapping. After the instance and correlation information is known for a conversation, the class raises its local service events. It specifies the correlation in the parameter data on the call.

The following code example shows a workflow communication services correlated interface definition, ITaskService.

    [Serializable]
    public class TaskEventArgs : ExternalDataEventArgs
    {
        private string id;

        public TaskEventArgs(Guid instanceId,string id)
            :base(instanceId)
        {
            this.id = id;
        }

        public string Id
        {
            get { return id; }
            set { id = value; }
        }
    }

    [ExternalDataExchange]
    [CorrelationParameter("taskId")]
    public interface ITaskService
    {
        [CorrelationInitializer]
        void CreateTask(string taskId, string assignee, string text);

        [CorrelationAlias("taskId", "e.Id")]
        event EventHandler<TaskEventArgs> TaskCompleted;
    }

Any operation, method, or event that starts a new conversation must be attributed with the CorrelationInitializerAttribute. If a call occurs to a CorrelationInitializerAttribute method m, the service class knows that a new conversation is being initialized with this call. The workflow conversation lifetime is dictated by the lifetime of the correlation reference. A workflow can unload and load between conversations.

The following code example illustrates a service class that implements ITaskService.

    public class TaskService : ITaskService
    {
        public void CreateTask(string taskId, string assignee, string text)
        {
            Console.WriteLine("task " + taskId + " created for " + assignee);
        }

        public void RaiseEvent(TaskEventArgs args)
        {
            if (TaskCompleted != null)
                TaskCompleted(null, args);
        }

        public event EventHandler<TaskEventArgs> TaskCompleted;
    }

Using Correlation in Workflows

Interface Attributes

Using Correlation Attributes

See Also

Reference

Concepts

Additional resources