Share via

How to: Create an SDM Endpoint

  • Article

How to: Create an SDM Endpoint

An endpoint is created when a system needs to communicate with another system through a protocol (for example, FTP). For example, if you have a logical server system that communicates with another logical server system using FTP, then each logical server system needs to contain an FTP endpoint. You create an endpoint for each kind of system (logical server system, or application system) in which a protocol can be used.

Endpoints allow systems to form communication relationships with other systems. Because resources cannot have dependencies that cross system boundaries, endpoints are used to model the interaction of a system with other components. Examples of endpoints include the HTTP, TCP/IP, and SOAP connectors between systems.

When to Create an SDM Endpoint

Each component object of the system definition model has certain characteristics that serve as guidelines in deciding how to define a model for it. You should model an object as an endpoint when:

  • The object you are modeling represents a role in a protocol.
  • You expect systems to be developed that use this protocol to interact.

This section describes the steps to create endpoints for systems to communicate with each other using FTP.

Bb167809.wedge(en-us,VS.90).gifTo create an SDM endpoint

  1. Create a .sdm file named Microsoft.Samples.SimpleFtp.sdm.

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

    <?xml version="1.0" encoding="utf-8"?>

<SystemDefinitionModel Name="Microsoft.Samples.SimpleFtp" Version="1.0.0.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns="https://schemas.microsoft.com/SystemDefinitionModel/2005/1"> <Information> <CompanyName>Micorosoft 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 SDM SDK sample to illustrate authoring SDM endpoints. </Description> </Information>

&lt;!-- Import information --&gt;


&lt;!-- Endpoint definitions --&gt;


&lt;!-- Containment definitions --&gt;


&lt;!-- Communication definitions --&gt;


&lt;!-- Delegation definitions --&gt;


&lt;!-- Hosting definitions --&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).

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

    Whenever an .sdm file needs to reference a definition found in an .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 another .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.SimpleFtp.sdm file to specify the imports that will be used in this sample.

    <!-- Import information -->

<Import Alias="WindowsApp" Name="Microsoft.WindowsApplication"/>
<Import Alias="WebHost" Name="Microsoft.WebHost"/>
<Import Alias="WindowsHost" Name="Microsoft.WindowsHost"/>
<Import Alias="WebApp" Name="Microsoft.WebApplication"/>
<Import Alias="DC" Name="Microsoft.Datacenter"/>
<Import Alias="DA" Name="Microsoft.DistributedApplication"/>
<Import Alias="Web" Name="Microsoft.Web"/>
<Import Alias="Flow" Name="System.Flow"/>

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

  1. Create endpoint definitions in the .sdm file. Create one endpoint for each of the locations that the protocol can be used.

    Decide if the endpoint you are creating will be used in the Application Diagram (AD) or Logical Datacenter Diagram (LDD) in your SDM project in Visual Studio 2005 Team Edition for Software Architects or Visual Studio Team System 2008 Architecture Edition. For an endpoint in the AD, use "Application" for the Layer attribute. The Layer attribute should be set to "ApplicationHost" for endpoints used in the LDD. The same endpoint cannot be used in both layers.

    1. Create the client (consumer) endpoint for the Application layer (used in the AD).

      <!-- FtpContentClient is the client (consumer) endpoint

    in the application layer. --> <EndpointDefinition Name="FtpContentClient" Layer="Application" Abstract="true"/>

    1. Create the server (provider) endpoint for the Application layer (used in the AD).

      <!-- FtpContentServer is the server (provider) endpoint

    in the application layer. --> <EndpointDefinition Name="FtpContentServer" Layer="Application" Abstract="true"/>

    1. Create the client (consumer) endpoint for the ApplicationHost layer (used in the LDD).

      <!-- FtpClient is the client (consumer) endpoint

    in the application host layer. --> <EndpointDefinition Name="FtpClient" Layer="ApplicationHost" Abstract="true"/>

    1. Create the server (provider) endpoint for the ApplicationHost layer (used in the LDD).

      <!-- FtpServer is the server (provider) endpoint

    in the application host layer. --> <EndpointDefinition Name="FtpServer" Layer="ApplicationHost" Abstract="true"/> 

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

  2. Add design data to the client endpoints created in the step above.

    Each endpoint that acts as a client must be marked as such by using the <DesignData> element. This way, the design surface (AD or LDD) is able to connect client and server (provider) endpoints with the connection pointing the correct way (from provider to the consumer). By default, each endpoint is a server (provider) endpoint so you will only need to mark the client endpoints. The same endpoint cannot be used as both a server (provider) endpoint and a client (consumer) endpoint.

    The two client endpoints that were created in step 3a and 3c are listed below with the new design data information included in them. In your .sdm file, replace the code for the two client endpoints with the code below.

    1. Create the client endpoint for the application layer.

      <!-- FtpContentClient is the client (consumer) endpoint

    in the application layer. --> <EndpointDefinition Name="FtpContentClient" Layer="Application" Abstract="true"> <DesignData> <VisualStudio xmlns= "https://schemas.microsoft.com/SystemDefinitionModel/2005/1/DesignData/VisualStudio"> <ModelElement> <Property Name="Direction" Value="Client"/> </ModelElement> </VisualStudio> </DesignData> </EndpointDefinition>

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

    1. Create the client (consumer) endpoint for the host layer.

      <!-- FtpClient is the client (consumer) endpoint

    in the application host layer. --> <EndpointDefinition Name="FtpClient" Layer="ApplicationHost" Abstract="true"> <DesignData> <VisualStudio xmlns= "https://schemas.microsoft.com/SystemDefinitionModel/2005/1/DesignData/VisualStudio"> <ModelElement> <Property Name="Direction" Value="Client"/> </ModelElement> </VisualStudio> </DesignData> </EndpointDefinition>

  3. Add containment relationships to your .sdm file so that a system can contain the endpoints you are creating.

    On the design surface, an endpoint is drawn on the edge of a system. In the .sdm file, this is represented by a containment relationship in which the system contains the endpoint. To define this relationship, add a containment definition for each system that can contain each endpoint. Note that you should only allow host layer (LDD) systems to contain host layer endpoints and application layer (AD) systems to contain application layer endpoints.

    In this example, the application layer endpoints are added to the WindowsApplication and WebApplication (ASP.NETWebApplication and ASP.NETWebService) systems and the host layer endpoints are added to the WindowsHost (WindowsClient) and WebServer (IISWebServer) systems.

    Note  : The display names of the systems in the Visual Studio design surface are in parentheses, describing the SDM system names in the paragraph above.

    1. Add these containment definitions to your .sdm file.

      2. 

    

    4. 



