How to: Create an SDM Flow

Article
11/24/2009

How to: Create an SDM Flow

Creating a flow between settings allows the value of a setting to be computed from other settings' values. Flows work similar to calculations in a spreadsheet. A cell in a spreadsheet can contain a formula (a flow in SDM) that uses one or more other cells (settings in SDM) as input to the formula to create a derived value.

Flows are implemented by a manager. Managers allow you to define the custom behavior of a flow by implementing the behavior of the flow in C# code. A manager is defined in an .sdm file (in XML) and then the SDM Manager Generator command line tool is used to create the manager in C#. After the manager is created, you write C# code to implement the flow.

This section describes the steps to create your own implementation for a flow called "CollapseList." It is a flow function that will take a list of settings and collapse them into a single setting value.

Bb167810.wedge(en-us,VS.90).gif To create an SDM Flow

Create a .sdm document named Microsoft.Samples.CollapseList.sdm.

For more information on creating a .sdm document, see How to: Create a .sdmdocument File. Use the code below to start your .sdm document.

[XML]
```
<?xml version="1.0" encoding="US-ASCII"?>
```

<SystemDefinitionModel Name="Microsoft.Samples.CollapseList" Version="1.0.0.0" DocumentLanguage="en" xmlns="https://schemas.microsoft.com/SystemDefinitionModel/2005/1"> <Information> <FriendlyName>Sample Flow model</FriendlyName> <CompanyName>Microsoft Corporation</CompanyName> <Copyright>Copyright (c) Microsoft Corporation. All rights reserved.
This is provided AS IS with no warranties, and confers no rights. </Copyright> <Description>This is a sample flow that collapses values from a list to a single value. </Description> </Information>

&lt;!-- Add flow information here --&gt;

</SystemDefinitionModel>

For more information on the XML elements used in the code above, see [**SystemDefinitionModel Element**](bb168334\(v=vs.90\).md) and [**Information Element**](bb168173\(v=vs.90\).md).

Create a flow definition.

In a flow definition, you provide the name of the manager that will be implementing the flow. Note the class name (ClrClassName) in the code below, which will be used later when implementing the manager in C#. Add the following code to your .sdm file.

[XML]
```
<FlowDefinition 
Name="CollapseList"
Manager="CollapseListManager"
ClrClassName="Microsoft.SystemDefinitionModel.Samples.CollapseList"/>
```
For more information on the XML element used in the code above, see FlowDefinition Element.
Specify the manager information for the flow.

For the SDM compiler to find the assembly with the implementation of the flow, you need to specify the manager information. In a later step, you will provide the implementation for and compile Microsoft.Sdm.Samples.CollapseList.dll. Add the following code to your .sdm file.

[XML]
```
<Manager 
Name="CollapseListManager"
AssemblyName="Microsoft.Sdm.Samples.CollapseList"
SourcePath="Microsoft.Sdm.Samples.CollapseList.dll" />
```

For more information on the XML element used in the code above, see [**Manager Element**](bb168178\(v=vs.90\).md).

Add the settings that use the flow.

A setting declaration must be provided for each setting that will be used to evaluate the flow. For this example, three settings are used:

ListSource: The list of setting values that will be concatenated to form a single value.
Separator: Delimiter string that will be concatenated between each of the values in ListSource.
Destination: The setting to which the result of the flow will be assigned.

For example, there are two values in the ListSource setting: "A" and "B". If the Separator setting value is a comma and a space, the Destination setting value will be assigned "A, B".

The settings are added to the .sdm file in the flow definition created in step 2.

[XML]

<FlowDefinition 
Name="CollapseList"
Manager="CollapseListManager" 
ClrClassName="Microsoft.SystemDefinitionModel.Samples.CollapseList">

    <Description>Collapses all values in a setting list to a single value.
    </Description>
    <SettingDeclaration 
        Name="ListSource" 
        List="true" 
        Definition="Any" 
        Access="WriteOnly" 
        CanBeNull="true" />
    <SettingDeclaration 
        Name="Destination" 
        List="false" 
        Definition="String" 
        Access="ReadOnly" 
        CanBeNull="true" />
    <SettingDeclaration 
        Name="Separator" 
        List="false" 
        Definition="String" 
        Access="WriteOnly" 
        CanBeNull="false"/>

    <SettingValueList 
        Path="ListSource" Null="true" />
    <SettingValue 
        Path="Separator">, </SettingValue>

</FlowDefinition>

For more information on the XML element used in the code above, see [**SettingDeclaration Element**](bb168223\(v=vs.90\).md) and [**SettingValueList Element**](bb168233\(v=vs.90\).md).

When creating the settings for the flow, note:

  - The definition for the ListSource setting is "Any", which means that any type of list can be used to compute the flow: String, Int, Version, or any other possible setting definition. Later in this topic, the Any type is converted to a string.
  - Each setting that is an input to the flow must have Access set to WriteOnly.
  - Each setting that is an Output from the flow must have Access set to ReadOnly
  - When evaluating the flow, all settings that are inputs to the flow must be initialized before the SDM compiler will allow the flow to be executed. To make it easier to use the flow, a good practice is to provide default values for each of the input settings if they are not required. In the flow definition, the default values are set such that the list is null and the separator string is a comma and a space.

