How to: Create an SDM Application System

Article
11/24/2009

How to: Create an SDM Application System

Using SDM, you can create an application system model that models a real application by containing other SDM objects and containing a variety of settings. The application system model is able to contain SDM objects such as endpoints that let the application system communicate with other systems and resources. You can create settings on the application system that model the attributes of a real application, such as the version of the application and the amount of memory used by the application. These settings can be used by logical server systems that host the application system.

This section describes the steps to create a system that models an application.

Bb167807.wedge(en-us,VS.90).gif To create an SDM system that models an application

Create a .sdm file named Microsoft.Samples.MyApplication.sdm.

For more information on creating a .sdm file, see How to: Create an SDM Document. Use the code below to start your .sdm file.
```
<?xml version="1.0" encoding="US-ASCII"?>
```

&lt;Information&gt;
    &lt;FriendlyName&gt;Example of a system in the application layer.
    &lt;/FriendlyName&gt;
    &lt;CompanyName&gt;Microsoft Corporation&lt;/CompanyName&gt;
    &lt;Copyright&gt;Copyright (c) Microsoft Corporation. 
        All rights reserved.  
        This is provided AS IS with no warranties,
        and confers no rights.&lt;/Copyright&gt;
&lt;/Information&gt;

&lt;!-- Add import information --&gt;

&lt;!-- Add system information --&gt;

&lt;!-- Add containment relationship for resource --&gt;

&lt;!-- Add containment relationship for endpoints --&gt;

&lt;!-- Add containment relationship for Application layer --&gt;

&lt;!-- Add hosting relationships --&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).

Add <Import> elements for each imported .sdmdocument file.

Whenever a .sdm file needs to reference a definition found in a .sdmdocument file, an <Import> element is used. When an <Import> element is used in the .sdm file, the compiler command sdmc.exe /r must be used to compile the document. Each <Import> element specifies:
- A reference to a definition in a .sdmdocument file.
- An Alias attribute whose value specifies the prefix that will be used when referring to other documents from the current file.
- The Name attribute of the SystemDefinitionModel Element that is being referenced.
Add the following XML block to the Microsoft.Samples.MyApplication.sdm file to specify the imports that will be used in this sample.
```
    
<Import Alias="DA" 
    Name="Microsoft.DistributedApplication" />
<Import Alias="VerConstraint" 
    Name="Microsoft.Samples.VersionConstraint" />
<Import Alias="CollList" 
    Name="Microsoft.Samples.CollapseList" />
<Import Alias="Certs" 
    Name="Microsoft.Samples.Certificates"/>
<Import Alias="Ftp" 
    Name="Microsoft.Samples.SimpleFtp"/>
<Import Alias="MyServer" 
    Name="Microsoft.Samples.MyLogicalServer" />
<Import Alias="Windows" 
    Name="Microsoft.WindowsHost"/>
```
For more information on the XML elements used in the code above, see Import Element.
Create an Application layer (used in the Application Diagram) system.
1. The application system is named MyApplication. Add the following code to the .sdm file.
```

```

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

2.  Add deployment report data to the \<SystemDefinition\> element that was created in step 3a.
    
    Every system definition that is loaded by the design surface in Visual Studio needs a \<DesignData\> element for the deployment report. When the deployment report is generated, it will use the design data to indicate what type of system definition is used. If the appropriate design data is not added to a system definition, you will get an error when you generate the deployment report.
    
    Under the \<DesignData\> element in your system definition, add the Report element with Type="Application". Replace the \<SystemDefinition\> element created in the step above with the \<SystemDefinition\> element below.
    
    <pre IsFakePre="true" xmlns="https://www.w3.org/1999/xhtml">&lt;!-- System information --&gt;

    &lt;DesignData&gt;
        &lt;Report Type="Application" 
            xmlns="https://schemas.microsoft.com/SystemDefinitionModel/2005/1/DesignData/DeploymentReport" /&gt;
    &lt;/DesignData&gt;

</SystemDefinition>

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