<!-- Containment definitions -->


<!-- FtpClient containments -->
<ContainmentDefinition Name="WebServerContainsFtpClient"
ParentDefinition="WebHost:WebServer"
MemberDefinition="FtpClient"/>
<ContainmentDefinition Name="WindowsHostContainsFtpClient"
ParentDefinition="WindowsHost:WindowsHost"
MemberDefinition="FtpClient"/>


<!-- FtpServer containments -->
<ContainmentDefinition Name="WebServerContainsFtpServer"
ParentDefinition="WebHost:WebServer"
MemberDefinition="FtpServer" />
<ContainmentDefinition Name="WindowsHostContainsFtpServer"
ParentDefinition="WindowsHost:WindowsHost"
MemberDefinition="FtpServer"/>


<!-- FtpContentClient containments -->
<ContainmentDefinition
Name="WindowsApplicationContainsFtpContentClient"
ParentDefinition="WindowsApp:WindowsApplication"
MemberDefinition="FtpContentClient" />
<ContainmentDefinition Name="WebApplicationContainsFtpContentClient"
ParentDefinition="WebApp:WebApplication"
MemberDefinition="FtpContentClient" />


<!-- FtpContentServer containments -->
<ContainmentDefinition
Name="WindowsApplicationContainsFtpContentServer"
ParentDefinition="WindowsApp:WindowsApplication"
MemberDefinition="FtpContentServer" />
<ContainmentDefinition Name="WebApplicationContainsFtpContentServer"
ParentDefinition="WebApp:WebApplication"
MemberDefinition="FtpContentServer" />



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

2.  In addition to the containment definitions for the application and host that will contain the endpoints, there is a required set of containment definitions that must be specified. Each application layer (AD) endpoint must be contained by the DistributedApplication system in Microsoft.DistributedApplication.sdmdocument, and each host layer (LDD) endpoint must be contained by the ZoneEndpoint in Microsoft.Datacenter.sdmdocument. Add the code below to your .sdm file.
    
    <pre IsFakePre="true" xmlns="https://www.w3.org/1999/xhtml">&lt;!-- Required application layer containments
 with DistributedApplication. --&gt;



