Announcing DSS Services

Glossary Item Box

DSS Tools and Utilities: DSS Contract Information Tool (DssInfo.exe)

DSS User Guide: Documenting Services

Microsoft Robotics Developer Studio

Send feedback on this topic

Announcing DSS Services

The DSS Contract Information Tool (DssInfo.exe) utility, which is part of Decentralized Software Services (DSS), provides a mechanism for generating an index of DSS service descriptions using Atom/RSS technology compatible with common Really Simple Syndication (RSS) readers. The utility takes as input a set of service assemblies and generates the index as a self-contained set of XML and HTML pages that can be published on a Web server as-is or customized to fit particular requirements on style and presentation.

The service descriptions referenced in the index contains information about each service including supported Decentralized Software Services Protocol message operations, service categories, service partners, and more (see also DSS Service Components) The index allows for discovery of services based on their descriptions and because it is using Atom/RSS technology, enables subscribers automatically to be notified of updates and additions. By default the service description index includes only descriptions of services, not information about the actual service implementations. However, it is possible to customize the index to add such information as necessary.

This topic describes how to generate and customize an index and how to publish and announce an index. Please see these references for examples of indexes:

1. The DSS Service Description Index Overview contains high-level data about the index and provides a reference to the actual index. In Web browsers with RSS support this reference often is indicated using an orange RSS icon.
2. DSS Service Description Index contains a description of all services shipping as part of Microsoft Robotics Developer Studio and associated packages. A detailed description of how to use the index is provided in the DSS Service Description Index Overview.
3. DSS Service Description Catalog contains a set of DSS service description indexes that have been announced to the Microsoft Robotics Developer Studio community.

Generating a DSS Service Description Index

Before generating the index, the programmer should check to see they have documented their services so that the documentation is included in the index. See the topic Documenting Services for details.

The DSS Contract Information Tool (DssInfo.exe) utility is a command line tool which can be run from a DSS command prompt. The following example creates an index of services and individual service description pages for the assembly Utility.Y2006.M08.dll. Additional assemblies can be listed separated by spaces. The generated index is saved in c:\summaries.

dssinfo /v:q /s:html /o:"c:\summaries" bin\Utility.Y2006.M08.dll

To view the generated site you can open the index.html or the index.atom.xml page directly using an appropriate viewer or editor. For example, in the above example the programmer can either open the index page directly from the hard disk as below:

start c:\Summaries\index.html

It also opens from a Web server. To view the index using the ASP.NET development server use the following command:

WebDev.WebServer /port:8080 /path:"c:\Summaries"

You can use the /mergeindex argument to add to an existing index causing the index.atom.xml file to contain the merged output. If you don't want to merge with the existing index, delete the output directory first or choose another output path.

See DSS Contract Information Tool (DssInfo.exe) for a description of all available options. 

Customizing a DSS Service Description Index

The service description index consists of a set of self-contained XML and HTML files that can be edited and or customized to fit a particular style or presentation:

1. An overview HTML page, index.html, containing a description of the index.

2. A Cascading Style Sheet, stylesheet.css, defining the style and layout for presenting the service descriptions and the overview page.

3. A set of service descriptions, an HTML page per service, e.g. 2IUVGS6CHJQ3TMQ76GQYUR7TXYLILJEU.html, describing the services includes in the index.

4. An Atom/RSS feed, index.atom.xml, acting as a searchable index of all service descriptions in the index. See Documenting Services for how to document services so that the documentation is included in the index. Using Atom/RSS allows the index to be accessed from popular RSS readers and subscribed to so that subscribers automatically can be notified about the publication of new service descriptions.

   The System.ServiceModel.Syndication.SyndicationFeed class and other classes in the System.ServiceModel.Syndication namespace introduced in .NET Framework 3.5 make it easy to programmatically read, write, and modify Atom/RSS feeds.

5. An XSLT. atom.xslt, used to provide an HTML Web interface for the feed when it is viewed in a Web browser. If the Atom/RSS feed is opened through HTTP by a browser that supports feeds then the browser’s default feed viewer will be used.

The set of files in the directory are related, linked to each other, as indicated in the figure below. The set of generated files are internally consistent which means they can be published as a whole without changing any of their internal relationships. 

Publishing an Index as an Atom/RSS feed

An index can be viewed directly as local files using a Web browser or other HTML/XML reader enabling easy inspection and/or editing before publication. However, in order for most RSS readers to recognize the index.atom.xml file as an RSS feed, it must be published through an HTTP server.

The files making up an index can be copied as-is and will remain internally consistent as long as they maintain their relative location in the directory structure. The actual publication of an index through an HTTP server depends on the mechanism and policy provided by the particular HTTP server. For example, an index can be limited to access by individuals, groups, departments, organizations, or made entirely public. Refer to the documentation for the HTTP server in question for additional details.

An index can be updated at any time simply by republishing it in the same location.

Announcing an Index

Public indexes may be announced through the DSS Service Description Catalog. The catalog is RSS enabled allowing subscribers to be automatically notified of additions and updates. To announce a new index, please follow this process:

1. Go to the DSS Service Description Catalog
2. Under the Community Content banner, click, Add New Community Content
3. If not already signed in, then sign in using your Windows Live ID or follow the process if you do not have one.
4. Fill out the community entry and mark it with the tag robotics.services. Below is an example of how an entry may look. Note that hyperlinks can be inserted by selecting text and then press Ctrl-K.
5. Once the entry has been submitted it will show up in the DSS Service Description Catalog within a few minutes.

DSS Tools and Utilities: DSS Contract Information Tool (DssInfo.exe)

DSS User Guide: Documenting Services

© 2012 Microsoft Corporation. All Rights Reserved.