3.  Add settings to the \<SystemDefinition\> element created in step 3b.
    
    Add a setting to the application system so that in Visual Studio, the user will be able to specify the version of an application system. Replace the \<SystemDefinition\> element created in step 3b with the \<SystemDefinition\> element below.
    
    <pre IsFakePre="true" xmlns="https://www.w3.org/1999/xhtml">&lt;!-- System information --&gt;

    &lt;!-- Create a setting to represent the version of the application --&gt;
    &lt;SettingDeclaration 
        Name="AppVersion" 
        Definition="Version" List="false" CanBeNull="false"/&gt;

</SystemDefinition>

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

4.  Add settings, and a flow for the settings, to the \<SystemDefinition\> element that was created in step 3c (optional).
    
    A flow is used to compute a setting's value from the value of other settings. For more information on creating a flow between settings, see [How to: Create an SDM Flow](bb167810\(v=vs.90\).md).
    
    In the following code, a \<Flow\> element is added along with settings that use the flow. Replace the \<SystemDefinition\> element created in step 3c with the \<SystemDefinition\> element below.
    
    <pre IsFakePre="true" xmlns="https://www.w3.org/1999/xhtml">&lt;!-- System information --&gt;

    &lt;!-- Create a setting to represent the version of the application --&gt;
    &lt;SettingDeclaration 
        Name="AppVersion" 
        Definition="Version" List="false" CanBeNull="false"/&gt;

    &lt;!-- Create some settings to try out 
        the sample flow (CollapseList). --&gt;
    &lt;SettingDeclaration Name="Names" 
        Definition="String" List="true" CanBeNull="false"/&gt;
    &lt;SettingDeclaration Name="NameSeparator" 
        Definition="String" List="false" CanBeNull="false"/&gt;
    &lt;SettingDeclaration Name="CombinedNames" 
        Definition="String" List="false" CanBeNull="false"/&gt;

    &lt;!-- Use the sample flow to convert the list of names
        into a single value --&gt;
    &lt;Flow Name="CombineNames" Definition="CollList:CollapseList"&gt;
        &lt;Input Name="ListSource" Path="Names"/&gt;
        &lt;Input Name="Separator" Path="NameSeparator"/&gt;
        &lt;Output Name="Destination" Path="CombinedNames"/&gt;
    &lt;/Flow&gt;

</SystemDefinition>

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

Add containment relationships to your system so that the system can contain endpoints and resources.
1. Adding a resource to a system allows the system model to contain a software or hardware element. Examples of resources in an operating system include certificates, certificate stores, files, directories, and registry keys. In this example, the resource that this application system will contain is a certificate named X509Certificate. To create this resource, see How to: Create an SDM Resource.
  
  The following example defines the containment definition of the certificate resource so the application system can contain the resource. Add the following code to your .sdm file.
```

```

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

2.  Adding endpoints to a system allows the system to be able to communicate with other systems over a protocol such as HTTP, TCP/IP, or FTP. In this example, the endpoints that the application system will contain are named FtpContentClient and FtpContentServer. These endpoints allow the application system to communicate with other systems using FTP. To create these endpoints, see [How to: Create an SDM Endpoint](bb167809\(v=vs.90\).md).
    
    The following example defines the containment definitions of the FTP endpoints so the system can contain the endpoints. Add the following code to your .sdm file.
    
    <pre IsFakePre="true" xmlns="https://www.w3.org/1999/xhtml">&lt;!-- MyApplication can contain ftp endpoints
in the application layer --&gt;

Add required System Diagram (SD) containment.

In order to create a fully functional application system in the Application layer, there is a required containment definition that must be added, otherwise, you will not be able to create an application system in the design surface of Visual Studio. Add the following code to your .sdm file.
```

```

Add hosting definitions.

After defining the application system, define which logical server systems in the ApplicationHost layer (systems in the LDD) the application system can be hosted on. We will allow it to be hosted on the WindowsHost (WindowsClient is the display name in Visual Studio) as well as the MyLogicalServer system that was created in the How to: Create an SDM Logical Server System topic.

