Export (0) Print
Expand All

Working with complex data in a workflow

Updated: July 12, 2012

DynamicValue allows you to create, store, and consume data structures. This data can be recursive, meaning that a DynamicValue can contain other DynamicValues. DynamicValue composition rules are very simple: its properties can be primitives, arrays, or other DynamicValues, similar to a recursive property bag or JSON serialization format. DynamicValue provides both a container and manipulation mechanism for compound data with first class binding surface for WF.

How DynamicValue Stores its Data

At the very core, you can think of DynamicValue as a recursive list of key-value pairs. The following table represents a simple DynamicValue:

 

Name Value of Underlying Primitive Data Type

Age

42

Name

John Doe

In the previous table, the DynamicValue has two properties: Age has a value of 42 and Name has a value of John Doe. The name of a DynamicValue property is a string, and the value can be any one of the types in the following list, or null (Nothing in Visual Basic). If any other type is passed to a DynamicValue an exception will be thrown.

  • String

  • Int32

  • Double

  • Guid

  • Boolean

  • DateTime

  • TimeSpan

  • IList<T>, where T is one of the types in this list

  • IDictionary<string, T>, where T is one of the types in this list

  • DynamicValue

Note that DynamicValue is in the list of supported types. This means that the value of a DynamicValue can be another DynamicValue, as shown in the following table.

 

Name Value

Customer

 

Name Value

Age

42

Name

Jon Doe

Company

Contoso Corporation

Customer contains a DynamicValue as its value, and that DynamicValue contains Age and Name. To reference the value for Name, you can use Customer/Name. If Customer/Name value is referred to and it has not yet been created, it will be added. This is referred to as an upsert.

DynamicValue also supports the notion of arrays. An array is a set of primitive values contained as the value for a DynamicValue. The main conceptual difference between a DynamicValue as an array instead of nested DynamicValue is that the items in the array do not have a name and are accessed by index. Note that the arrays can contain different types. In the array value for Numbers, the types are Int32 and Double. In the array value for Items, the values are a nested DynamicValue and an Int32.

 

Name Value

Numbers

 

4

6

3

3.14

2.71

Items

 

 

Name Value

First

4

Second

5

6

Addressing Values in a DynamicValue

Values are set and retrieved from a DynamicValue using a path notation. Paths are Uri-like strings that point to a given property, similar to the flattened representation of a structure. Paths are composed using the name of a property, using a string, or an index into an item within an array value, using a number surrounded by parenthesis.

noteNote
To see examples of working with DynamicValue paths, see the DynamicValue Path Evaluator sample. The DynamicValue Path Evaluator sample allows you to enter the endpoint of a REST service that returns JSON, and experiment and become familiar with DynamicValue and paths of the returned data.

In the previous section, several examples of DynamicValue were given. The first example was for a DynamicValue with two values, as shown in the following table.

 

Name Value

Age

42

Name

John Doe

To access the first value, a path consisting of Age is used, which returns a value of 42. A path of Name returns the value John Doe.

The second example from the previous section included some nested values, as shown in the following table.

 

Name Value

Customer

 

Name Value

Age

42

Name

Jon Doe

Company

Contoso Corporation

The path Customer returns a DynamicValue (which itself contains two values). The path of Company returns Contoso Corporation. In order to access nested values, a / is used to delineate properties. Using this notation, the path Customer/Age returns a value of 42, and Customer/Name returns John Doe.

To access values stored in an array, indexes are used in the path. The following table represents the DynamicValue from the previous section that contained booth arrays and nested DynamicValues.

 

Name Value

Numbers

 

4

6

3

3.14

2.71

Items

 

 

Name Value

First

4

Second

5

6

In the DynamicValue represented by the previous table, a path of Numbers returns the first array. DynamicValue arrays are zero based, and Numbers(0) returns the first element of the array, and Numbers(3) returns the fourth element of the array. Items returns the second array, and Items(0) returns the first item in the array, which is a DynamicValue. To access the values in that nested DynamicArray, the property names are combined with the path that yields the array. Items(0)/First returns 4 and Items(0)/Second returns 5.

You can use paths to declaratively build a compound data structure. The values can be known at design time or dynamically bound at runtime. The following example shows a set of paths and values that represent a composition of a customer that has an address.

 

Path (To) Value (From)

FirstName

John

LastName