Create a manager for the flow.

Managers allow flows to insert custom behavior into the runtime environment by having the behavior of the flow implemented in C# code. The C# code that creates the manager is generated from the .sdm file that contains the flow definition by using the SDM Manager Generator (SdmG.exe) tool, and then you add the C# code that implements the behavior of the flow.
1. Generate the C# flow manager code using the SDM Manager Generator command line tool. For more information on the tool, see SDM Manager Generator (SdmG.exe).
  
  The settings that were added to the <FlowDefinition> element above need to have corresponding public properties in a C# implementation of the manager. To make this process easier for you, the SDM Manager Generator (SdmG.exe) tool generates this code. Run the following command line to use the tool. This command places the resulting C# code in a file named CollapseListProperties.cs.
  
  SdmG.exe Microsoft.Samples.CollapseList.sdm /Flows*+* **/Classes:**CollapseListProperties.cs
  
  If you look at the CollapseListProperties.cs file, you should see the following code.
  
  [C#]
```
/// This file was generated using SdmG.exe, version=1.0.x.0
```

namespace Microsoft.SystemDefinitionModel.Samples { using System;

public partial class CollapseList :

Microsoft.SystemDefinitionModel.Manager.IFlow { public string Separator; public string Destination; public object[] ListSource; } }

    In the code above, note:
    
      - The namespace and class name are derived from the **ClrClassName** attribute of the \<FlowDefinition\> element.
      - The generated class implements the [**IFlow**](bb167945\(v=vs.90\).md) interface, although no implementation is provided for the [**IFlow.Evaluate**](bb167946\(v=vs.90\).md) method.
      - The generated class is a partial class.
      - The SDM type "Any" translated to the C\# type "object".

2.  Implement the **IFlow.Evaluate** method for the flow.
    
    Because the generated code is a partial class, you can define the implementation for the **IFlow.Evaluate** method in a separate C\# file. This code should implement the behavior of the flow.
    
    Create a new C\# source file with a class that implements **IFlow** and has the same name as the generated CollapseList class above.
    
    #### \[C\#\]
    
    The following code implements the **IFlow.Evaluate()**. Place the code in a file named CollapseList.cs.
    
    <pre IsFakePre="true" xmlns="https://www.w3.org/1999/xhtml">namespace Microsoft.SystemDefinitionModel.Samples

{ using System; using System.Text; using Microsoft.SystemDefinitionModel; using Microsoft.SystemDefinitionModel.Manager;

public partial class CollapseList : IFlow
{
    /// &lt;summary&gt;
    /// Collapse the values from a setting value list
    /// into a single value.
    /// &lt;/summary&gt;
    /// &lt;returns&gt; Array of errors detected when
    /// evaluating the flow.
    ///&lt;/returns&gt;
    
    public FlowError[] Evaluate()
    {
        // Check if the list has been initialized.
        if (this.ListSource == null)
        {
            // The list is null,
            // so set the destination to null
            this.Destination = null;
        }
        else
        {
            // Convert the object array to
            // a string array
            String[] stringValues =
                new String[this.ListSource.Length];
            for (int i = 0; i &lt; this.ListSource.Length; i++)
            {
                stringValues[i] = 
                    this.ListSource[i].ToString();
            }

            // Join the array with the separator and
            // assign the value to the destination.
            this.Destination = 
                String.Join(this.Separator, stringValues);
        }

        // There are no errors to be detected
        // in this flow.
        return null;
    }
}

}

Compile the C# manager code.

Take the two C# files that you created in step 5 and call the C# compiler (Csc.exe) using the command below. The SDM SDK Command Prompt window sets the SdmPublicAssemblies environment variable that will be needed for this compilation.

Csc.exe /noconfig /target*:library* /reference*:"%SdmPublicAssemblies%\Microsoft.sdm.manager.dll"* /out*:Microsoft.Sdm.Samples.CollapseList.dll* CollapseListProperties.cs CollapseList.cs ****
Compile the .sdm file containing the <FlowDefinition> element.

At this point, you have completed creating the flow. Now, compile the .sdm file containing the flow to produce a .sdmdocument file containing the flow, which can be referenced later by Distributed System Designer so that the flow can be used by SDM in Visual Studio 2005 Team Edition for Software Architects and Visual Studio Team System 2008 Architecture Edition. Make sure the manager assembly from the previous step is in the same directory as the .sdm file.

Use the SDM compiler to compile the .sdm file. For more information on the compiler, see SDM Command Line Compiler (SdmC.exe).

SdmC.exe Microsoft.Samples.CollapseList.sdm /Output Microsoft.Samples.CollapseList.sdmDocument

Using the Flow

Now that you have defined the flow and provided an implementation, you can use the flow. In an SDM system, the <Flow> element is used with <Input> and <Output> child elements for each of the settings that will be used to compute the flow. To see an example of how the flow that was created in this topic is used, see step 3 in How to: Create an SDM Application System.

How to: Create an SDM Flow

How to: Create an SDM Flow

[XML]

[XML]

[XML]

[XML]

[C#]

Using the Flow

See Also

Additional resources