The following code creates two hosting definitions in the system. One hosting definition so the system can be hosted by the WindowsHost system, and the other hosting definition so the system can be hosted by the MyLogicalServer system. Add the following code to your .sdm file.
```

```

<HostingDefinition Name="MyLogicalServerHostsMyApplication" HostDefinition="MyServer:MyLogicalServer" GuestDefinition="MyApplication"/>

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

Add constraints to the application system (optional).

Because a setting for the version of the application was already created, we can add a constraint to the MyLogicalServer hosting relationship that was defined in step 6. This constraint checks the necessary settings on the MyLogicalServer system and compares them to the settings on the application system, using a new constraint named VersionConstraint that will check if a version of the application is within a range of valid versions on the logical server hosting the application. The VersionConstraint is created by following the steps in the How to: Create a Custom Constraint on a Setting topic.

Replace the MyLogicalServer hosting definition from the code in step 6 with the code below.
```

```

&lt;!-- Use the constraint to check
    if the FileVersion is within range --&gt;
&lt;Constraint 
    Name="VersionInRange" 
    Definition="VerConstraint:VersionConstraint"&gt;
    &lt;Input Name="ActualVersion" 
        Path="Guest.AppVersion"/&gt;
    &lt;Input Name="MinimumDesiredVersion" 
        Path="Host.MinAppVersion"/&gt;
    &lt;Input Name="MaximumDesiredVersion" 
        Path="Host.MaxAppVersion"/&gt;
    &lt;Input Name="MinimumDesiredVersionInclusive" 
        Path="Host.MinAppVersionInclusive"/&gt;
    &lt;Input Name="MaximumDesiredVersionInclusive" 
        Path="Host.MaxAppVersionInclusive"/&gt;
&lt;/Constraint&gt;

</HostingDefinition>

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

Compile the .sdm File

Use the SDM compiler to validate the .sdm file that you created in the steps above. For more information on the SDM compiler, see SDM Command Line Compiler (SdmC.exe). To invoke the sdm compiler, open an SDM SDK compiler window and type the following command at the command prompt.

Sdmc.exe Microsoft.Samples.MyApplication.sdm /r Microsoft.DistributedApplication.sdmdocument /r Microsoft.Samples.VersionConstraint.sdmdocument /r Microsoft.Samples.CollapseList.sdmdocument /r Microsoft.Samples.Certificates.sdmdocument /r Microsoft.Samples.SimpleFtp.sdmdocument /r Microsoft.Samples.MyLogicalServer.sdmdocument /r Microsoft.WindowsHost.sdmdocument /SearchPath "%SdmModelsDir%\"

If the .sdm file is valid XML, the command above will produce the compiled form of the document, namely, Microsoft.Sample.MyApplication.sdmdocument. Note that the format of the compiled file is slightly different from the format of the .sdm file.
Create a prototype for the system.

In order for the system to appear in the toolbox in Visual Studio, you need to create a prototype for the system. Run the ProtoGen.exe tool with the following command lines, which will create a prototype file named MyApplication.adPrototype. For more information on the ProtoGen.exe tool, see SDM Prototype Generator (ProtoGen.exe).

ProtoGen.exe /Type System /Layer Application /Document Microsoft.Samples.MyApplication /TypeName MyApplication /Output MyApplication.adPrototype

For information on installing the prototype and the .sdmdocument file so that the system can be used in Visual Studio, see the step 2 in How to: Create an SDM System.

Example

The following example shows the complete code for an application system named MyApplication.

