Documenting Services

Glossary Item Box

VPL Overview: VPL Introduction

DSS User Guide: Announcing DSS Services

C# Programming Guide: XML Documentation Comments

Visual Studio: Using IntelliSense

Microsoft Robotics Developer Studio

Send feedback on this topic

Documenting Services

This topic describes a set of mechanisms that can be used to document services. The documentation provided using these mechanisms is leveraged in different contexts including Visual Programming Language (VPL), service description indexes, and DSS proxy assemblies to provide documentation, tooltips, and icons when presented to the user. See the section Usage Examples for examples of how these mechanisms are used.

DisplayName and Description Attributes

DSS takes advantage of two attributes from the System.ComponentModel namespace to describe service state types, message operation types, and service implementation types:

• The System.ComponentModel.DisplayName attribute can be used to provide a short name or title which can be used to easily identify the item being described.
• The System.ComponentModel.Description attribute can be used to provide a text description of what the item does or means.

The attributes be can be applied to the following types and properties:

Service State

The DisplayName and Description attributes can be applied to the service state class as shown in this example:

/// <summary>
/// The ServiceTutorial10 State
/// </summary>
[DataContract()]
[DisplayName("Service Tutorial 10 State Document")]
[Description("Specifies the state document for the service Service Tutorial 10.")]
public class ServiceTutorial10State
{

The attributes can also be applied to public properties of the service state as follows:

/// <summary>
/// This property specifies the first name of a person. 
/// </summary>
[DataMember]
[DisplayName("First Name")]
[Description("Specifies the first name of a person.")]
public string FirstName
{
  get { return _firstName; }
  set { _firstName = value; }
}

The DisplayName attribute cannot be applied to public fields, only properties.

Message Operations

The DisplayName and Description attributes can be applied to message operations as well as individual message types. Below is an example of the attributes being applied to a message operation:

/// <summary>
/// The ServiceTutorial10 Get Operation returns the current state of the service
/// </summary>
[DisplayName("Get Service State")]
[Description("Gets the current state of the service.")]
public class Get : Get<GetRequestType, PortSet<ServiceTutorial10State, Fault>>
{
}

Service Implementation

Finally, the DisplayName and Description attributes can be applied to the service implementation class as illustrated in this example:

/// <summary>
/// Implementation class for ServiceTutorial10
/// </summary>
/// <remarks>
/// This tutorial shows how to document a service using several features.
/// </remarks>
[DisplayName("Service Tutorial 10: Service Documentation")]
[Description("This tutorial provides an example of how to document a service.")]
[DssCategory(TutorialCategories.ServiceTutorial)]
[Contract(Contract.Identifier)]
[DssServiceDescription("https://msdn.microsoft.com/library/cc998489.aspx")]
public class ServiceTutorial10Service : DsspServiceBase

Notice too that this example has a DssCategory attribute which is explained below under Categories.

Browsable Attribute

The System.ComponentModel.Browsable attribute specifies whether a property should be displayed in a Properties window. By default, properties are displayed but to hide the property you can apply the Browsable attribute as follows:

/// <summary>
/// This property specifies the last time this state was modified. 
/// </summary>
[DataMember]
[DisplayName("Last Modified Date")]
[Description("Specifies the last date and time the state was modified.")]
[Browsable(false)]
public DateTime LastModified
{
    get { return _lastModified; }
    set { _lastModified = value; }
}

Categories

Categories provide a mechanism for classifying and grouping services together. Services can have an open-ended number of categories enabling them to be grouped in arbitrary ways. There are two parts to categories, defining them and using them. Categories can be defined as part of a service and because they are included in a service proxy Dynamic Link Library (DLL), can be reused by other services.

Categories are defined using the Publish attribute as follows:

/// <summary>
/// Categories present a mechanism for grouping together related services.
/// </summary>
[DataContract]
[Description("Identifies a set of categories used to identify tutorials.")]
public sealed class TutorialCategories
{
    /// <summary>
    /// Indicates that the service is a DSS service tutorial.
    /// </summary>
    [DataMember]
    [Description("Indicates that the service is a DSS service tutorial.")]
    public const string ServiceTutorial = "https://schemas.microsoft.com/categories/dss/tutorial.html";