<ContainmentDefinition Name="DistributedAppContainsFtpContentClient"
ParentDefinition="DA:DistributedApplication"
MemberDefinition="FtpContentClient" />
<ContainmentDefinition Name="DistributedAppContainsFtpContentServer"
ParentDefinition="DA:DistributedApplication"
MemberDefinition="FtpContentServer" />


<!-- Required host layer containments with ZoneEndpoint. -->
<ContainmentDefinition Name="ZoneEndpointContainsFtpClient"
ParentDefinition="DC:ZoneEndpoint"
MemberDefinition="FtpClient" />
<ContainmentDefinition Name="ZoneEndpointContainsFtpServer"
ParentDefinition="DC:ZoneEndpoint"
MemberDefinition="FtpServer" />



    

  1. Add communication definitions.
    

    Given that you want to connect the endpoints together on the design surfaces (the Visual Studio AD and LDD), you need to define which endpoints can communicate with each other. This is done with a communication definition. One communication definition must be specified between each client and logical server that can be connected. Add the code below to your .sdm file.
    

    2. 



<!-- Communication definitions -->


<!-- Specify communication relationships
between the appropriate ftp clients and logical servers. -->
<CommunicationDefinition Name="FtpConnection"
ClientDefinition="FtpClient"
ServerDefinition="FtpServer"/>
<CommunicationDefinition Name="FtpContentConnection"
ClientDefinition="FtpContentClient"
ServerDefinition="FtpContentServer"/>


Now that the communication definitions between the new FTP endpoints have been created, there are a couple of communication definitions that are required if you want the endpoint to communicate between zones in the host layer. You need to set up communication from your client (consumer) endpoint to ZoneEndpoint and from the ZoneEndpoint to your server (provider) endpoint. Add the code below to your .sdm file.

<pre IsFakePre="true" xmlns="https://www.w3.org/1999/xhtml">&lt;!-- Need a communication with
ZoneEndpoint to connect in and out of the zones --&gt;



<CommunicationDefinition Name="FtpToZoneConnection"
ClientDefinition="FtpClient"
ServerDefinition="DC:ZoneEndpoint"/>
<CommunicationDefinition Name="ZoneToFtpConnection"
ClientDefinition="DC:ZoneEndpoint"
ServerDefinition="FtpServer"/>



    

  1. Add hosting definitions.
    

    The application layer (AD) endpoints must be hosted by endpoints on the host layer (LDD). Otherwise, when you attempt to define a deployment, you will not be able to bind your systems in Deployment Designer. One hosting definition must be specified for each pair (application and host) of endpoints. Add the code below to your .sdm file.
    

    2. 



<!-- Hosting definitions -->


<!-- FtpClient hosts an FtpContentClient -->
<HostingDefinition Name="FtpClientHostsFtpContentClient"
GuestDefinition="FtpContentClient"
HostDefinition="FtpClient"/>


<!-- FtpServer hosts an FtpContentServer -->
<HostingDefinition Name="FtpServerHostsFtpContentServer"
GuestDefinition="FtpContentServer"
HostDefinition="FtpServer"/>


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



    

  1. Add delegation definitions.
    

    Each endpoint used by application systems should specify a delegation relationship with itself so that it can be delegated in System Designer and for zones in the LDD. Without the delegation relationships, if you attempt to drag a server (provider) endpoint to the boundary of a zone or create a proxy endpoint in System Designer, nothing will happen. Also, if you right-click the endpoint in System Designer or inside a zone and select Add Proxy Endpoint, nothing will happen without the delegation relationships. Add the code below to your .sdm file.
    

    <!-- Each endpoint should have a
delegation to itself -->

    2. 



<DelegationDefinition Name="FtpClientDelegation"
ProxyDefinition="FtpClient"
DelegateDefinition="FtpClient"/>
<DelegationDefinition Name="FtpServerDelegation"
ProxyDefinition="FtpServer"
DelegateDefinition="FtpServer"/>
<DelegationDefinition Name="FtpContentClientDelegation"
ProxyDefinition="FtpContentClient"
DelegateDefinition="FtpContentClient"/>
<DelegationDefinition Name="FtpContentServerDelegation"
ProxyDefinition="FtpContentServer"
DelegateDefinition="FtpContentServer"/>


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



    

  1. Add settings to the endpoints.
    

    You can add settings to endpoints and then add a flow between the settings on different endpoints. First, you add a few settings to the host layer FTP server (provider) endpoint.
    

    Add the following code to your .sdm file. This code will replace the EndpointDefinition element that was created in step 3d.
    

    <!-- FtpServer is the server (provider) endpoint