<?xml version="1.0" encoding="US-ASCII"?>
<SystemDefinitionModel Name="Microsoft.Samples.MyApplication" 
    Version="1.0.0.0" 
    xmlns="https://schemas.microsoft.com/SystemDefinitionModel/2005/1"
    xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xs="https://www.w3.org/2001/XMLSchema">

    <Information>
        <FriendlyName>Example of a system in the application layer.
        </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>
    </Information>

    <Import Alias="DA" 
        Name="Microsoft.DistributedApplication" />
    <Import Alias="VerConstraint" 
        Name="Microsoft.Samples.VersionConstraint" />
    <Import Alias="CollList" 
        Name="Microsoft.Samples.CollapseList" />
    <Import Alias="Certs" 
        Name="Microsoft.Samples.Certificates"/>
    <Import Alias="Ftp" 
        Name="Microsoft.Samples.SimpleFtp"/>
    <Import Alias="MyServer" 
        Name="Microsoft.Samples.MyLogicalServer" />
    <Import Alias="Windows" 
        Name="Microsoft.WindowsHost"/>

    <SystemDefinition 
        Name="MyApplication" 
        Layer="Application" 
        Abstract="true">
        <DesignData>
            <Report Type="Application" 
                xmlns="https://schemas.microsoft.com/SystemDefinitionModel/2005/1/DesignData/DeploymentReport" />
        </DesignData>
        
        <!-- Create a setting to represent the version of the application -->
        <SettingDeclaration 
            Name="AppVersion" 
            Definition="Version" List="false" CanBeNull="false"/>

        <!-- Create some settings to try out 
            the sample flow (CollapseList). -->
        <SettingDeclaration Name="Names" 
            Definition="String" List="true" CanBeNull="false"/>
        <SettingDeclaration Name="NameSeparator" 
            Definition="String" List="false" CanBeNull="false"/>
        <SettingDeclaration Name="CombinedNames" 
            Definition="String" List="false" CanBeNull="false"/>

        <!-- Use the sample flow to convert the list of names
            into a single value -->
        <Flow Name="CombineNames" Definition="CollList:CollapseList">
            <Input Name="ListSource" Path="Names"/>
            <Input Name="Separator" Path="NameSeparator"/>
            <Output Name="Destination" Path="CombinedNames"/>
        </Flow>
        
    </SystemDefinition>

    <!-- MyApplication can contain a certificate -->
    <ContainmentDefinition Name="MyApplicationContainsCertificate" 
    ParentDefinition="MyApplication" 
    MemberDefinition="Certs:X509Certificate"/>

    <!-- MyApplication can contain ftp endpoints
        in the application layer -->
    <ContainmentDefinition 
        Name="MyApplicationContainsFtpContentClient"
        ParentDefinition="MyApplication"
        MemberDefinition="Ftp:FtpContentClient"/>
    <ContainmentDefinition 
        Name="MyApplicationContainsFtpContentServer"
        ParentDefinition="MyApplication"
        MemberDefinition="Ftp:FtpContentServer"/>

    <!-- A system in the Application layer
        must be contained by DistributedApplication -->
    <ContainmentDefinition 
        Name="DistributedApplicationContainsMyApplication" 
        ParentDefinition="DA:DistributedApplication" 
        MemberDefinition="MyApplication"/>

    <!-- MyApplication can be hosted by WindowsHost
        without restrictions -->
    <HostingDefinition Name="WindowsHostHostsMyApplication"
        HostDefinition="Windows:WindowsHost"
        GuestDefinition="MyApplication"/>

    <!-- MyApplication can be hosted by
        MyLogicalServer with a constraint on the hosting -->
    <HostingDefinition 
        Name="MyLogicalServerHostsMyApplication" 
        HostDefinition="MyServer:MyLogicalServer" 
        GuestDefinition="MyApplication">
    
        <!-- Use the constraint to check
            if the FileVersion is within range -->
        <Constraint 
            Name="VersionInRange" 
            Definition="VerConstraint:VersionConstraint">
            <Input Name="ActualVersion" 
                Path="Guest.AppVersion"/>
            <Input Name="MinimumDesiredVersion" 
                Path="Host.MinAppVersion"/>
            <Input Name="MaximumDesiredVersion" 
                Path="Host.MaxAppVersion"/>
            <Input Name="MinimumDesiredVersionInclusive" 
                Path="Host.MinAppVersionInclusive"/>
            <Input Name="MaximumDesiredVersionInclusive" 
                Path="Host.MaxAppVersionInclusive"/>
        </Constraint>
    </HostingDefinition>

</SystemDefinitionModel>

How to: Create an SDM Application System

How to: Create an SDM Application System

Example

See Also

Additional resources