    /// <summary>
    /// Indicates that the service is a robotics tutorial.
    /// </summary>
    [Description("Indicates that the service is a robotics tutorial.")]
    [DataMember]
    public const string RoboticsTutorial = "https://schemas.microsoft.com/categories/robotics/tutorial.html";
}

The categories need to be public and marked with DataContract and DataMember so that they will be included in the Proxy.

NOTE: A category string must be in the format of a URI. You cannot use an arbitrary text string.

Categories are used by declaring them on a service implementation type using the DssCategory attribute. An example of how to use one of the categories defined above is as follows:

/// <summary>
/// Implementation class for ServiceTutorial10
/// </summary>
/// <remarks>
/// This tutorial shows how to document a service using several features.
/// </remarks>
[DisplayName("Service Tutorial 10: Service Documentation")]
[Description("This tutorial provides an example of how to document a service.")]
[DssCategory(TutorialCategories.ServiceTutorial)]
[Contract(Contract.Identifier)]
[DssServiceDescription("https://msdn.microsoft.com/library/cc998489.aspx")]
public class ServiceTutorial10Service : DsspServiceBase

Icons

Icons can be embedded as part of a service implementation DLL and as a result will also be included in the resulting proxy DLL. DSS uses a 32x32 image and a 16x16 thumbnail version of an icon. These icons are used by VPL on activity blocks to to make it easier to visually identify services. You can also use icons in XSLT pages.

Using Visual Studio you can include an icon as part of a service implementation DLL by adding it to the project and marking it as an Embedded Resource. To automatically be identified, the image name must be of the form:

• <ServiceImplementationClassName>.image.{bmp,jpg,png} for the 32x32 version
• <ServiceImplementationClassName>.thumbnail.{bmp,jpg,png} for the 16x16 version

Below is an example of a Property window in Visual Studio for an 32x32 embedded resource icon:

If the service assembly contains more than one service you must include the services namespace in the name, e.g.

• <ServiceImplementationNamespace>.<ServiceImplementationClassName>.image.{bmp,jpg,png} for the 32x32 version
• <ServiceImplementationNamespace>.<ServiceImplementationClassName>.thumbnail.{bmp,jpg,png} for the 16x16 version

When a service is loaded, the embedded resources are "mounted" into the /resources folder on the DSS node so that they can be accessed using a web browser via URLs. If you want to include an icon on page that is created using an XSLT Transform, then you need to know the full path for the source of the image tag in the XSLT code. The easiest way to find out the path is to start your service, open a web browser, and then browse to (assuming you used port 50000):

https://localhost:50000/resources

then select the link for your service and navigate through the resources until you find the icon. You can actually click on the link to the icon to view it in the web browser. 

The full path to an image icon should be of the form:

/resources/<AssemblyName>/<ServiceImplementationNamespace>.<FolderPath>.<ServiceImplementationClassName>.image.{bmp,jpg,png}

The <AssemblyName> can be found in the Project Properties. It does not include ".dll".

Note that the <ServiceImplementationNamespace> will generally be the same as the Default Namespace in the Project Properties because service projects usually contain only one service.

The <FolderPath> is optional. If you place the images in the same folder as the source files in your project, then there is no <FolderPath>. However, if you have a lot of embedded resources then it is common practise to place them into a sub-folder called Resources. In that case, the full URL must include Resources as the <FolderPath>.

You can embed any images you like into your service DLL this way, and you are not restricted to just the service icons. This allows you to decorate your web pages with additional graphics.

NOTE: If you only embed icons to your project, and do not reference any XSLT files using the EmbeddedResource or ServiceState attributes, your icons might not be mounted at runtime. To force them to be mounted you need to add a string variable to your service class with the EmbeddedResource attribute in a similar way to how you refer to an XSLT Transform, except that you refer to an icon instead. The presence of this attribute then causes all of the embedded resources to be mounted.

XML Documentation Comments

In Visual C# you can create documentation for the code by including XML tags in special comment fields in the source code directly before the code block they refer to. See (XML Documentation Comments). The XML documentation uses the /// (tripple-slash) notation which you can see in the above code examples. When you compile a C# project with documentation generation enabled, the compiler will search for all XML tags in the source code and create an XML documentation file which is used by Visual Studio for IntelliSense. See Using IntelliSense.

When enabling documentation for a DSS service project, available under the Project/Properties/Build menu in Visual Studio, all relevant XML documentation is automatically carried over to the proxy. If documentation is not enabled for a DSS service project, an XML documentation file is still generated for the proxy, however, it only contains minimal information.

Usage Examples

The following are examples of where the documentation mechanisms described in this topic show up in VPL and DSS Service Description Index:

Example illustrating effect in VPL of adding icons, DisplayName attribute, and Description attribute applied to the service implementation class:

None of the services shown in the diagram above have icons defined. If they did, then the thumbnail icons would appear in the Services panel and the image icons would appear on activity blocks.

Example showing the effect in a DSS service description index (see Announcing DSS Services) of adding icons, DisplayName attribute, and Description attribute applied to the service implementation class:

Example showing use of categories in a DSS Service Description Index where the categories are used to classify and group services:

VPL Overview: VPL Introduction

DSS User Guide: Announcing DSS Services

C# Programming Guide: XML Documentation Comments

Visual Studio: Using IntelliSense

© 2012 Microsoft Corporation. All Rights Reserved.