in the application host layer. -->

    2. 



<EndpointDefinition
Name="FtpServer" Layer="ApplicationHost" Abstract="true">
<SettingDeclaration Name="Port" Definition="Int" />
<SettingDeclaration Name="HomeDirectory" Definition="String" />
<SettingDeclaration Name="ConnectionTimeout" Definition="Int" />
<SettingDeclaration Name="MaxConnections" Definition="Int" />
<SettingDeclaration Name="Uri" Definition="Web:Uri" />
<SettingValue Path="Port">21</SettingValue>
</EndpointDefinition>


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

**Note**   The default port for FTP is 21, although it can be changed by anyone who uses this endpoint. If you want to always require port 21, you can set the **Fixed**="true" attribute on the \<SettingValue\> element.

So far, all the settings have used the basic \<SettingDeclaration\> element without doing anything complex. The \<SettingDeclaration\> element also allows you to use facets, which are like subsettings that work together to create the overall setting.

Add the following code to your .sdm file. This code will replace the \<EndpointDefinition\> element that was created in step 3b.

<pre IsFakePre="true" xmlns="https://www.w3.org/1999/xhtml">&lt;!-- FtpContentServer is the server (provider) endpoint
in the application layer. --&gt;



<EndpointDefinition
Name="FtpContentServer" Layer="Application" Abstract="true">
<SettingDeclaration Name="Uri"
Definition="Web:Uri"
DefaultRead="Absolute"
DefaultWrite="Relative"
CanBeNull="true">
<Facet Name="Base" />
<Facet Name="Relative" />
<Facet Name="Absolute" />
</SettingDeclaration>


&lt;SettingValue Path="Uri@Relative" Null="true" /&gt;
&lt;SettingValue Path="Uri@Base" Null="true" /&gt;



</EndpointDefinition>


Now that you have seen what the entire setting looks like, analyze each piece of the setting. Notice that there are three facets for the URI setting:

  - Base: This is the base URL where the FTP logical server is hosted.
  - Relative: The relative path from the Base where the content is located.
  - Absolute: Combination of the base and relative paths.

Each of these settings can be accessed or set by using the @ notation. For example, Uri@Relative will get or set the Relative facet. Because the Absolute facet will be computed from the base and relative paths, you need to make sure the Base and Relative facets are always initialized to some value. As you can see above, they have been initialized by the \<SettingValue\> elements to **Null**.

If you want to get around the @ notation for the facets because you feel it complicates things, you can still get and set the setting by using the normal setting name URI instead of something like Uri@Base. This is accomplished by using the attributes **DefaultRead** and **DefaultWrite** on the \<SettingDeclaration\> element. Whenever you need to read the value of the Uri setting, the Absolute facet will be retrieved. When you want to set the value of the Uri, the Relative facet will be set by default.

The next step describes how that Absolute facet is computed from the Base and Relative facets.



    

  1. Add flow between the settings on different endpoints.
    

    The Absolute facet needs to be computed from the Base and Relative facets. This will be accomplished by adding a flow to the FtpContentServer next to the Uri setting. There already exists a flow definition that knows how to flow a Uri in this format, so you reuse the one in Microsoft.Web.sdmdocument.
    

    Add the following code to your .sdm file. This flow needs to be added into the <EndpointDefinition> element that was created in step 3b.
    

    <!-- Compute the absolute Uri from the base
and relative paths. -->

    2. 



<Flow Name="ConstructAbsoluteUri"
Definition="Web:CombineUrlFlow">
<Input Name="Base" Path="Uri@Base" />
<Input Name="Relative" Path="Uri@Relative" />
<Output Name="Absolute" Path="Uri@Absolute" />
</Flow>


Now that the Absolute path is computed, note that the Base for the Uri isn't really controlled by the application layer. The base should come from the Uri setting in the FtpServer endpoint, which is in the host layer. Now you can add another flow that will copy the base Uri from the endpoint in the host layer to the Base facet of the endpoint in the application layer. The link between the two endpoints is the hosting definition created in step 7.

Add the following code to your .sdm file. This code replaces the \<HostingDefinition\> element created in step 7.

