DSS Service Manifests

  • Article

Glossary Item Box

Microsoft Robotics Developer Studio Send feedback on this topic

DSS Service Manifests

Decentralized Software Services (DSS) Manifests are XML files that can be read by the Manifest Loader Service (see DSS System Services) indicating a set of services that are to be started. While manifests can be loaded at any time during the life time of a DSS Node they typically are used during start-up of a node to indicate which services to start. Manifests can be indicated on the command line when starting a DSS Node using DSS Host Tool (DssHost.exe), or as part of the static DssEnvironment class. They can also be loaded using the control panel service which is one of the DSS System Services, or loaded programmatically by accessing the Manifest Loader Service directly.

DSS Manifests can be edited in any XML editor or using DSS Manifest Editor, see DSS Manifest Editor Introduction, which is a visual editor for creating and modifying manifests.

Both the DSS Host Tool (DssHost.exe) and the static DssEnvionment class accepts multiple manifests to be specified at the same time. This makes it easy to start multiple services specified in different manifests without having to manually consolidate the manifests. This is used in several of the robotics tutorials where different manifests are used to sumultaneously start generic services and services that are specific to a particular robotics platform. Manifests contain a set of records, each specifying a service to be created and possibly which other services it should partner with. The manifest loader service submits each manifest to the constructor service (see DSS System Services) which then in turn creates a service instance. Manifests are not required for creating new service instances; services can interact directly with the constructor service without first creating a manifest.

The primary purpose of manifests is two-fold:

  1. To create a set of services declaratively without modifying existing code, and
  2. To overwrite the default partners that a service should partner with when it starts up

Manifests are not recommended for complex orchestration of services. Applications that orchestrate many different services should create them programmatically. This should be accomplished either by interacting directly with the constructor service or use the partner attributes to automatically instantiate services upon activation.

Creating and Editing Manifests

For convenience a simple manifest is created as part of every DSS service project. However, services don't have to be listed in a manifest to be created and services are not limited to be listed in one manifest. Manifests can be edited with any XML editor such as the editor provided with some of the Visual Studio editions. The default manifest typically looks similar to this:

<Manifest
  xmlns="https://schemas.microsoft.com/xw/2004/10/manifest.html"
  xmlns:dssp="https://schemas.microsoft.com/xw/2004/10/dssp.html"
  xmlns:s="http://schemas.tempuri.org/2007/04/mysample.html">
  <CreateServiceList>
    <ServiceRecordType>
      <dssp:Contract>http://schemas.tempuri.org/2007/04/mysample.html</dssp:Contract>
    </ServiceRecordType>
  </CreateServiceList>
</Manifest>

This manifest contains a single ServiceRecordType element containing the contract of the service to create. Manifests can contain any number of ServiceRecordType elements, each creating a new instance of a service with the indicated contract. Below are several examples of how to specify ServiceRecordType elements for different scenarios.

Changing the Service Instance Name

DSS services have a default name indicated using the ServicePort attribute which is part of defining a service. See Service Tutorial 1 (C#) - Creating a Service. However, through the manifest this name can be overwritten with another name indicated using the Service element as illustrated below:

    <ServiceRecordType>
      <dssp:Contract>http://schemas.tempuri.org/2007/04/mysample.html</dssp:Contract>
      <dssp:Service>https://localhost/MyNewSampleName</dssp:Service>
    </ServiceRecordType>

Setting the Initial State Partner

For services that use an initial state partner, see Service Tutorial 3 (C#) - Persisting State, you can use the manifest to indicate which resource or file to use as the initial state. The initial state is indicated by adding a partner with the name StateService and a service element with the value of the Uniform Resource Identifier (URI) identifying the resource or file.

    <ServiceRecordType>
      <dssp:Contract>http://schemas.tempuri.org/2007/04/mysample.html</dssp:Contract>
      <dssp:PartnerList>
        <dssp:Partner>
          <dssp:Service>mystate.xml</dssp:Service>
          <dssp:Name>dssp:StateService</dssp:Name>
        </dssp:Partner>
      </dssp:PartnerList>
    </ServiceRecordType>

Service names are URIs and are resolved relative to the manifest itself. In the example above this means that the **mystate.**xml is in the same directory as the manifest itself.

Setting Other Partners

Other partners can be set using the exact same model as for the initial state partner with the only difference being the partner name. For example, if the service with contract http://schemas.tempuri.org/2007/04/mysample.html has a partner named MyPartner then it can be listed in the manifest like this:

    <ServiceRecordType>
      <dssp:Contract>http://schemas.tempuri.org/2007/04/mysample.html</dssp:Contract>
      <dssp:PartnerList>
        <dssp:Partner>
          <dssp:Service>https://localhost/myPartnerService</dssp:Service>
          <dssp:Name>s:MyPartner</dssp:Name>
        </dssp:Partner>
      </dssp:PartnerList>
    </ServiceRecordType>

In this case, the myPartnerService, service would either already have to be running or it could be created by listing it in a separate serviceRecordType element in the manifest.

Cross Node Manifests

Manifests are not limited to referring to services or partners running on the same DSS node. If permitted by the DSS Node Security Model services can be created and linked as partners across any number of DSS nodes. This example illustrates how to indicate that a service should partner with a service already running on another node. By using the ServiceDirectory element as part of the partner element the particular service instance URI of the remote service is looked up in the Directory Service running on the remote node.

    <ServiceRecordType>
      <dssp:Contract>http://schemas.tempuri.org/2007/04/mysample.html</dssp:Contract>
      <dssp:PartnerList>
        <dssp:Partner>
          <dssp:Name>s:MyPartner</dssp:Name>
          <dssp:ServiceDirectory>http://example.org:50000/directory</dssp:ServiceDirectory>
        </dssp:Partner>
      </dssp:PartnerList>
    </ServiceRecordType>

Service Tutorial 7 (C#) - Advanced Topics illustrates further how to create services and partnerships across DSS nodes.

Manifest Loading Results

Manifests are validated according to their XML Schema definition before they are loaded by the Manifest Loader Service causing any syntax errors to be reported. When the Manifest Loader Service has completed the load of a manifest it reports the results programmatically in the response to the request for loading the manifest. However, the manifest load results can also be inspected by pointing your Web browser at the running DSS node and find the Manifest Loader Service which typically is at the address:

https://localhost:50000/manifestloaderclient

 

 

© 2012 Microsoft Corporation. All Rights Reserved.