Doe

Address/City

Redmond

Address/State

WA

The paths and values in the previous table would create the DynamicValue represented by the following table.

 

Name Value

FirstName

John

LastName

Doe

Address

 

Name Value

City

Redmond

State

WA

The DynamicValue type provides a Parse method that can be used to parse a JSON string into a DynamicValue. In addition, there is a ParseDynamicValue activity that can be used in workflows to parse a JSON string into a DynamicValue.

Http activities can also understand DynamicValue. If you assign a DynamicValue to the response of an Http* activity, it will get the results as JSON and build a DynamicValue with that result. If you pass a DynamicValue to the request body or use it as the response content, the appropriate headers will be added to indicate that JSON is used.

Using DynamicValue in Workflows

In addition to the DynamicValue type, Workflow Manager 1.0 also provides activities for creating and working with DynamicValue in workflows.

 

Activity Description Arguments

BuildDynamicValue

Builds a DynamicValue instance. It receives a dictionary of paths and values as input and returns the resulting DynamicValue. It uses a multi-assign approach to build the DynamicValue (it accepts multiple paths and values).

This activity can be used to create a new DynamicValue or to modify an existing one.

InArgument<IDictionary<string,InArgument>> Properties

InOutArgument<DynamicValue> Result

ContainsDynamicValueProperty

Returns true if a DynamicValue contains a property represented by the specified path

InArgument<DynamicValue> Source

InArgument<DynamicValue> PropertyName

OutArgument<bool> Result

CopyDynamicValue

Copies properties from one DynamicValue to another DynamicValue

InArgument<IDictionary<string,string>> PropertyMapping

InArgument<DynamicValue> Source

OutArgument<DynamicValue> Result

CountDynamicValueItems

Returns the count of children in a DynamicValue path

InArgument<DynamicValue> Source

OutArgument<int> Result

CreateDynamicValue

Create an instance of a DynamicValue passing only one path and one value (no multi-assign semantics)

InArgument<string> PropertyName

InArgument PropertyValue

OutArgument<DynamicValue> Result

CreateDynamicValueFromMessage

Creates a DynamicValue from a SOAP message

InArgument<DynamicValue> Headers

InArgument<XElement> Value

InArgument<MessageVersion> Version

OutArgument<DynamicValue> Result

CreateMessageFromDynamicValue

Creates a SOAP message from a specially formatted DynamicValue

InArgument<string> Action

InArgument<DynamicValue> Headers

InArgument<DynamicValue> Body

InArgument<MessageVersion> Version

OutArgument<XElement> Result

CreateUriFromDynamicValue

Creates a URI from a DynamicValue

InArgument<DynamicValue> Options

OutArgument<string> Result

GetDynamicValueProperties

Get several properties of an existing DynamicValue. Given a DynamicValue a user can query multiple properties (passing multiple paths) using a single activity.

InArgument<DynamicValue> Source

InArgument<IDictionary<string,OutArgument>> Properties

GetDynamicValueProperty

Get one property of a DynamicValue, where T is one of the types in previously given list.

InArgument<DynamicValue> Source

InArgument<string> PropertyName

OutArgument<T> Result

ParseDynamicValue

Parse a JSON string into a DynamicValue

InArgument<string> JSON

OutArgument<DynamicValue> Result

Using DynamicValue

DynamicValue and its supporting activities allow for representing and manipulating data in a host agnostic way. Hence, DynamicValue is a workflow feature that can be used with any workflow host, so it is not limited to Workflow Manager 1.0. It can be used with any of the other existing workflow hosts like WorkflowInvoker, WorkflowApplication, and WorkflowServiceHost.

The Working with complex data in a workflow using DynamicValue sample demonstrates how to use the feature with WorkflowApplication. Several of the other Using DynamicValue samples show how to use DynamicValue in Workflow Manager 1.0 workflows. DynamicValue usage is the same regardless of the host; what changes for every host is how the data is loaded into the DynamicValue (for example in Workflow Manager 1.0 it is very common to create the DynamicValue as the result of an Http operation using Http activities).

noteNote
For information about the Workflow Manager 1.0 samples and where to locate them, see Workflow Manager 1.0 Samples.


Workflow Manager 1.0 MSDN Community Forum


Build Date:

2014-01-17

Community Additions

ADD
Show:
© 2014 Microsoft