<pre IsFakePre="true" xmlns="https://www.w3.org/1999/xhtml">&lt;!-- FtpServer hosts an FtpContentServer --&gt;



<HostingDefinition Name="FtpServerHostsFtpContentServer"
GuestDefinition="FtpContentServer"
HostDefinition="FtpServer">


&lt;!-- Copy the base Uri from the host to the application layer. --&gt;
&lt;Flow Name="CopyUrlBase" Definition="Flow:Copy"&gt;
    &lt;Input Name="Source" Path="Host.Uri" /&gt;
    &lt;Output Name="Destination" 
        Path="Guest.Uri@Base" 
        Cast="true" /&gt;
&lt;/Flow&gt;



</HostingDefinition>


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

By copying the Uri from the host to the application layer, now the absolute Uri can be accurately computed in the application layer.



    

  1. 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.SimpleFtp.sdm /Output Microsoft.Samples.SimpleFtp.sdmDocument /Reference Microsoft.WindowsApplication.sdmDocument /r Microsoft.WebHost.sdmDocument /r Microsoft.WindowsHost.sdmDocument /r Microsoft.WebApplication.sdmDocument /r Microsoft.Datacenter.sdmDocument /r Microsoft.DistributedApplication.sdmDocument /r Microsoft.Web.sdmDocument /r System.Flow.sdmDocument /SearchPath "%SdmModelsDir%\"
    

    This compiles the .sdm file with the references mentioned in the imports. Because the built-in .sdmdocument files that are referenced are not in the current directory, you can use the /SearchPath switch to tell the compiler where to find them. The environment variable SdmModelsDir has already been set by the sdm command window to point to the directory where the referenced documents are installed.
    

    If the .sdm file is valid XML, the command above will produce the compiled form of the document, namely, Microsoft.Sample.SimpleFtp.sdmdocument. Note that the format of the compiled file is slightly different from the format of the .sdm file.
    

    2. 

  2. Create Toolbox items (prototypes).
    

    If you install the endpoint .sdmdocument file in Visual Studio now by following the directions in the Setup section at the end of this topic, you will be able to get the AD and LDD to add endpoints to the systems when you right-click the systems, but your endpoint will not show up in the toolbox in Distributed System Designer. To add the endpoint to the toolbox, you must create a prototype. A prototype is a file that defines the information about your endpoint, application, or logical server. When you drag a toolbox item onto the design surface, the information from the prototype enables the correct SDM information to be used.
    

    You need to create a prototype for all of the endpoints except one: the FtpContentClient endpoint. Client endpoints used in Application Designer do not need a prototype.
    

    The following steps are commands that use the ProtoGen.exe tool from the command line. For more information on the ProtoGen.exe tool, see SDM Prototype Generator (ProtoGen.exe). Each step in the list creates a prototype for a different endpoint.
    

      

    1. FtpClient endpoint prototype.
      

      ProtoGen.exe /Type Endpoint /Layer Host /Document Microsoft.Samples.SimpleFtp /TypeName FtpClient /Output FtpClient.lddPrototype /Name FtpClientEndpoint
      

      2. 

    2. FtpServer endpoint prototype.
      

      ProtoGen.exe /Type Endpoint /Layer Host /Document Microsoft.Samples.SimpleFtp /TypeName FtpServer /Output FtpServer.lddPrototype
      

      3. 

    3. FtpContentServer endpoint prototype.
      

      ProtoGen.exe /Type Endpoint /Layer Application /Document Microsoft.Samples.SimpleFtp /TypeName FtpContentServer /Output FtpContentServer.adPrototype
      

      4. 

    

    For information on installing the prototype and the .sdmdocument file, see the Setup section near the end of this topic.
    

    3. 



Example


The following example is a complete .sdm file that creates FTP endpoints.


<?xml version="1.0" encoding="utf-8"?>
<SystemDefinitionModel Name="Microsoft.Samples.SimpleFtp"
    Version="1.0.0.0" 
    xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xsd="https://www.w3.org/2001/XMLSchema" 
    xmlns="https://schemas.microsoft.com/SystemDefinitionModel/2005/1">
    <Information>
        <CompanyName>Micorosoft 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 SDM SDK sample 
            to illustrate authoring SDM endpoints.
        </Description>
    </Information>
    
    <Import Alias="WindowsApp" Name="Microsoft.WindowsApplication"/>
    <Import Alias="WebHost" Name="Microsoft.WebHost"/>
    <Import Alias="WindowsHost" Name="Microsoft.WindowsHost"/>
    <Import Alias="WebApp" Name="Microsoft.WebApplication"/>
    <Import Alias="DC" Name="Microsoft.Datacenter"/>
    <Import Alias="DA" Name="Microsoft.DistributedApplication"/>
    <Import Alias="Web" Name="Microsoft.Web"/>
    <Import Alias="Flow" Name="System.Flow"/>
    

    <!-- FtpContentClient is the client (consumer) endpoint 
        in the application layer. -->
    <EndpointDefinition Name="FtpContentClient" 
        Layer="Application" Abstract="true">
        <Description>
            <Entry Name="Description">A simple FTP application client.</Entry>
            <Entry Name="DisplayName">FtpContentClientEndpoint</Entry>
        </Description>
        <DesignData>
            <VisualStudio xmlns=
"https://schemas.microsoft.com/SystemDefinitionModel/2005/1/DesignData/VisualStudio">
                <ModelElement>
                    <Property Name="Direction" Value="Client"/> 
                </ModelElement>
            </VisualStudio>
        </DesignData>
    </EndpointDefinition>

    <!-- FtpContentServer is the server (provider) endpoint 
        in the application layer. -->
    <EndpointDefinition Name="FtpContentServer"
        Layer="Application" Abstract="true">
        <Description>
            <Entry Name="Description">A simple FTP application server.</Entry>
            <Entry Name="DisplayName">FtpContentServerEndpoint</Entry>
        </Description>

        <SettingDeclaration Name="Uri" 
            Definition="Web:Uri" 
            DefaultRead="Absolute" 
            DefaultWrite="Relative" 
            CanBeNull="true">
            <Description>The URL to the content associated
                with this endpoint. This can be specified either as
                a relative or absolute URL. If a relative URL is
                provided then it is combined with the URL from the
                host endpoint to create an absolute URL.
            </Description>
            <Facet Name="Base" />
            <Facet Name="Relative" />
            <Facet Name="Absolute" />
        </SettingDeclaration>

        <SettingValue Path="Uri@Relative" Null="true" />
        <SettingValue Path="Uri@Base" Null="true" />

        <!-- Compute the absolute Uri from the base
            and relative paths. -->
        <Flow Name="ConstructAbsoluteUri" 
            Definition="Web:CombineUrlFlow">
            <Input Name="Base" Path="Uri@Base" />
            <Input Name="Relative" Path="Uri@Relative" />
            <Output Name="Absolute" Path="Uri@Absolute" />
        </Flow>
    </EndpointDefinition>

    <!-- FtpClient is the client (consumer) endpoint
        in the application host layer. -->
    <EndpointDefinition Name="FtpClient" 
        Layer="ApplicationHost" 
        Abstract="true">
        <Description>
            <Entry Name="Description">A simple FTP client.</Entry>
            <Entry Name="DisplayName">FtpClientEndpoint</Entry>
        </Description>
        <DesignData>
            <VisualStudio xmlns=
"https://schemas.microsoft.com/SystemDefinitionModel/2005/1/DesignData/VisualStudio">
                <ModelElement>
                    <Property Name="Direction" Value="Client"/> 
                </ModelElement>
            </VisualStudio>
        </DesignData>
    </EndpointDefinition>
    
    <!-- FtpServer is the server (provider) endpoint
    in the application host layer. -->
    <EndpointDefinition Name="FtpServer" 
        Layer="ApplicationHost" Abstract="true">
        <Description>
            <Entry Name="Description">A simple FTP server.</Entry>
            <Entry Name="DisplayName">FtpServerEndpoint</Entry>
        </Description>
        <SettingDeclaration Name="Port" Definition="Int" />
        <SettingDeclaration Name="HomeDirectory"
            Definition="String" />
        <SettingDeclaration Name="ConnectionTimeout" 
            Definition="Int" />
        <SettingDeclaration Name="MaxConnections" 
            Definition="Int" />
        <SettingDeclaration Name="Uri" Definition="Web:Uri" />
        <SettingValue Path="Port">21</SettingValue>
    </EndpointDefinition>


    <!-- FtpClient containments -->
    <ContainmentDefinition Name="WebServerContainsFtpClient"
        ParentDefinition="WebHost:WebServer" 
        MemberDefinition="FtpClient" />
    <ContainmentDefinition Name="WindowsHostContainsFtpClient" 
        ParentDefinition="WindowsHost:WindowsHost" 
        MemberDefinition="FtpClient" />

    <!-- FtpServer containments -->
    <ContainmentDefinition Name="WebServerContainsFtpServer" 
        ParentDefinition="WebHost:WebServer" 
        MemberDefinition="FtpServer" />
    <ContainmentDefinition Name="WindowsHostContainsFtpServer" 
        ParentDefinition="WindowsHost:WindowsHost" 
        MemberDefinition="FtpServer" />

    <!-- FtpContentClient containments -->
    <ContainmentDefinition Name="WindowsApplicationContainsFtpContentClient" 
        ParentDefinition="WindowsApp:WindowsApplication" 
        MemberDefinition="FtpContentClient" />
    <ContainmentDefinition Name="WebApplicationContainsFtpContentClient" 
        ParentDefinition="WebApp:WebApplication" 
        MemberDefinition="FtpContentClient" />

    <!-- FtpContentServer containments -->
    <ContainmentDefinition Name="WindowsApplicationContainsFtpContentServer" 
        ParentDefinition="WindowsApp:WindowsApplication" 
        MemberDefinition="FtpContentServer" />
    <ContainmentDefinition Name="WebApplicationContainsFtpContentServer" 
        ParentDefinition="WebApp:WebApplication" 
        MemberDefinition="FtpContentServer" />

    <!-- Required host layer containments with ZoneEndpoint. -->
    <ContainmentDefinition Name="ZoneEndpointContainsFtpClient" 
        ParentDefinition="DC:ZoneEndpoint" 
        MemberDefinition="FtpClient" />
    <ContainmentDefinition Name="ZoneEndpointContainsFtpServer" 
        ParentDefinition="DC:ZoneEndpoint" 
        MemberDefinition="FtpServer" />

    <!-- Required application layer 
        containments with DistributedApplication. -->
    <ContainmentDefinition Name="DistributedAppContainsFtpContentClient" 
        ParentDefinition="DA:DistributedApplication" 
        MemberDefinition="FtpContentClient" />
    <ContainmentDefinition Name="DistributedAppContainsFtpContentServer" 
        ParentDefinition="DA:DistributedApplication" 
        MemberDefinition="FtpContentServer" />

    <!-- Specify communication relationships between the
        appropriate ftp clients and logical servers. -->
    <CommunicationDefinition Name="FtpConnection" 
        ClientDefinition="FtpClient" 
        ServerDefinition="FtpServer"/>
    <CommunicationDefinition Name="FtpContentConnection" 
        ClientDefinition="FtpContentClient" 
        ServerDefinition="FtpContentServer"/>

    <!-- Need a communication with ZoneEndpoint to connect
        in and out of the zones -->
    <CommunicationDefinition Name="FtpToZoneConnection" 
        ClientDefinition="FtpClient" 
        ServerDefinition="DC:ZoneEndpoint"/>
    <CommunicationDefinition Name="ZoneToFtpConnection" 
        ClientDefinition="DC:ZoneEndpoint" 
        ServerDefinition="FtpServer"/>
    
    <!-- Each endpoint should have a delegation to itself -->
    <DelegationDefinition Name="FtpClientDelegation" 
        ProxyDefinition="FtpClient" 
        DelegateDefinition="FtpClient"/>
    <DelegationDefinition Name="FtpServerDelegation" 
        ProxyDefinition="FtpServer" 
        DelegateDefinition="FtpServer"/>
    <DelegationDefinition Name="FtpContentClientDelegation" 
        ProxyDefinition="FtpContentClient" 
        DelegateDefinition="FtpContentClient"/>
    <DelegationDefinition Name="FtpContentServerDelegation" 
        ProxyDefinition="FtpContentServer" 
        DelegateDefinition="FtpContentServer"/>
    
    <!-- FtpClient hosts an FtpContentClient -->
    <HostingDefinition Name="FtpClientHostsFtpContentClient" 
        GuestDefinition="FtpContentClient" 
        HostDefinition="FtpClient" />
    
    <!-- FtpServer hosts an FtpContentServer -->
    <HostingDefinition Name="FtpServerHostsFtpContentServer" 
        GuestDefinition="FtpContentServer" 
        HostDefinition="FtpServer">
        <!-- Copy the base Uri from the host
            to the application layer. -->
        <Flow Name="CopyUrlBase" Definition="Flow:Copy">
            <Input Name="Source" Path="Host.Uri" />
            <Output Name="Destination" Path="Guest.Uri@Base" 
                Cast="true" />
        </Flow>
    </HostingDefinition>

</SystemDefinitionModel>


Setup


After an SDK user has compiled a .sdm file with the SDM compiler, the resulting .sdmdocument and corresponding prototype(s) and bitmap(s) need to be installed into Visual Studio. Visual Studio loads the compiled .sdmdocument files when a distributed system solution is opened or created. To instruct Distributed System Designer to load your model during startup, you need to add the full path to your model in a registry key. In Visual Studio 2005, the registry key is:


HKLM\Software\Microsoft\VisualStudio\

     8.0\EnterpriseTools\Sdm\InitializationFiles


In Visual Studio Team System 2008 Architecture Edition, the registry key is:


HKLM\Software\Microsoft\VisualStudio\

     9.0\EnterpriseTools\Sdm\InitializationFiles


There is one entry per model that needs to be loaded during startup. Consider the following when adding a value to this key for your model.


    

  • Add one value for each model you are installing.
    • 

  • The name of the value is typically the name of the file without the .sdmdocument extension. The registry data value is the full path to your model. For example, an entry for the endpoint sample would be: Microsoft.Samples.SimpleFtp = C:\SdmSamples\Microsoft.Samples.SimpleFtp.sdmdocument.
    • 

  • The name of the registry value determines the order in which the models are loaded. The models get loaded alphabetically from the registry key according to the name. For your model to be loaded correctly, all models imported by your model must be loaded before your model. To guarantee loading in the correct order, the recommendation is: add a numerical prefix to the name of your file. The prefix must be greater than the numbers of the models that your model imports. If your model doesn't import any documents, you should still use a number for consistency.
    • 



Installing a prototype


Each prototype (.adPrototype and .lddPrototype) that you create must be installed to a folder where Visual Studio can find them. In Visual Studio 2005, Visual Studio will scan for all files with the extensions .adPrototype and .lddPrototype in the directories found in the registry key:


HKLM\Software\Microsoft\VisualStudio\

     8.0\EnterpriseTools\DesignerPrototypeFolders


In Visual Studio 2005, use the following procedure to install your prototype(s):


    

  1. Create a new registry value (string value) under the prototype folders key.
    2. 

  2. Set the registry value's Name to something that will be unique such as the name of your .sdm file or a guid.
    3. 

  3. Set the registry value's Data to the folder in which your prototypes are found
    4. 



In Visual Studio Team System 2008 Architecture Edition, use the following procedure to install your prototype(s):


    

  1. Right-click anywhere in the Visual Studio Toolbox, and click Import.
    

    2. 

  2. In the Import Prototype from File dialog box, click the ellipsis (…) button next to the Prototype Filename box.
    

    3. 

  3. In the Select Prototype File dialog box, browse to and double-click the prototype file that you want to install.
    

    4. 

  4. Under Import for Users, choose one of the following:
    

      

    • To import the prototype for your use only, click Import for my use only and then click OK.
      • 

    • To import the prototype for all users on your computer, click Import for all users of this computer, and then click OK.
      • 

    

    5. 



Note  If you are running Visual Studio on Windows Server 2003 or Windows XP, you must have at least Power User permissions to import for all users. If you are running Visual Studio on Windows Vista, you must have administrator permissions to import for all users.


To create an .msi file for installing the prototype, you need the following registry keys:


    

  • To install the prototype for an individual user, use the following registry key:
    

    HKCU\Software\Microsoft\VisualStudio\
    
     9.0\EnterpriseTools\DesignerPrototypeFolders
    

    • 

  • To install the prototype for all users on the same computer, use the following registry key:
    

    HKLM\Software\Microsoft\VisualStudio\
    
     9.0\EnterpriseTools\DesignerPrototypeFolders
    

    • 



The next time Visual Studio is started, your prototype will appear in the toolbox.


Installing a bitmap for a prototype


The bitmap that is displayed next to a prototype in the Visual Studio toolbox is a 16x16 pixel .bmp file. When the prototype is created using the SDM Prototype Generator tool, a default bitmap file will be assigned to it. If you want custom bitmaps to be created with a prototype, you need to specify the location of the bitmap in the arguments to the SDM Prototype Generator tool.


See Also


How to: Create an SDM Document


Send comments about this topic to Microsoft


Build date: 10/2/2007